Authentication & authorization

Security is critical to modern web applications. Fluid Framework, as a part of your web application architecture, is an important piece of infrastructure to secure. Fluid Framework is a layered architecture, and auth-related concepts are implemented based on the Fluid service it’s connecting to. This means that the specifics of authentication will differ based on the Fluid service.

The information below is based on Azure Fluid Relay service. Other Fluid services may differ. See Available Fluid services for more information.

Azure Fluid Relay service

Important

The information below assumes you are onboarded to Azure Fluid Relay service. Azure Fluid Relay service is currently in Private Preview.

Each Azure Fluid Relay service tenant you create is assigned a tenant ID and its own unique tenant secret key.

The secret key is a shared secret. Your app/service knows it, and the Azure Fluid Relay service knows it. Since the tenant secret key is uniquely tied to your tenant, using it to sign requests guarantees to the Azure Fluid Relay service that the requests are coming from an authorized user of the tenant.

In summary, the secret key is how the Azure Fluid Relay service knows that requests are coming from your app or service. This is critical, because once the Azure Fluid Relay service can trust that it’s your app making the requests, it can trust the data you send. This is also why it’s important that the secret is handled securely.

Warning

Anyone with access to the secret can impersonate your application when communicating with Azure Fluid Relay service.

Now you have a mechanism to establish trust. Your app can sign some data, send it to the Azure Fluid Relay service, and the service can validate whether the data is signed properly, and if so, it can trust it. Fortunately, there’s an industry standard method for encoding authentication and user-related data with a signature for verification: JSON Web Tokens (JWTs).

JWTs and Azure Fluid Relay service

Note

The specifics of JWTs are beyond the scope of this article. For more details about the JWT standard see https://jwt.io/introduction.

JSON Web Tokens are a signed bit of JSON that can include additional information about the rights conferred by the JWT. The Azure Fluid Relay service uses signed JWTs for establishing trust with calling clients.

The next question is: what data should your app send?

The app must send the tenant ID so that Azure Fluid Relay service can look up the right secret key to validate the request. The app also must send the container ID (called documentId in the JWT) so Azure Fluid Relay service knows which container the request is about. Finally, the app must also set the scopes (permissions) that the request is permitted to use – this enables you to establish your own user permissions model if you wish.

 1{
 2  "alg": "HS256",
 3  "typ": "JWT"
 4}.{
 5  "documentId": "azureFluidDocumentId",
 6  "scopes": [ "doc:read", "doc:write", "summary:write" ],
 7  "user": {
 8    "name": "TestUser",
 9    "id": "Test-Id-123"
10  },
11  "iat": 1599098963,
12  "exp": 1599098963,
13  "tenantId": "AzureFluidTenantId",
14  "ver": "1.0"
15}.[Signature]

Tip

Note that the token also includes user information (see lines 7-9 above). You can use this to augment the user information that is automatically available to Fluid code using the audience feature. See Adding custom data to tokens for more information.

Every request to Azure Fluid Relay must be signed with a valid JWT. The Azure Fluid Relay documentation contains additional details about how to sign the token. Fluid delegates the responsibility of creating and signing these tokens to a token provider.

More information

The token provider

A token provider is responsible for creating and signing tokens that the @fluidframework/azure-client uses to make requests to the Azure Fluid Relay service. You are required to provide your own secure token provider implementation. However, Fluid provides an InsecureTokenProvider that accepts your tenant secret, then locally generates and returns a signed token. This token provider is useful for testing, but in production scenarios you must use a secure token provider.

A secure serverless token provider

One option for building a secure token provider is to create a serverless Azure Function and expose it as a token provider. This enables you to store the tenant secret key on a secure server. Your application calls the Azure Function to generate tokens rather than signing them locally like the InsecureTokenProvider does.

Adding custom data to tokens

🚧 Coming soon

This article is not yet written.

Connecting user auth to Fluid service auth

You do this in your token provider. For example, you could make your Azure Function token provider authenticated. If an application tries to call the Function it would fail unless authenticated with your auth system. If you’re using Azure Active Directory, for example, you might create an AAD application for your Azure Function, and tie it to your organization’s auth system.

In this case the user would sign into your application using AAD, through which you would obtain a token to use to call your Azure Function. The Azure Function itself behaves the same, but it’s now only accessible to people who have also authenticated with AAD.

Since the Azure Function is now your entrypoint into obtaining a valid token, only users who have properly authenticated to the Function will then be able to relay that token to the Azure Fluid Relay service from their client application. This two-step approach enables you to use your own custom authentication process in conjunction with the Azure Fluid Relay service.