Merge pull request #177531 from tylerbutler/az-func-tp

Updates to TokenProvider article

Author: denrea

articles/azure-fluid-relay/how-tos/azure-function-token-provider.md

@@ -17,70 +17,20 @@ fluid.url: https://fluidframework.com/docs/build/tokenproviders/
 
 In the [Fluid Framework](https://fluidframework.com/), TokenProviders are responsible for creating and signing tokens that the `@fluidframework/azure-client` uses to make requests to the Azure Fluid Relay service. The Fluid Framework provides a simple, insecure TokenProvider for development purposes, aptly named **InsecureTokenProvider**. Each Fluid service must implement a custom TokenProvider based on the particulars service's authentication and security considerations.
 
-## Implementing your own TokenProvider class
+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. TokenProviders must know the secret key to sign requests, but the secret key cannot be included in client code.
 
-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. 
+## Implement an Azure Function to sign tokens
 
-TokenProviders must know the secret key to sign requests, but the secret key cannot be included in client code. TokenProviders contact the Fluid server at runtime to securely obtain the secret key without exposing it to the client. This is accomplished through two separate API calls: `fetchOrdererToken` and `fetchStorageToken`. They are responsible for fetching the orderer and storage URLs from the host respectively. Both functions return `TokenResponse` objects representing the token value.
+One option for building a secure token provider is to create HTTPS endpoint and create a TokenProvider implementation that makes authenticated HTTPS requests to that endpoint to retrieve tokens. This enables you to store the *tenant secret key* in a secure location, such as [Azure Key Vault](../../key-vault/general/overview.md).
 
-## TokenProvider class example
+The complete solution has two pieces:
 
-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 would then call the Azure Function to generate tokens.
+1. An HTTPS endpoint that accepts requests and returns Azure Fluid Relay tokens.
+1. An ITokenProvider implementation that accepts a URL to an endpoint, then makes requests to that endpoint to retrieve tokens.
 
-This example implements that pattern in a class called **AzureFunctionTokenProvider**. It accepts the URL to your Azure Function, `userId` and`userName`. This specific implementation is also provided for you as an export from the `@fluidframework/azure-client` package.
+### Create an endpoint for your TokenProvider using Azure Functions
 
-```typescript
-import { ITokenProvider, ITokenResponse } from "@fluidframework/azure-client";
-
-export class AzureFunctionTokenProvider implements ITokenProvider {
-  constructor(
-    private readonly azFunctionUrl: string,
-    private readonly userId: string,
-    private readonly userName: string,
-  );
-
-  public async fetchOrdererToken(tenantId: string, documentId: string): Promise<ITokenResponse> {
-        return {
-            jwt: await this.getToken(tenantId, documentId),
-        };
-    }
-
-    public async fetchStorageToken(tenantId: string, documentId: string): Promise<ITokenResponse> {
-        return {
-            jwt: await this.getToken(tenantId, documentId),
-        };
-    }
-}
-```
-
-To ensure that the tenant secret key is kept secure, it is stored in a secure backend location and is only accessible from within the Azure Function. One way to fetch a signed token is to make a `GET` request to your Azure Function, providing the `tenantID` and `documentId`, and `userID`/`userName`. The Azure Function is responsible for the mapping between the tenant ID and a tenant key secret to appropriately generate and sign the token such that the Azure Fluid Relay service will accept it.
-
-```typescript
-private async getToken(tenantId: string, documentId: string): Promise<string> {
-    const params = {
-        tenantId,
-        documentId,
-        userId: this.userId,
-        userName: this.userName,
-    };
-    const token = this.getTokenFromServer(params);
-    return token;
-}
-```
-
-The example below uses the [`axios`](https://www.npmjs.com/package/axios) library to make HTTP requests. You can use other libraries or approaches to making an HTTP request.
-
-```typescript
-private async getTokenFromServer(input: any): Promise<string> {
-    return axios.get(this.azFunctionUrl, {
-        params: input,
-    }).then((response) => {
-        return response.data as string;
-    }).catch((err) => {
-        return err as string;
-    });
-}
-```
+[Azure Functions](../../azure-functions/functions-overview.md) are a fast way to create such an HTTPS endpoint. The example below implements that pattern in a class called **AzureFunctionTokenProvider**. It accepts the URL to your Azure Function, `userId` and`userName`. This specific implementation is also provided for you as an export from the `@fluidframework/azure-client` package.
 
 This example demonstrates how to create your own **HTTPTrigger Azure Function** that fetches the token by passing in your tenant key.
 
@@ -89,7 +39,7 @@ import { AzureFunction, Context, HttpRequest } from "@azure/functions";
 import { ScopeType } from "@fluidframework/azure-client";
 import { generateToken } from "@fluidframework/azure-service-utils";
 
-//Replace "myTenantKey" with your key here.
+// NOTE: retrieve the key from a secure location.
 const key = "myTenantKey";
 
 const httpTrigger: AzureFunction = async function (context: Context, req: HttpRequest): Promise<void> {
@@ -105,20 +55,23 @@ const httpTrigger: AzureFunction = async function (context: Context, req: HttpRe
             status: 400,
             body: "No tenantId provided in query params",
         };
+        return;
     }
 
     if (!key) {
         context.res = {
             status: 404,
             body: `No key found for the provided tenantId: ${tenantId}`,
         };
+        return;
     }
 
     if (!documentId) {
         context.res = {
             status: 400,
             body: "No documentId provided in query params"
         };
+        return;
     }
 
     let user = { name: userName, id: userId };
@@ -141,8 +94,67 @@ const httpTrigger: AzureFunction = async function (context: Context, req: HttpRe
 export default httpTrigger;
 ```
 
-The `generateToken` function generates a token for the given user that is signed using the tenant's secret key. This allows the token to be returned to the client without ever exposing the secret itself to it. Instead, the token is generated using it to provide scoped access to the given document. This token can be returned by an `ITokenProvider` implementation to use with the `AzureClient`.
+The `generateToken` function, found in the `@fluidframework/azure-service-utils` package, generates a token for the given user that is signed using the tenant's secret key. This enables the token to be returned to the client without exposing the secret. Instead, the token is generated server-side using the secret to provide scoped access to the given document. The example ITokenProvider below makes HTTP requests to this Azure Function to retrieve tokens.
+
+### Deploy the Azure Function
+
+Azure Functions can be deployed in several ways. See the **Deploy** section of the [Azure Functions documentation](../../azure-functions/functions-continuous-deployment.md) for more information about deploying Azure Functions.
+
+### Implement the TokenProvider
+
+TokenProviders can be implemented in many ways, but must implement two separate API calls: `fetchOrdererToken` and `fetchStorageToken`. These APIs are responsible for fetching tokens for the Fluid orderer and storage services respectively. Both functions return `TokenResponse` objects representing the token value. The Fluid Framework runtime calls these two APIs as needed to retrieve tokens.
 
+
+To ensure that the tenant secret key is kept secure, it is stored in a secure backend location and is only accessible from within the Azure Function. To retrieve tokens, you need to make a `GET` or `POST` request to your deployed Azure Function, providing the `tenantID` and `documentId`, and `userID`/`userName`. The Azure Function is responsible for the mapping between the tenant ID and a tenant key secret to appropriately generate and sign the token.
+
+This example implementation below uses the [axios](https://www.npmjs.com/package/axios) library to make HTTP requests. You can use other libraries or approaches to making an HTTP request from server code.
+
+```typescript
+import { ITokenProvider, ITokenResponse } from "@fluidframework/routerlicious-driver";
+import axios from "axios";
+import { AzureMember } from "./interfaces";
+
+/**
+ * Token Provider implementation for connecting to an Azure Function endpoint for
+ * Azure Fluid Relay token resolution.
+ */
+export class AzureFunctionTokenProvider implements ITokenProvider {
+    /**
+     * Creates a new instance using configuration parameters.
+     * @param azFunctionUrl - URL to Azure Function endpoint
+     * @param user - User object
+     */
+    constructor(
+        private readonly azFunctionUrl: string,
+        private readonly user?: Pick<AzureMember, "userId" | "userName" | "additionalDetails">,
+    ) { }
+
+    public async fetchOrdererToken(tenantId: string, documentId?: string): Promise<ITokenResponse> {
+        return {
+            jwt: await this.getToken(tenantId, documentId),
+        };
+    }
+
+    public async fetchStorageToken(tenantId: string, documentId: string): Promise<ITokenResponse> {
+        return {
+            jwt: await this.getToken(tenantId, documentId),
+        };
+    }
+
+    private async getToken(tenantId: string, documentId: string | undefined): Promise<string> {
+        const response = await axios.get(this.azFunctionUrl, {
+            params: {
+                tenantId,
+                documentId,
+                userId: this.user?.userId,
+                userName: this.user?.userName,
+                additionalDetails: this.user?.additionalDetails,
+            },
+        });
+        return response.data as string;
+    }
+}
+```
 ## See also
 
 - [Add custom data to an auth token](connect-fluid-azure-service.md#adding-custom-data-to-tokens)