Trigger für Authentifizierungsereignisse für Azure Functions Clientbibliothek für Node

Artikel
01/10/2024

Authentifizierungsereignistrigger für Azure Functions verarbeitet die gesamte Back-End-Verarbeitung (z. B. Token-/JSON-Schemavalidierung) für eingehende HTTP-Anforderungen für Authentifizierungsereignisse. Und stellt dem Entwickler ein stark typisiertes, versionsbasiertes Objektmodell zur Verfügung, mit dem er arbeiten kann, was bedeutet, dass der Entwickler keine Vorkenntnisse über die Anforderungs- und Antwort-JSON-Nutzlasten haben muss.

Dieses Projektframework bietet die folgenden Features:

Tokenüberprüfung zum Sichern des API-Aufrufs
Objektmodell, Typisierung und IDE IntelliSense
Eingehende und ausgehende Überprüfung der API-Anforderungs- und Antwortschemas
Versionskontrolle
Es ist kein Code im Bausteine erforderlich.

Erste Schritte

Installieren des npm-Pakets

npm install @azure/functions-authentication-events

Voraussetzungen

Azure-Funktionstools
Azure Function Core Tools
Wenn Sie Visual Studio Code verwenden, gelten die folgenden Erweiterungen:
- ms-azuretools.vscode-azurefunctions
- ms-dotnettools.csharp

Authentifizieren des Clients

Wenn der Azure AD-Authentifizierungsereignissedienst Ihre benutzerdefinierte Erweiterung aufruft, sendet er einen Authorization Header mit einem Bearer {token}. Dieses Token stellt eine Dienst-zu-Dienst-Authentifizierung dar, in der Folgendes gilt:

Die "Ressource", die auch als Zielgruppe bezeichnet wird, ist die Anwendung, die Sie registrieren, um Ihre API darzustellen. Dies wird durch den aud Anspruch im Token dargestellt.
Der "Client" ist eine Microsoft-Anwendung, die den Azure AD-Authentifizierungsereignisdienst darstellt. Sie hat den appId Wert .99045fe1-7639-4a75-9d4a-577b6ca3810f Dies wird dargestellt durch:
- Der azp Anspruch im Token, wenn Ihre Anwendungseigenschaft accessTokenAcceptedVersion auf 2festgelegt ist.
- Der appid Anspruch im Token, wenn die accessTokenAcceptedVersion Eigenschaft Ihrer Ressourcenanwendung auf 1 oder nullfestgelegt ist.

Es gibt drei Ansätze für den Umgang mit dem Token. Sie können das Verhalten mithilfe von Anwendungseinstellungen wie unten gezeigt oder über die Datei local.settings.json in lokalen Umgebungen anpassen.

Überprüfen von Token mit Azure Functions Azure AD-Authentifizierungsintegration

Wenn Sie Ihre Funktion in der Produktion ausführen, wird dringend empfohlen, die Azure Functions Azure AD-Authentifizierungsintegration zum Überprüfen eingehender Token zu verwenden.

Wechseln Sie in Ihrer Funktions-App zur Registerkarte "Authentifizierung".
Klicken Sie auf "Identitätsanbieter hinzufügen".
Wählen Sie "Microsoft" als Identitätsanbieter aus.
Wählen Sie "Details einer vorhandenen App-Registrierung angeben" aus.
Geben Sie die Application ID der App ein, die Ihre API in Azure AD darstellt.

Der Aussteller und die zulässige Zielgruppe hängen von der accessTokenAcceptedVersion Eigenschaft Ihrer Anwendung ab (finden Sie im "Manifest" der Anwendung).

