Megosztás a következőn keresztül:

Útmutató: TokenProvider írása Azure-függvényekkel

  • Cikk

Megjegyzés:

Ez az előzetes verzió szolgáltatásszintű szerződés nélkül érhető el, és éles számítási feladatokhoz nem ajánlott. Előfordulhat, hogy néhány funkció nem támogatott, vagy korlátozott képességekkel rendelkezik.

A Dinamikus keretrendszer a TokenProviders feladata olyan jogkivonatok létrehozása és aláírása, amelyeket az @fluidframework/azure-client Azure Fluid Relay szolgáltatáshoz való kérésekhez használnak. A Dinamikus keretrendszer egy egyszerű, nem biztonságos TokenProvidert biztosít fejlesztési célokra, a neve insecureTokenProvider. Minden Fluid-szolgáltatásnak egyéni TokenProvidert kell implementálnia az adott szolgáltatás hitelesítési és biztonsági szempontjai alapján.

Minden létrehozott Azure Fluid Relay-erőforráshoz hozzárendelünk egy bérlőazonosítót és egy saját egyedi bérlői titkos kulcsot. A titkos kulcs egy megosztott titkos kód. Az alkalmazás/szolgáltatás tudja, és az Azure Fluid Relay szolgáltatás is ismeri. A TokenProvidersnek ismernie kell a kérések aláírásához szükséges titkos kulcsot, de a titkos kulcs nem szerepelhet az ügyfélkódban.

Azure-függvény implementálása jogkivonatok aláírásához

A biztonságos jogkivonat-szolgáltató létrehozásának egyik lehetősége, ha HTTPS-végpontot hoz létre, és létrehoz egy TokenProvider-implementációt, amely hitelesített HTTPS-kéréseket küld az adott végpontra a jogkivonatok lekéréséhez. Ez az elérési út lehetővé teszi a bérlő titkos kulcsának biztonságos helyen, például az Azure Key Vaultban való tárolását.

A teljes megoldás két részből áll:

  1. Egy HTTPS-végpont, amely fogadja a kéréseket, és Azure Fluid Relay-jogkivonatokat ad vissza.
  2. Egy ITokenProvider-implementáció, amely egy végpont URL-címét fogadja el, majd a végpontra irányuló kéréseket küld a jogkivonatok lekéréséhez.

Végpont létrehozása a TokenProviderhez az Azure Functions használatával

Az Azure Functions használatával gyorsan létrehozhat ilyen HTTPS-végpontokat.

Ez a példa bemutatja, hogyan hozhat létre saját HTTPTrigger Azure-függvényt , amely lekéri a jogkivonatot a bérlőkulcs átadásával.

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 generateToken csomagban @fluidframework/azure-service-utils található függvény létrehoz egy jogkivonatot az adott felhasználó számára, amely a bérlő titkos kulcsával van aláírva. Ez a módszer lehetővé teszi, hogy a jogkivonat a titkos kód felfedése nélkül visszakerüljön az ügyfélhez. Ehelyett a jogkivonat kiszolgálóoldalon jön létre a titkos kód használatával, hogy hatókörön belüli hozzáférést biztosítson az adott dokumentumhoz. Az alábbi ITokenProvider példa HTTP-kéréseket küld erre az Azure-függvényre a jogkivonatok lekéréséhez.

Az Azure-függvény üzembe helyezése

Az Azure Functions többféleképpen is üzembe helyezhető. További információkért tekintse meg az Azure Functions dokumentációjának Üzembe helyezés című szakaszát az Azure Functions üzembe helyezéséről.

A TokenProvider implementálása

A TokenProviders sokféleképpen implementálható, de két külön API-hívást kell implementálnia: fetchOrdererToken és fetchStorageToken. Ezek az API-k felelősek a Fluid orderer és a Storage-szolgáltatások jogkivonatainak lekéréséért. Mindkét függvény a jogkivonat értékét képviselő objektumokat ad vissza TokenResponse . A Dinamikus keretrendszer futtatókörnyezet szükség szerint meghívja ezt a két API-t a jogkivonatok lekéréséhez. Vegye figyelembe, hogy bár az alkalmazáskód csak egy szolgáltatásvégpontot használ az Azure Fluid Relay szolgáltatással való kapcsolat létesítéséhez, az Azure-ügyfél a szolgáltatással együtt belsőleg lefordítja ezt az egy végpontot egy rendelési és tárolási végpontpárra. Ez a két végpont ettől a ponttól kezdve használatos az adott munkamenethez, ezért a jogkivonatok lekéréséhez két külön függvényt kell implementálnia, egyet mindegyikhez.

