Utlösare för autentiseringshändelser för Azure Functions klientbibliotek för Node

Artikel
01/10/2024

Autentiseringshändelseutlösare för Azure Functions hanterar all serverdelsbearbetning (t.ex. validering av token/json-schema) för inkommande HTTP-begäranden för autentiseringshändelser. Och ger utvecklaren en starkt typifierad, versionshanterad objektmodell att arbeta med, vilket innebär att utvecklaren inte behöver ha någon tidigare kunskap om json-nyttolaster för begäran och svar.

Det här projektramverket innehåller följande funktioner:

Tokenverifiering för att skydda API-anropet
Objektmodell, inmatning och IDE-intellisense
Inkommande och utgående validering av API-begäran och svarsscheman
Versionshantering
Inget behov av exempelkod.

Komma igång

Installera npm-paketet

npm install @azure/functions-authentication-events

Förutsättningar

Azure-funktionsverktyg
Azure Function Core Tools
Om du använder Visual Studio Code följande tillägg:
- ms-azuretools.vscode-azurefunctions
- ms-dotnettools.csharp

Autentisera klienten

När Azure AD-tjänsten för autentiseringshändelser anropar ditt anpassade tillägg skickas ett Authorization huvud med en Bearer {token}. Denna token representerar en tjänst-till-tjänst-autentisering där:

Resursen, som även kallas målgrupp, är det program som du registrerar för att representera ditt API. Detta representeras av anspråket aud i token.
"Klienten" är ett Microsoft-program som representerar Azure AD-tjänsten för autentiseringshändelser. Den har värdet appId99045fe1-7639-4a75-9d4a-577b6ca3810f. Detta representeras av:
- Anspråket azp i token om programegenskapen accessTokenAcceptedVersion är inställd på 2.
- Anspråket appid i token om resursprogrammets accessTokenAcceptedVersion egenskap är inställd på 1 eller null.

Det finns tre sätt att hantera token. Du kan anpassa beteendet med hjälp av programinställningar enligt nedan eller via filen local.settings.json i lokala miljöer.

Verifiera token med hjälp av Azure Functions Azure AD autentiseringsintegrering

När du kör funktionen i produktion rekommenderar vi starkt att du använder Azure Functions Azure AD-autentiseringsintegrering för att verifiera inkommande token.

Gå till fliken "Autentisering" i funktionsappen
Klicka på "Lägg till identitetsprovider"
Välj "Microsoft" som identitetsprovider
Välj "Ange information om en befintlig appregistrering"
Ange för den Application ID app som representerar ditt API i Azure AD

Utfärdaren och den tillåtna målgruppen beror på egenskapen för accessTokenAcceptedVersion ditt program (finns i "Manifestet" för programmet).

Om egenskapen är inställd på accessTokenAcceptedVersion2: 6. Ange Issuer URL to "https://login.microsoftonline.com/{tenantId}/v2.0" 7. Set an 'Allowed Audience' to the Application ID (appId))

