Trigger událostí ověřování pro Azure Functions klientskou knihovnu pro Node

Článek
04/05/2023

Trigger události ověřování pro Azure Functions zpracovává veškeré zpracování back-endu (např. ověření schématu tokenu nebo json) příchozích požadavků HTTP pro události ověřování. A poskytuje vývojáři objektový model se silnými typy a verzemi, se kterým může pracovat, což znamená, že vývojář nemusí mít žádné předchozí znalosti datových částí JSON požadavků a odpovědí.

Tato architektura projektu poskytuje následující funkce:

Ověření tokenu pro zabezpečení volání rozhraní API
Objektový model, psaní a integrované vývojové prostředí IntelliSense
Příchozí a odchozí ověřování schémat požadavků a odpovědí rozhraní API
Správa verzí
Není potřeba používat často používaný kód.

Začínáme

Instalace balíčku npm

npm install @azure/functions-authentication-events

Požadavky

Nástroje funkcí Azure
Azure Functions Core Tools
Pokud používáte Visual Studio Code, použijte následující rozšíření:
- ms-azuretools.vscode-azurefunctions
- ms-dotnettools.csharp

Ověření klienta

Když služba událostí ověřování Azure AD zavolá vaše vlastní rozšíření, odešle hlavičku AuthorizationBearer {token}s . Tento token bude představovat ověřování služby pro službu , ve kterém:

Prostředek, označovaný také jako cílová skupina, je aplikace, kterou zaregistrujete jako reprezentaci vašeho rozhraní API. Toto je reprezentováno deklarací aud identity v tokenu.
Klient je aplikace Microsoftu, která představuje službu událostí ověřování Azure AD. Má appId hodnotu 99045fe1-7639-4a75-9d4a-577b6ca3810f. Toto je reprezentováno:
- Deklarace azp identity v tokenu, pokud je vlastnost vaší aplikace accessTokenAcceptedVersion nastavená na 2.
- Deklarace appid identity v tokenu, pokud je vlastnost vaší aplikace accessTokenAcceptedVersion prostředků nastavená na 1 nebo null.

Existují tři přístupy k práci s tokenem. Chování můžete přizpůsobit pomocí nastavení aplikace , jak je znázorněno níže, nebo prostřednictvím souboru local.settings.json v místních prostředích.

Ověřování tokenů s využitím integrace ověřování Azure Functions Azure AD

Při spouštění funkce v produkčním prostředí se důrazně doporučuje použít k ověřování příchozích tokenů integraci ověřování Azure Functions Azure AD.

V aplikaci funkcí přejděte na kartu Ověřování.
Klikněte na Přidat zprostředkovatele identity.
Jako zprostředkovatele identity vyberte Microsoft.
Vyberte Zadat podrobnosti o existující registraci aplikace.
Zadejte název Application ID aplikace, která představuje vaše rozhraní API v Azure AD

Vystavitel a povolená cílová skupina závisí na accessTokenAcceptedVersion vlastnosti vaší aplikace (najdete je v manifestu aplikace).

accessTokenAcceptedVersion Pokud je vlastnost nastavená na 2hodnotu : 6. Nastavte Issuer URL to "https://login.microsoftonline.com/{tenantId}/v2.0" 7. Set an 'Allowed Audience' to the Application ID (appId').

accessTokenAcceptedVersion Pokud je vlastnost nastavená na 1 hodnotu nebo null: 6, nastavte Issuer URL to "https://sts.windows.net/{tenantId}/" 7. Set an 'Allowed Audience' to the Application ID URI (also known asidentifikátorUri). It should be in the format ofapi://{azureFunctionAppName}.azurewebsites.net/{resourceApiAppId}orapi://{FunctionAppFullyQualifiedDomainName}/{resourceApiAppId}', pokud používáte vlastní název domény.

Trigger události ověřování ve výchozím nastavení ověří, že je nakonfigurovaná integrace ověřování funkce Azure Functions, a zkontroluje, jestli je klient v tokenu nastavený na 99045fe1-7639-4a75-9d4a-577b6ca3810f hodnotu (prostřednictvím azp deklarací identity nebo appid v tokenu).

Pokud chcete rozhraní API otestovat s jiným klientem, který není Azure AD službou událostí ověřování, například pomocí nástroje Postman, můžete nakonfigurovat volitelné nastavení aplikace:

AuthenticationEvents__CustomCallerAppId – identifikátor GUID požadovaného klienta. Pokud není zadaný, 99045fe1-7639-4a75-9d4a-577b6ca3810f předpokládá se.

Nechte trigger ověřit token.

V místních prostředích nebo prostředích, která nejsou hostovaná ve službě Azure Functions, může trigger provést ověření tokenu. Nastavte následující nastavení aplikace:

AuthenticationEvents__TenantId – ID tenanta
AuthenticationEvents__AudienceAppId – stejná hodnota jako Povolená cílová skupina v možnosti 1.
AuthenticationEvents__CustomCallerAppId (volitelné) – identifikátor GUID požadovaného klienta. Pokud není zadaný, 99045fe1-7639-4a75-9d4a-577b6ca3810f předpokládá se.

Ukázkový local.settings.json soubor:

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "FUNCTIONS_WORKER_RUNTIME": "dotnet",
    "AuthenticationEvents__TenantId": "8615397b-****-****-****-********06c8",
    "AuthenticationEvents__AudienceAppId": "api://46f98993-****-****-****-********0038",
    "AuthenticationEvents__CustomCallerAppId": "46f98993-****-****-****-********0038"
  }
}

