Como gravar um TokenProvider com uma função do Azure

Observação

Essa versão prévia é fornecida sem contrato de nível de serviço e não é recomendada para cargas de trabalho de produção. Alguns recursos podem não ter suporte ou podem ter restrição de recursos.

No Fluid Framework, TokenProviders são responsáveis por criar e assinar tokens que o @fluidframework/azure-client usa para fazer solicitações ao serviço do Azure Fluid Relay. O Fluid Framework fornece um TokenProvider simples e não seguro para fins de desenvolvimento, chamado adequadamente de InsecureTokenProvider. Cada serviço do Fluid precisa implementar um TokenProvider personalizado com base nas considerações de segurança e autenticação do serviço específico.

Cada recurso do Azure Fluid Relay que você cria recebe uma ID de locatário e a própria chave secreta exclusiva do locatário. A chave secreta é um segredo compartilhado. Tanto seu aplicativo/serviço quanto o serviço do Azure Fluid Relay o conhecem. TokenProviders precisam conhecer a chave secreta para assinar solicitações, mas a chave secreta não pode ser incluída no código do cliente.

Implementar uma função do Azure para assinar tokens

Uma opção para compilar um provedor de token seguro é criar um ponto de extremidade HTTPS e criar uma implementação TokenProvider que faz solicitações HTTPS autenticadas para esse ponto de extremidade para recuperar tokens. Esse caminho permite que você armazene a chave secreta do locatário em um local seguro, como Azure Key Vault.

A solução completa tem duas partes:

1. Um ponto de extremidade HTTPS que aceita solicitações e retorna tokens do Azure Fluid Relay.
2. Uma implementação de ITokenProvider que aceita uma URL para um ponto de extremidade e faz solicitações para esse ponto de extremidade para recuperar tokens.

Criar um ponto de extremidade para o TokenProvider usando o Azure Functions

Usar o Azure Functions é uma maneira rápida de criar esse ponto de extremidade HTTPS.

Este exemplo demonstra como criar sua Função do Azure HTTPTrigger que busca o token passando sua chave de locatário.

TypeScript

import { AzureFunction, Context, HttpRequest } from "@azure/functions";
import { ScopeType } from "@fluidframework/azure-client";
import { generateToken } from "@fluidframework/azure-service-utils";

// NOTE: retrieve the key from a secure location.
const key = "myTenantKey";

const httpTrigger: AzureFunction = async function (context: Context, req: HttpRequest): Promise<void> {
    // tenantId, documentId, userId and userName are required parameters
    const tenantId = (req.query.tenantId || (req.body && req.body.tenantId)) as string;
    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 = (req.query.scopes || (req.body && req.body.scopes)) as ScopeType[];

    if (!tenantId) {
        context.res = {
            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;
    }

    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,
        documentId,
        key,
        scopes ?? [ScopeType.DocRead, ScopeType.DocWrite, ScopeType.SummaryWrite],
        user
    );

    context.res = {
        status: 200,
        body: token
    };
};

export default httpTrigger;

A função generateToken, encontrada no pacote @fluidframework/azure-service-utils, gera um token para o usuário que é assinado usando a chave secreta do locatário. Esse método permite que o token seja retornado ao cliente sem expor o segredo. Em vez disso, o token é gerado no lado do servidor usando o segredo para fornecer acesso com escopo ao documento fornecido. O exemplo de ITokenProvider abaixo faz solicitações HTTP para essa função do Azure para recuperar tokens.

C#

using System;
using System.IO;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.AspNetCore.Http;
using Microsoft.Extensions.Logging;
using Newtonsoft.Json;
using Newtonsoft.Json.Linq;
using System.Text;

using Microsoft.IdentityModel.Tokens;
using System.IdentityModel.Tokens.Jwt;

namespace dotnet_tokenprovider_functionsapp
{
    public static class AzureFunction
    {
        // NOTE: retrieve the key from a secure location.
        private static readonly string key = "myTenantKey";