accessTokenAcceptedVersion Om egenskapen är inställd på 1 eller null: 6. Ange Issuer URL to "https://sts.windows.net/{tenantId}/" 7. Set an 'Allowed Audience' to the Application ID URI (also known asidentifierUri-api://). It should be in the format of{azureFunctionAppName}.azurewebsites.net/{resourceApiAppId}orapi://{FunctionAppFullyQualifiedDomainName}/{resourceApiAppId} om du använder ett anpassat domännamn.

Som standard verifierar autentiseringshändelseutlösaren att Integrering av Azure Function-autentisering har konfigurerats och kontrollerar att klienten i token är inställd 99045fe1-7639-4a75-9d4a-577b6ca3810f på (via anspråken azp eller appid i token).

Om du vill testa ditt API mot en annan klient som inte är Azure AD tjänsten för autentiseringshändelser, som att använda Postman, kan du konfigurera en valfri programinställning:

AuthenticationEvents__CustomCallerAppId – guid för din önskade klient. Om inget anges 99045fe1-7639-4a75-9d4a-577b6ca3810f antas det.

Be utlösaren verifiera token

I lokala miljöer eller miljöer som inte finns i Azure-funktionstjänsten kan utlösaren utföra tokenverifieringen. Ange följande programinställningar:

AuthenticationEvents__TenantId – ditt klientorganisations-ID
AuthenticationEvents__AudienceAppId – samma värde som "Tillåten målgrupp" i alternativ 1.
AuthenticationEvents__CustomCallerAppId (valfritt) – guid för din önskade klient. Om inget anges 99045fe1-7639-4a75-9d4a-577b6ca3810f antas det.

En exempelfil local.settings.json :

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

Ingen tokenverifiering

Om du inte vill autentisera token under lokal utveckling anger du följande programinställning:

AuthenticationEvents__BypassTokenValidation – värdet för true gör att utlösaren inte söker efter en validering av token.

Snabbstart

Visuell Studio-kod
- Starta Visual Studio Code
- Kör terminalkommandot func init . --worker-runtime node via kommandopaletten
- Kör terminalkommandot func new via kommandopaletten
- Följ anvisningarna för att skapa projekt
- Kör terminalkommandot npm install @azure/functions-authentication-events via kommandopaletten
- Kör terminalkommandot npm install via kommandopaletten
- Kör terminalkommandot npm run-script build via kommandopaletten
I utvecklingssyfte ska tokenverifiering för testning utföras:
Lägg till AuthenticationEvents__BypassTokenValidation-programnyckeln i avsnittet "Värden" i filen local.settings.json och ange värdet till true. Om du inte har en local.settings.json-fil i din lokala miljö skapar du en i roten för funktionsappen.

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

När projektet har lästs in kan du köra exempelkoden och du bör se azure functions-utvecklarens program läsa in slutpunkten.

Viktiga begrepp

Viktiga begrepp för Azure .NET SDK finns här

Dokumentation

En funktion har publicerats, det finns en del bra läsning om loggning och mått som finns här
Api-dokumentationen finns i (Länka TBD)
När det här övergår till förhandsgranskning, förutom icke-bakåtkompatibla ändringar och skulle vara så enkelt som att ta bort nuget-källan som pekar på den privata förhandsgranskningen.

Exempel

Gör följande för att testa tokenförstoring.

Öppna projektet som skapades i föregående steg. (Snabbstart)
Kör programmet. func host start
När Azure Functions-utvecklarens program har startat kopierar du den lyssnings-URL som visas när programmet startas.
Obs! Alla autentiseringsfunktioner visas, om vi har en funktionslyssnare registrerad med namnet "OnTokenIssuanceStart"
Funktionsslutpunkten är sedan en kombination av lyssnings-URL:en och funktionen, till exempel: "http://localhost:7071/runtime/webhooks/AuthenticationEvents?code=(YOUR_CODE)& function=OnTokenIssuanceStart"
Publicera följande nyttolast med något som Postman eller Fiddler.
Steg för att använda Postman finns (länka 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"
            }
        }
    }
}

Du bör se det här svaret:

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

Felsökning

Visuell Studio-kod
- Om du kör i Visual Studio Code får du ett fel i stil med att den lokala Azure Storage-emulatorn inte är tillgänglig. Du kan starta emulatorn manuellt.! (Obs! Azure Storage-emulatorn är nu inaktuell och den föreslagna ersättningen är Azurite)
- Om du använder Visual Studio Code på Mac använder du Azurite
- Om du ser följande fel i Windows (det är en bugg) när du försöker köra den skapade projicerade.
- Detta kan lösas genom att köra det här kommandot i PowerShell Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope LocalMachine mer information om detta finns här och här

Nästa steg

Mer information om Azure SDK finns på den här webbplatsen

Publicera

Följ anvisningarna här för att skapa och publicera din Azure Application. </azure/azure-functions/functions-develop-vs?tabs=in-process#publish-to-azure>
För att fastställa den publicerade publiceringsslutpunkten kombinerar du azure-funktionsslutpunkten som du skapade, dirigerar till lyssnaren och lyssnarkoden. Du hittar lyssningskoden genom att gå till azure-funktionsprogrammet, välja "Appnycklar" och kopiera värdet för AuthenticationEvents_extension.
Till exempel: "https://azureautheventstriggerdemo.azurewebsites.net/runtime/webhooks/AuthenticationEvents?code=(AuthenticationEvents_extension_key)& function=OnTokenIssuanceStart"
Kontrollera att produktionsmiljön har rätt programinställningar för tokenautentisering.
Återigen kan du testa den publicerade funktionen genom att publicera nyttolasten ovan till den nya slutpunkten.

Bidra

Mer information om hur du bidrar till den här lagringsplatsen finns i bidragsguiden.

Det här projektet välkomnar bidrag och förslag. Merparten av bidragen kräver att du godkänner ett licensavtal för bidrag, där du deklarerar att du har behörighet att bevilja oss rättigheten att använda ditt bidrag, och att du dessutom uttryckligen gör så. Mer information finns på https://cla.microsoft.com.

När du skickar en pull-förfrågan avgör en CLA-robot automatiskt om du måste tillhandahålla ett licensavtal för bidrag med lämplig PR (t.ex. etikett eller kommentar). Följ bara robotens anvisningar. Du behöver bara göra detta en gång i alla lagringsplatser med vår CLA.

Det här projektet använder sig av Microsofts uppförandekod för öppen källkod. Mer information finns i Vanliga frågor och svar om uppförandekod eller kontakt opencode@microsoft.com med ytterligare frågor eller kommentarer.

Dela via