Back on using Microsoft’s FluidFramework for using synchronized real time data in collaborative applications. Additionally to what I covered in the first post here we will consider more enterprise-ready storage options for handling our backend data.

In fact we are going to replace one single line of code from part I which establishes the client.

const client = new TinyliciousClient();

And yes it’s about replacing one single line with a bunch of code but of course we have to talk about reliability, enterprise-readiness and last not least security. The answer will be the Azure Fluid Relay service which is in public preview right now at the time of writing this post.

Series

• FluidFramework in a collaborative app (Vote Movies)
• FluidFramework and Azure Fluid Relay service (Vote Movies)
• FluidFramework in a Teams Meeting app (Vote Movies)

Content

• Azure Fluid Relay
• Client Access
  • Insecure client
  • Azure Token Provider serverless
  • Testing Azure Function
  • Consume Azure Function
  • Azure Function and user authentication
• Azure Fluid Relay management
• Summary and outlook

Azure Fluid Relay

While in part one our server side component tinylicious was working out of the box we now have to deploy an Azure Fluid Relay service. As for typical Azure resources there’s nothing more than selecting a subscription, resource group and a name.

Client access

To establish a connection at first an azure-client package has to be installed.

npm i @fluidframework/azure-client @fluidframework/test-client-utils

For access to the Azure Fluid Relay service a shared key is needed. This can be retrieved from the access keys section.

Insecure

The easiest but not very secure way is to use the InsecureTokenProvider. As needed this will create a Json Web Token (JWT) for access to Azure Fluid Relay service.

export const connectionConfig: AzureClientProps = { connection: {
    tenantId: "34d381d*-****-****-****-*******60f90",
    tokenProvider: new InsecureTokenProvider("c51b27e2881cfc8d8101d0e1dfaea768", { id: userID }),
    orderer: "https://alfred.westeurope.fluidrelay.azure.com",
    storage: "https://historian.westeurope.fluidrelay.azure.com",
}} ;
const client = new AzureClient(connectionConfig);

While in line 2 the Tenant Id from above’s screenshot is used in line 3 it’s the Primary Key as shared secret. A userID is used as a variable as later a real login is established for a different reason. But here also a dummy user could be used.

Azure Token serverless

The disadvantage of the previous alternative is that the shared secret is published within client-side code. The better and more enterprise-ready solution is to retrieve the Json Web Token (JWT) from an Azure Function. So the shared secret is held in the Azure Function server-side.

Except the shared secret the Microsoft tutorial “How to implement the service token provider” handles the other variables as parameters. In this implementation I put some of them to the configuration or even hardcoded such as the tenant ID and the scope. This helps for simplicity reasons but of courses does not enable a more flexible or multi-tenant scenario. The main function code looks like this:

import { AzureFunction, Context, HttpRequest } from "@azure/functions"
import { ScopeType } from "@fluidframework/azure-client";
import { generateToken } from "@fluidframework/azure-service-utils";
import { getSecret } from "./keyVault";
const httpTrigger: AzureFunction = async function (context: Context, req: HttpRequest): Promise<void> {
  const tenantId = process.env.TENANTID;
  const documentId = (req.query.documentId || (req.body && req.body.documentId)) as string | undefined;
  const userId = (req.query.userId || (req.body && req.body.userId)) as string;
  const userName = (req.query.userName || (req.body && req.body.userName)) as string;
  const scopes = [ScopeType.DocRead, ScopeType.DocWrite, ScopeType.SummaryWrite]; // "doc:read", "doc:write", "summary:write"
  if (!tenantId) {
    context.res = {
      status: 400,
      body: "No tenantId provided in query params",
    };
    return;
  }
  const key = await getSecret("AzureFluidRelay"); // Name of KeyVault secret
  if (!key) {
    context.res = {
      status: 404,
      body: `No key found for the provided tenantId: ${tenantId}`,
    };
    return;
  }
  let user = { name: userName, id: userId };
  // Will generate the token and returned by an ITokenProvider implementation to use with the AzureClient.
  const token = generateToken(
    tenantId,
    key,
    scopes ?? [ScopeType.DocRead, ScopeType.DocWrite, ScopeType.SummaryWrite],
    documentId,
    user
  );
  context.res = {
    status: 200,
    body: token
  };
};
export default httpTrigger;