Žádné ověření tokenu

Pokud nechcete, aby se token během místního vývoje neověřoval , nastavte následující nastavení aplikace:

AuthenticationEvents__BypassTokenValidation – hodnota true způsobí, že trigger nebude kontrolovat ověření tokenu.

Rychlé zprovoznění

Visual Studio Code
- Spusťte Visual Studio Code.
- Spuštění příkazu func init . --worker-runtime node terminálu prostřednictvím palety příkazů
- Spuštění příkazu func new terminálu prostřednictvím palety příkazů
- Postupujte podle pokynů k vytvoření projektu.
- Spuštění příkazu npm install @azure/functions-authentication-events terminálu prostřednictvím palety příkazů
- Spuštění příkazu npm install terminálu prostřednictvím palety příkazů
- Spuštění příkazu npm run-script build terminálu prostřednictvím palety příkazů
Pro účely vývoje zapněte ověření tokenu pro testování:
Přidejte AuthenticationEvents__BypassTokenValidation klíč aplikace do oddílu Hodnoty v souboru local.settings.json a nastavte jeho hodnotu na true. Pokud v místním prostředí nemáte soubor local.settings.json, vytvořte ho v kořenovém adresáři vaší aplikace funkcí.

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "FUNCTIONS_WORKER_RUNTIME": "node",
    "AuthenticationEvents__BypassTokenValidation": true
  }
}

Po načtení projektu můžete spustit ukázkový kód a měli byste vidět, jak aplikace vývojáře Azure Functions načte váš koncový bod.

Klíčové koncepty

Klíčové koncepty sady Azure .NET SDK najdete tady.

Dokumentace

Na jedné z publikovaných funkcí najdete dobré informace o protokolování a metrikách, které najdete tady.
Dokumentaci k rozhraní API najdete v tématu (Odkaz TBD).
Jakmile se přesunete do verze Preview, nedojde k žádným zásadním změnám. Stačí odebrat zdroj NuGet, který odkazuje na privátní verzi Preview.

Příklady

Pokud chcete otestovat rozšíření tokenů, postupujte následovně.

Otevřete projekt vytvořený v předchozím kroku. (Rychlý start)
Spusťte aplikaci. func host start
Jakmile se spustí aplikace vývojáře Azure Functions, zkopírujte adresu URL naslouchání, která se zobrazí při spuštění aplikace.
Poznámka: Jsou uvedené všechny funkce ověřování, pokud máme zaregistrovaný jeden naslouchací proces funkce s názvem OnTokenIssuanceStart.
Koncový bod funkce pak bude kombinací adresy URL pro naslouchání a funkce, například: "http://localhost:7071/runtime/webhooks/AuthenticationEvents?code=(YOUR_CODE)& function=OnTokenIssuanceStart"
Publikujte následující datovou část pomocí nástroje Postman nebo Fiddler.
Postup použití nástroje Postman najdete (odkaz TBD).