Wenn die accessTokenAcceptedVersion -Eigenschaft auf 2festgelegt ist: 6. Legen Sie die Issuer URL to "https://login.microsoftonline.com/{tenantId}/v2.0" 7. Set an 'Allowed Audience' to the Application ID (appId fest')

Wenn die accessTokenAcceptedVersion Eigenschaft auf 1 oder nullfestgelegt ist: 6. Legen Sie den Issuer URL to "https://sts.windows.net/{tenantId}/" 7. Set an 'Allowed Audience' to the Application ID URI (also known asidentifierUri). It should be in the format ofapi://{azureFunctionAppName}.azurewebsites.net/{resourceApiAppId}orapi://{FunctionAppFullyQualifiedDomainName}/{resourceApiAppId}' fest, wenn ein benutzerdefinierter Domänenname verwendet wird.

Standardmäßig überprüft der Authentifizierungsereignistrigger, ob die Integration der Azure-Funktionsauthentifizierung konfiguriert ist, und überprüft, ob der Client im Token auf 99045fe1-7639-4a75-9d4a-577b6ca3810f festgelegt ist (über die - oder appid -azpAnsprüche im Token).

Wenn Sie Ihre API mit einem anderen Client testen möchten, bei dem es sich nicht um den Azure AD-Authentifizierungsereignisdienst handelt, z. B. mit Postman, können Sie eine optionale Anwendungseinstellung konfigurieren:

AuthenticationEvents__CustomCallerAppId - die GUID Ihres gewünschten Clients. Wenn nicht angegeben, 99045fe1-7639-4a75-9d4a-577b6ca3810f wird davon ausgegangen.

Lassen Sie den Trigger das Token überprüfen.

In lokalen Umgebungen oder Umgebungen, die nicht im Azure-Funktionsdienst gehostet werden, kann der Trigger die Tokenüberprüfung durchführen. Legen Sie die folgenden Anwendungseinstellungen fest:

AuthenticationEvents__TenantId : Ihre Mandanten-ID
AuthenticationEvents__AudienceAppId – derselbe Wert wie "Zulässige Zielgruppe" in Option 1.
AuthenticationEvents__CustomCallerAppId (optional): die GUID Ihres gewünschten Clients. Wenn nicht angegeben, 99045fe1-7639-4a75-9d4a-577b6ca3810f wird davon ausgegangen.

Beispiel einer Datei 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"
  }
}

Keine Tokenüberprüfung

Wenn Sie das Token während der lokalen Entwicklung nicht authentifizieren möchten, legen Sie die folgende Anwendungseinstellung fest:

AuthenticationEvents__BypassTokenValidation : Der Wert von true bewirkt, dass der Trigger nicht auf eine Überprüfung des Tokens überprüft.

Schnellstart

Visual Studio Code
- Starten Sie Visual Studio Code.
- Ausführen des Terminalbefehls func init . --worker-runtime node über die Befehlspalette
- Ausführen des Terminalbefehls func new über die Befehlspalette
- Folgen Sie den Aufforderungen zur Projekterstellung.
- Ausführen des Terminalbefehls npm install @azure/functions-authentication-events über die Befehlspalette
- Ausführen des Terminalbefehls npm install über die Befehlspalette
- Ausführen des Terminalbefehls npm run-script build über die Befehlspalette
Zu Entwicklungszwecken turn of token validation for testing( Turn of token validation for testing):
Fügen Sie den AuthenticationEvents__BypassTokenValidation Anwendungsschlüssel dem Abschnitt "Values" in der Datei local.settings.json hinzu, und legen Sie dessen Wert auf true fest. Wenn Sie in Ihrer lokalen Umgebung keine Datei local.settings.json haben, erstellen Sie eine datei im Stammverzeichnis Ihrer Funktions-App.

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

Nachdem das Projekt geladen wurde, können Sie den Beispielcode ausführen. Es sollte angezeigt werden, dass die Anwendung des Azure Functions-Entwicklers Ihren Endpunkt geladen hat.

Wichtige Begriffe

Wichtige Konzepte des Azure .NET SDK finden Sie hier.

Dokumentation

Eine der Funktion wurde veröffentlicht, es gibt einige gute Lektüre über Protokollierung und Metriken, die hier zu finden sind.
Die API-Dokumentation finden Sie unter (Link-TBD).
Sobald dies in die Vorschauversion wechselt, sind keine Breaking Changes erforderlich. Dies wäre so einfach wie das Entfernen der NuGet-Quelle, die auf die private Vorschau zeigt.

Beispiele

Gehen Sie wie folgt vor, um die Tokenerweiterung zu testen.