For a full solution running at the point of writing, refer to my GitHub repo for this Azure Function. Also as the referred Microsoft tutorial was not up to date and having several errors / inconsistencies at the same point of time.

Testing

As the Azure Function runs anonymously it can simply be tested:
Run your function Url with following query parameters
https://<YourFunctionUrl>.azurewebsites.net/api/FluidTokenProvider?userName=markus&userId=markus@mmsharepoint.onmicrosoft.com&documentId=a0004aeb-272a-4dc2-b28b-51830cef61d7

This might produce a response like the following:

{
  "alg": "HS256",
  "typ": "JWT"
}.{
  "documentId": "a0004aeb-272a-4dc2-b28b-51830cef61d7",
  "scopes": [
    "doc:read",
    "doc:write",
    "summary:write"
  ],
  "tenantId": "34d381d*-****-****-****-*******60f90",
  "user": {
    "name": "markus",
    "id": "markus@mmsharepoint.onmicrosoft.com"
  },
  "iat": 1654865714,
  "exp": 1654869314,
  "ver": "1.0",
  "jti": "b21cd59f-3efa-4cc0-a8fd-6cd61f5429df"
}.[Signature]

Consume it

As now the Azure function is running anonymously it simply can be consumed by our existing client-side code. This looks like the following:

export const connectionConfig: AzureClientProps = { connection: {
    tenantId: process.env.REACT_APP_TENANT_ID!,
    tokenProvider: new AzureFunctionTokenProvider(process.env.REACT_APP_AZURETOKENURL + "/api/FluidTokenProvider", { userId: userID, userName: "Test User" }),
    orderer: process.env.REACT_APP_ORDERER!,
    storage: process.env.REACT_APP_STORAGE!,
}}
const client = new AzureClient(connectionConfig);

In line 3 there is the Azure Function url from above coming from environment variables now. documentId is missing here, this will automatically be added by the corresponding AzureClient methods (getContainer(…) or createContainer() ) as the documentId is the same like the id of the container. userID (and also the optional userName could) is handled like above coming from a user login.

Azure Function and user authentication

Authentication against Azure Fluid Relay service always works with a shared secret. To implement user authentication you can use the workaround that the user authentication works against the Azure function which then will provide shared secret only to authenticated and authorized users. Two things need to be considered for that. At first the Azure Function needs to be configured to only accept calls from authenticated users. Next the client-side call needs to be executed in an authenticated manner. To configure the Azure Function switch to the authentication tab and require authentication while adding Microsoft as an identity provider.

Next the created corresponding app registration needs to be configured. From the authentication tab click the app registration under Microsoft identity provider:

What’s needed is a single page application with a corresponding redirect URI. In the given example only with a local test URL:

Now we can login to our application and use the received identity token to authenticate against our AzureTokenProvider function. Microsoft’s sample AzureTokenProvider does not implement authentication but we can take the open source code and further adjust it. The sample code can be found in Microsoft’s tutorial which simply can be enhanced by additionally accepting an identity token and use that to authenticate against the Azure Function:

export class AzureFunctionTokenProviderSec implements ITokenProvider {
    constructor(
        private readonly azFunctionUrl: string,
        private readonly authToken: string,
        private readonly user?: Pick,        
    ) { }
    public async fetchOrdererToken(tenantId: string, documentId?: string): Promise {
        return {
            jwt: await this.getToken(tenantId, documentId),
        };
    }
    public async fetchStorageToken(tenantId: string, documentId: string): Promise {
        return {
            jwt: await this.getToken(tenantId, documentId),
        };
    }
    private async getToken(tenantId: string, documentId: string | undefined): Promise {
        const response = await axios.get(this.azFunctionUrl, {
            headers: {
                Authorization: `Bearer ${this.authToken}`
            },
            params: {
                tenantId,
                documentId,
                userId: this.user?.userId,
                userName: this.user?.userName,
                additionalDetails: this.user?.additionalDetails,
            },
        });
        return response.data as string;
    }
}

So the difference can be found in line 4 and line 19-21. The constructor accepts an identity token and the getToken function uses it for authentication. Another difference now can be found in the utils class. If the getFluidContainer function receives an identity token It will simply exchange the AzureFunctionTokenProvider.