        [FunctionName("AzureFunction")]
        public static async Task<IActionResult> Run(
            [HttpTrigger(AuthorizationLevel.Function, "get", Route = null)] HttpRequest req, ILogger log)
        {
            string content = await new StreamReader(req.Body).ReadToEndAsync();
            JObject body = !string.IsNullOrEmpty(content) ? JObject.Parse(content) : null;

            string tenantId = (req.Query["tenantId"].ToString() ?? body["tenantId"]?.ToString()) as string;
            string documentId = (req.Query["documentId"].ToString() ?? body["documentId"]?.ToString() ?? null) as string;
            string userId = (req.Query["userId"].ToString() ?? body["userId"]?.ToString()) as string;
            string userName = (req.Query["userName"].ToString() ?? body["userName"]?.ToString()) as string;
            string[] scopes = (req.Query["scopes"].ToString().Split(",") ?? body["scopes"]?.ToString().Split(",") ?? null) as string[];

            if (string.IsNullOrEmpty(tenantId))
            {
                return new BadRequestObjectResult("No tenantId provided in query params");
            }

            if (string.IsNullOrEmpty(key))
            {
                return new NotFoundObjectResult($"No key found for the provided tenantId: ${tenantId}");
            }

            //  If a user is not specified, the token will not be associated with a user, and a randomly generated mock user will be used instead
            var user = (string.IsNullOrEmpty(userName) || string.IsNullOrEmpty(userId)) ? 
                new { name = Guid.NewGuid().ToString(), id = Guid.NewGuid().ToString() } :
                new { name = userName, id = userId };

            // Will generate the token and returned by an ITokenProvider implementation to use with the AzureClient.
            string token = GenerateToken(
                tenantId,
                key,
                scopes ?? new string[] { "doc:read", "doc:write", "summary:write" },
                documentId,
                user
            );

            return new OkObjectResult(token);
        }

        private static string GenerateToken(string tenantId, string key, string[] scopes, string? documentId, dynamic user, int lifetime = 3600, string ver = "1.0")
        {
            string docId = documentId ?? "";
            DateTime now = DateTime.Now;

            SigningCredentials credentials = new SigningCredentials(new SymmetricSecurityKey(Encoding.UTF8.GetBytes(key)), SecurityAlgorithms.HmacSha256);

            JwtHeader header = new JwtHeader(credentials);
            JwtPayload payload = new JwtPayload
            {
                { "documentId", docId },
                { "scopes", scopes },
                { "tenantId", tenantId },
                { "user", user },
                { "iat", new DateTimeOffset(now).ToUnixTimeSeconds() },
                { "exp", new DateTimeOffset(now.AddSeconds(lifetime)).ToUnixTimeSeconds() },
                { "ver", ver },
                { "jti", Guid.NewGuid() }
            };

            JwtSecurityToken token = new JwtSecurityToken(header, payload);

            return new JwtSecurityTokenHandler().WriteToken(token);
        }
    }
}

A função GenerateToken é criada com base no pacote npm @fluidframework/azure-service-utils e gera um token para o usuário especificado que é assinado usando a chave secreta do locatário. Essa função permite que o token seja retornado ao cliente sem expor o segredo. Em vez disso, o token é gerado no lado do servidor usando o segredo para fornecer acesso com escopo ao documento fornecido. O exemplo de ITokenProvider abaixo faz solicitações HTTP para essa função do Azure para recuperar tokens.

Implantar a Azure Function

O Azure Functions pode ser implantado de várias maneiras. Para obter mais informações, confira a seção Implantar da documentação do Azure Functions para obter mais informações sobre a implantação do Azure Functions.

Implementar o TokenProvider