Öffnen Sie das Projekt, das im vorherigen Schritt erstellt wurde. (Schnellstart)
Führen Sie die Anwendung aus. func host start
Nachdem die Anwendung des Azure Functions-Entwicklers gestartet wurde, kopieren Sie die Lausch-URL, die beim Start der Anwendung angezeigt wird.
Hinweis: Alle Authentifizierungsfunktionen werden aufgeführt, falls ein Funktionslistener mit dem Namen "OnTokenIssuanceStart" registriert ist.
Ihr Funktionsendpunkt ist dann eine Kombination aus der lauschenden URL und der Funktion, z. B.: "http://localhost:7071/runtime/webhooks/AuthenticationEvents?code=(YOUR_CODE)& function=OnTokenIssuanceStart"
Posten Sie die folgende Nutzlast mit etwa Postman oder Fiddler.
Schritte zur Verwendung von Postman finden Sie (Link 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"
            }
        }
    }
}

Diese Antwort sollte angezeigt werden:

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

Problembehandlung

Visual Studio Code
- Wenn Sie in Visual Studio Code ausgeführt werden, erhalten Sie eine Fehlermeldung wie der lokale Azure Storage-Emulator ist nicht verfügbar. Sie können den Emulator manuell starten.! (Hinweis: Der Azure Storage-Emulator ist jetzt veraltet, und der vorgeschlagene Ersatz ist Azurite.)
- Wenn Sie Visual Studio Code auf einem Mac verwenden, verwenden Sie Azurite.
- Wenn der folgende Fehler unter Windows angezeigt wird (dies ist ein Fehler), wenn Sie versuchen, die erstellte projiziert auszuführen.
- Dies kann durch Ausführen dieses Befehls in PowerShell Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope LocalMachine behoben werden. Weitere Informationen hierzu finden Sie hier und hier.

Nächste Schritte

Weitere Informationen zum Azure SDK finden Sie auf dieser Website.

Veröffentlichen

Befolgen Sie die anweisungen hier, um Ihre Azure-Anwendung zu erstellen und zu veröffentlichen. </azure/azure-functions/functions-develop-vs?tabs=in-process#publish-to-azure>
Um Ihren veröffentlichten Veröffentlichungsendpunkt zu ermitteln, kombinieren Sie den von Ihnen erstellten Azure-Funktionsendpunkt, leiten Sie den Listener und den Listenercode weiter. Der Listencode kann gefunden werden, indem Sie zu Ihrer Azure-Funktionsanwendung navigieren, "App-Schlüssel" auswählen und den Wert von AuthenticationEvents_extension kopieren.
Beispiel: "https://azureautheventstriggerdemo.azurewebsites.net/runtime/webhooks/AuthenticationEvents?code=(AuthenticationEvents_extension_key)& function=OnTokenIssuanceStart"
Stellen Sie sicher, dass Ihre Produktionsumgebung über die richtigen Anwendungseinstellungen für die Tokenauthentifizierung verfügt.
Erneut können Sie die veröffentlichte Funktion testen, indem Sie die oben genannte Nutzlast an den neuen Endpunkt senden.

Mitwirken

Ausführliche Informationen zum Mitwirken zu diesem Repository finden Sie im Leitfaden zur Mitarbeit.

Beiträge und Vorschläge für dieses Projekt sind willkommen. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. Ausführliche Informationen finden Sie unter https://cla.microsoft.com.

Wenn Sie einen Pull Request (PR) übermitteln, überprüft ein CLA-Bot automatisch, ob Sie eine Lizenzvereinbarung bereitstellen und den PR entsprechend ergänzen müssen (z.B. mit einer Bezeichnung oder einem Kommentar). Führen Sie einfach die Anweisungen des Bots aus. Sie müssen dies nur einmal für alle Repositorys mit unserer CLA tun.

Für dieses Projekt gelten die Microsoft-Verhaltensregeln für Open Source (Microsoft Open Source Code of Conduct). Weitere Informationen finden Sie in den häufig gestellten Fragen zum Verhaltenskodex. Sie können sich auch an opencode@microsoft.com wenden, wenn Sie weitere Fragen oder Anmerkungen haben.

Freigeben über