export async function getFluidContainer(userId: string, authToken?: string): Promise {
  userID = userId;
  if (authToken !== undefined) {
    connectionConfig.connection.tokenProvider = new AzureFunctionTokenProviderSec(process.env.REACT_APP_AZURETOKENURL + "/api/FluidTokenProvider", authToken, { userId: userID, userName: "Test User" });
  }  
  const client = new AzureClient(connectionConfig);
  let containerId: string = window.location.hash.substring(1);
  if (!containerId) {
    containerId = await createContainer(client);
    window.location.hash = containerId;
  }
  const container = await getContainer(client, containerId);
  return container;
};

So how do we get this identity token? In our app there is a specific login component. For this login component I am using MSAL.js 2.0 (npm install @azure/msal-browser) which I already introduced here. Once the user logs in a callback function is called:

const loginUser = async () => {
    const loginResponse = await msalInstance.loginPopup({ scopes:[] });
    props.login(loginResponse.account?.name!, loginResponse.account?.username!, loginResponse.idToken);
};

The callback function now retrieves the userID, userName and the idToken. Having that the fluidContainer can be instantiated:

const login = async (name: string, userName: string, idToken: string) => {
    setUserDisplayName(name);    
    setUserLoggedin(true);
    setUserID(userName);
    const container: IFluidContainer = await getFluidContainer(userName, idToken);
    setFluidContainer(container);
};

Here only a valid user authentication was considered. Of course you can furthermore use Azure AD security group based authorization which I showed client-side here or server-side here.

Azure Fluid Relay management

Of course many containers might get created over time And there might be a need for a proper lifecycle management. Here are some methods with Microsoft Azure CLI for that. The first one is for listing all available containers:

az rest --method get --uri https://management.azure.com/subscriptions/<subscriptionId>/resourcegroups/<resourceGroupName>/providers/Microsoft.FluidRelay/FluidRelayServers/<frsResourceName>/FluidRelayContainers?api-version=<apiVersion>

This might result in an output like this:

[
...
{
      "id": "/subscriptions/*9ba8c0*-****-****-****-**c081cd91**/resourceGroups/DefaultMMsharepoint/providers/Microsoft.FluidRelay/fluidRelayServers/mmdemorelay/fluidRelayContainers/72bb13b9-55e6-4007-b11c-0607c3f94f38",
      "name": "72bb13b9-55e6-4007-b11c-0607c3f94f38",
      "properties": {
        "frsContainerId": "72bb13b9-55e6-4007-b11c-0607c3f94f38",
        "frsTenantId": "34d381d*-****-****-****-*******60f90"
      },
      "resourceGroup": "DefaultMMsharepoint",
      "type": "Microsoft.FluidRelay/fluidRelayServers/fluidRelayContainers"
    }
  ]

That one now can be deleted quite similar to the get command:

az rest --method delete --uri https://management.azure.com/subscriptions/9ba8c0*-****-****-****-**c081cd91**/resourcegroups/DefaultMMsharepoint/providers/Microsoft.FluidRelay/FluidRelayServers/mmDemoRelay/FluidRelayContainers/72bb13b9-55e6-4007-b11c-0607c3f94f3?api-version=2021-08-30-preview

For further reference refer to the Microsoft documentation.

Summary and outlook

The application now looks only slightly different than in the first part. The main difference is, that it only establishes a container after a successful user login. This also works with different users of course. But the rest, especially the real-time data synchronization finally stays the same:

While in the first part the client site usage of Microsoft FluidFramework was shown, in this part a more professional storage option with Microsoft Azure Fluid Relay service was described in detail. Especially the necessity for secure authentication was explained with several facets. In my opinion this could be further improved out-of-the-box by Microsoft Azure with serverless components. Currently too much coding still necessary. But remember that we are talking about public preview technology at the time of writing this post.

Next we are going to try to use both described parts, client-side and server-side storage option inside a Microsoft Teams application. Finally for your reference you can meanwhile find both of my code repositories in my GitHub:

• Azure Function Token Provider
• Fluid Vote Movie

Markus is a SharePoint architect and technical consultant with focus on latest technology stack in Microsoft 365 Development. He loves SharePoint Framework but also has a passion for Microsoft Graph and Teams Development. He works for Avanade as an expert for Microsoft 365 Dev and is based in Munich. In 2021 he received his first Microsoft MVP award in M365 Development for his continuous community contributions. Although if partially inspired by his daily work opinions are always personal.