Annak érdekében, hogy a bérlő titkos kulcsa biztonságban legyen, biztonságos háttérrendszerben tárolja, és csak az Azure-függvényből érhető el. A jogkivonatok lekéréséhez be kell küldenie vagy GET le kell kérnie az üzembe helyezett Azure-függvényt, és meg kell adnia az tenantID és documentIda .userID/userNamePOST Az Azure-függvény feladata a bérlőazonosító és a bérlőkulcs titkos kulcsának megfeleltetése a jogkivonat megfelelő létrehozásához és aláírásához.

Az alábbi példa implementáció kezeli ezeket a kéréseket az Azure-függvénynek. Az axios-kódtárat használja HTTP-kérések igényléséhez. Más kódtárak vagy megközelítések használatával HTTP-kéréseket is kezdeményezhet a kiszolgálókódból. Ezt a konkrét megvalósítást a csomagból való @fluidframework/azure-client exportálásként is biztosítjuk.

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

Hatékonyság és hibakezelés hozzáadása

Ez AzureFunctionTokenProvider egy egyszerű implementáció, TokenProvider amelynek kiindulópontjaként kell kezelnie a saját egyéni jogkivonat-szolgáltató implementálásakor. Az éles üzemre kész jogkivonat-szolgáltató implementálásához érdemes megfontolnia a jogkivonat-szolgáltató által kezelni kívánt különböző hibaforgatókönyveket. Az implementáció például nem kezeli a AzureFunctionTokenProvider hálózatleválasztási helyzeteket, mert nem gyorsítótárazza a jogkivonatot az ügyféloldalon.

Amikor a tároló megszakad, a kapcsolatkezelő megpróbál új jogkivonatot lekérni a TokenProviderből, mielőtt újra csatlakozik a tárolóhoz. A hálózat leválasztása közben az API beolvasási kérése fetchOrdererToken sikertelen lesz, és nem újrapróbálkozási hibát okoz. Ez viszont azt eredményezi, hogy a tárolót megsemmisítik, és nem tudnak újracsatlakozni, még akkor sem, ha újra létrejön a hálózati kapcsolat.

A leválasztási probléma lehetséges megoldása az érvényes jogkivonatok gyorsítótárazása a Window.localStorage-ban. A jogkivonatok gyorsítótárazásával a tároló érvényes tárolt jogkivonatot kér le ahelyett, hogy API-kérést kér, miközben a hálózat megszakad. Vegye figyelembe, hogy egy helyileg tárolt jogkivonat egy bizonyos idő elteltével lejárhat, és egy új érvényes jogkivonat beszerzéséhez api-kérést kell küldenie. Ebben az esetben további hibakezelési és újrapróbálkozási logikára lenne szükség ahhoz, hogy a tároló egyetlen sikertelen kísérlet után ne omljon ki.

A fejlesztések megvalósítása teljes mértékben Önön és az alkalmazás követelményein múlik. Vegye figyelembe, hogy a localStorage jogkivonat-megoldással az alkalmazás teljesítménybeli fejlesztései is megjelennek, mivel minden getContainer hívásnál eltávolít egy hálózati kérést.

A jogkivonat-gyorsítótárazás biztonsági localStorage következményekkel járhat, és a saját belátása szerint dönti el, hogy melyik megoldás megfelelő az alkalmazás számára. Függetlenül attól, hogy implementálja-e a token-gyorsítótárazást, adjon hozzá hibakezelési és újrapróbálkozási logikát fetchOrdererToken , és fetchStorageToken hogy a tároló ne legyen megsemmisítve egyetlen sikertelen hívás után. Fontolja meg például, hogy egy blokk hívását getToken egy try catch olyan blokkba csomagolja, amely újrapróbálkozott, és csak meghatározott számú újrapróbálkozás után jelez hibát.

Kapcsolódó információk