{
    "type": "microsoft.graph.authenticationEvent.tokenIssuanceStart",
    "source": "/tenants/00000001-0000-0ff1-ce00-000000000000/applications/ef9e995c-efdb-4e76-97a9-8cdfc6e06afc",
    "data": {
        "@odata.type": "microsoft.graph.onTokenIssuanceStartCalloutData",
        "tenantId": "00000001-0000-0ff1-ce00-000000000000",
        "authenticationEventListenerId": "f2390d57-9664-4dde-b625-f0115925e1e2",
        "customAuthenticationExtensionId": "9cc1c1ed-5f04-4fdf-85c0-94a7c6ea819c",
        "authenticationContext": {
            "correlationId": "f4bd1870-b774-4fa5-ba78-e08ac6be14c0",
            "client": {
                "ip": "127.0.0.1",
                "locale": "en-us",
                "market": "en-us"
            },
            "protocol": "OAUTH2.0",
            "clientServicePrincipal": {
                "id": "eedfddb9-304e-4d62-aa83-24700a0bcf0e",
                "appId": "ef9e995c-efdb-4e76-97a9-8cdfc6e06afc",
                "appDisplayName": "",
                "displayName": "Test application"
            },
            "resourceServicePrincipal": {
                "id": "eedfddb9-304e-4d62-aa83-24700a0bcf0e",
                "appId": "ef9e995c-efdb-4e76-97a9-8cdfc6e06afc",
                "appDisplayName": "",
                "displayName": "Test application"
            },
            "user": {
                "companyName": "Evo Sts Test",
                "country": "",
                "id": "69d24544-c420-4721-a4bf-106f2378d9f6",
                "mail": "testadmin@evostsoneboxtest.com",
                "onPremisesSamAccountName": "testadmin",
                "onPremisesSecurityIdentifier": "testadmin",
                "preferredDataLocation": "",
                "userPrincipalName": "testadmin@evostsoneboxtest.com"
            }
        }
    }
}

Měla by se zobrazit tato odpověď:

{
    "data": {
        "@odata.type": "microsoft.graph.onTokenIssuanceStartResponseData",
        "actions": [
            {
                "@odata.type": "ProvideClaimsForToken",
                "claims": [
                    {
                        "DateOfBirth": "01/01/2000"
                    },
                    {
                        "CustomRoles": [
                            "Writer",
                            "Editor"
                        ]
                    }
                ]
            }
        ]
    }
}

Poradce při potížích

Visual Studio Code
- Pokud spustíte nástroj Visual Studio Code, zobrazí se chyba, že místní emulátor služby Azure Storage není k dispozici. Emulátor můžete spustit ručně. (Poznámka: Emulátor služby Azure Storage je teď zastaralý a navrhované nahrazení je Azurite.)
- Pokud používáte Visual Studio Code na Macu, použijte Azurite.
- Pokud se ve Windows při pokusu o spuštění vytvořeného projektu zobrazí následující chyba (jedná se o chybu).
- Tento problém se dá vyřešit spuštěním tohoto příkazu v PowerShelluSet-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope LocalMachine. Další informace najdete tady a tady.

Další kroky

Další informace o sadě Azure SDK najdete na tomto webu.

Publikovat

Pokud chcete vytvořit a publikovat Aplikace Azure, postupujte podle pokynů uvedených tady. </azure/azure-functions/functions-develop-vs?tabs=in-process#publish-to-azure>
Pokud chcete zjistit publikovaný koncový bod publikování, zkombinujte vytvořený koncový bod funkce Azure, nasměrujte ho na kód naslouchacího procesu a naslouchacího procesu. Kód naslouchání najdete tak, že přejdete do aplikace funkcí Azure, vyberete Klíče aplikace a zkopírujete hodnotu AuthenticationEvents_extension.
Příklad: "https://azureautheventstriggerdemo.azurewebsites.net/runtime/webhooks/AuthenticationEvents?code=(AuthenticationEvents_extension_key)& function=OnTokenIssuanceStart"
Ujistěte se, že vaše produkční prostředí má správné nastavení aplikace pro ověřování tokenů.
Publikovanou funkci můžete znovu otestovat odesláním výše uvedené datové části do nového koncového bodu.

Přispívání

Podrobnosti o přispívání do tohoto úložiště najdete v průvodci přispívání.

Tento projekt vítá příspěvky a návrhy. Většina příspěvků vyžaduje souhlas s licenční smlouvou s přispěvatelem (CLA), která stanoví, že máte právo udělit nám práva k používání vašeho příspěvku a skutečně tak činíte. Podrobnosti najdete tady: https://cla.microsoft.com

Při odesílání žádosti o přijetí změn robot CLA automaticky určí, jestli je potřeba poskytnout smlouvu CLA, a příslušným způsobem žádost o přijetí změn upraví (např. přidáním jmenovky nebo komentáře). Stačí postupovat podle pokynů robota. Pomocí našeho cla to budete muset provést ve všech úložištích pouze jednou.

Tento projekt přijal pravidla chování pro Microsoft Open Source. Další informace najdete v nejčastějších dotazech k pravidlům chování nebo kontaktujte s opencode@microsoft.com případnými dalšími dotazy nebo připomínkami.

Sdílet prostřednictvím