Azure Fluid Relay token contract

Article
11/21/2022

Requests sent to Azure Fluid Relay should contain a JWT token in the authorization header. This token should be signed by the tenant key.

Claims

JWTs (JSON Web Tokens) are split into three parts:

Header - Provides information about how to validate the token, including information about the type of token and how it was signed.
Payload - Contains all the important data about the user or app that is attempting to call your service.
Signature - Is the raw material used to validate the token.

Each part is separated by a period (.) and separately Base64 encoded.

Header claims

Claim	Format	Description
alg	string	The algorithm used to sign the token. For example, "HS256"
typ	string	This value should always be “JWT.”

Payload claims

Claim	Format	Description
documentId	string	Generated by Azure Fluid Relay (AFR) service. Identifies the document for which the token is being generated.
scope	string[]	Identifies the permissions required by the client on the document or summary. For every scope, you can define the permissions you want to give to the client.
tenantId	string	Identifies the tenant.
user	JSON	Identifies users of your application. It can be used by your application to identify your users by using the Fluid Framework Audience. `{ id: <user_id>, name: <user_name>, additionalDetails: { email: <email>, date: <date>, }, }`
iat	number, a UNIX timestamp	"Issued At" indicates when the authentication for this token occurred.
exp	number, a UNIX timestamp	The "exp" (expiration time) claim identifies the expiration time on or after which the JWT must not be accepted for processing. The token lifetime can't be more than 1 hour.
ver	string	Indicates the version of the access token. Must be `1.0` .
jti	string	Optional. The "jti" (JWT ID) claim provides a unique identifier for the JWT. The identifier value MUST be assigned in a manner that ensures that there is a negligible probability that the same value will be accidentally assigned to a different data object. We encourage you to use this claim to avoid failures due to usage of same token for document creation.

A sample Azure Fluid Relay token

{ 
  "alg": "HS256",  
  "typ": "JWT" 
}.{ 
  "documentId": "746c4a6f-f778-4970-83cd-9e21bf88326c", 
  "scopes": [ "doc:read", "doc:write", "summary:write" ],   
  "iat": 1599098963,  
  "exp": 1599098963,  
  "tenantId": "AzureFluidTenantId",  
  "ver": "1.0",
  "jti": "d7cd6602-2179-11ec-9621-0242ac130002"
}.[Signature]

How can you generate an Azure Fluid Relay token?

You can use the jsonwebtoken npm package and sign your token using this method.

export function getSignedToken(
    tenantId: string,
    documentId: string,
    tokenLifetime: number = 60 * 60,
    ver: string = "1.0") {
        jwt.sign(
            {
                documentId, 
                user: {
                    displayName: "displayName", 
                    id: "userId", 
                    name: "userName" 
                }, 
                scopes: ["doc:read", "doc:write", "summary:write"], 
                iat: Math.round((new Date()).getTime() / 1000), 
                exp: Math.round((new Date()).getTime() / 1000) + tokenLifetime, //set the expiry date based on your needs but max-limit is one hour.
                tenantId, 
                ver,
                jti: uuid(), 
            },
            "<tenant_key>");
    }

Share via