Os TokenProviders podem ser implementados de várias maneiras, mas devem implementar duas chamadas à API separadas: fetchOrdererToken e fetchStorageToken. Essas APIs são responsáveis por buscar tokens para o Fluid solicitado e os serviços de armazenamento, respectivamente. As duas funções retornam objetos TokenResponse que representam o valor do token. O runtime do Fluid Framework chama essas duas APIs conforme necessário para recuperar tokens. Observe que, embora o código do aplicativo esteja usando apenas um ponto de extremidade de serviço para estabelecer conectividade com o serviço do Azure Fluid Relay, o cliente do Azure internamente em conjunto com o serviço converte esse ponto de extremidade em um par de pontos de extremidade de armazenamento e ordenador. Esses dois pontos de extremidade são usados desse ponto em diante para essa sessão e é por isso que você precisa implementar as duas funções separadas para buscar tokens, uma para cada.

Para garantir que a chave secreta do locatário seja mantida em segurança, ela é armazenada em um local de back-end seguro e só pode ser acessada de dentro da Função do Azure. Para recuperar tokens, você precisa fazer uma solicitação GET ou POST para seu Azure Functions implantado, fornecendo o tenantID, documentId e userID/userName. O Azure Functions é responsável pelo mapeamento entre a ID do locatário e um segredo de chave do locatário para gerar e assinar adequadamente o token.

A implementação de exemplo a seguir lida com a realização dessas solicitações para sua Função do Azure. Ela usa a biblioteca axios para fazer solicitações HTTP. Você pode usar outras bibliotecas ou abordagens para fazer uma solicitação HTTP do código do servidor. Essa implementação específica também é fornecida para você como uma exportação do pacote @fluidframework/azure-client.

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;
    }
}

Adicionar eficiência e tratamento de erros

A AzureFunctionTokenProvider é uma implementação simples da TokenProvider que deve ser tratada como um ponto de partida ao implementar seu próprio provedor de token personalizado. Para a implementação de um provedor de token pronto para produção, você deve considerar vários cenários de falha que o provedor de token precisa lidar. Por exemplo, a implementação AzureFunctionTokenProvider falha ao lidar com situações de desconexão de rede porque não armazena em cache o token no lado do cliente.

Quando o contêiner se desconecta, o gerenciador de conexões tenta obter um novo token junto ao TokenProvider antes de se reconectar ao contêiner. Embora a rede esteja desconectada, a solicitação de obtenção da API feita no fetchOrdererToken falhará e gerará um erro sem repetição. Isso, por sua vez, faz com que o contêiner seja descartado e não possa se reconectar mesmo que uma conexão de rede seja restabelecida.

Uma possível solução para esse problema de desconexão é armazenar em cache tokens válidos no Window.localStorage. Com o cache de token, o contêiner recuperará um token armazenado válido em vez de fazer uma solicitação de obtenção da API enquanto a rede estiver desconectada. Observe que um token armazenado localmente pode expirar após um determinado período de tempo e você ainda precisará fazer uma solicitação de API para obter um novo token válido. Nesse caso, a lógica adicional de tratamento de erros e repetição será necessária para impedir que o contêiner seja descartado após uma tentativa com falha.

A maneira como você escolhe implementar esses aprimoramentos depende de você e dos requisitos do seu aplicativo. Observe que, com a solução de token localStorage, você também verá melhorias de desempenho em seu aplicativo porque está removendo uma solicitação de rede em cada chamada getContainer.

O cache de tokens com algo como localStorage pode vir com implicações de segurança e cabe a você decidir qual solução é apropriada para seu aplicativo. Não importa se você vai ou não implementar o cache de token, mas é necessário adicionar a lógica de tratamento de erros e repetição no fetchOrdererToken e fetchStorageToken para que o contêiner não seja descartado após uma chamada com falha. Considere, por exemplo, encapsular a chamada de getTokenem um bloco try com um bloco catch que repete a tentativa e gera um erro somente após um número especificado de tentativas.

Confira também

• Adicionar dados personalizados a um token de autenticação
• Como implantar aplicativos fluidos usando Aplicativos Web Estáticos do Azure
• Como validar um documento criado pelo usuário