Trigger für Authentifizierungsereignisse für Azure Functions Clientbibliothek für .NET

  • Artikel

Mit dem Trigger für Authentifizierungsereignisse für Azure Functions können Sie eine benutzerdefinierte Erweiterung implementieren, um Azure Active Directory-Authentifizierungsereignisse (Azure AD) zu verarbeiten. Der Trigger für Authentifizierungsereignisse verarbeitet die gesamte Back-End-Verarbeitung für eingehende HTTP-Anforderungen für Azure AD-Authentifizierungsereignisse und stellt dem Entwickler Folgendes zur Verfügung:

  • Tokenüberprüfung zum Schützen des API-Aufrufs
  • Objektmodell, Typisierung und IDE intellisense
  • Eingehende und ausgehende Validierung der API-Anforderungs- und Antwortschemas

Erste Schritte

Installieren des Pakets

Installieren Sie den Trigger für Authentifizierungsereignisse für Azure Functions mit NuGet:

dotnet add package Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents --prerelease

Voraussetzungen

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", auch bekannt als Zielgruppe, 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-Authentifizierungsdienst für Ereignisse 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 Eigenschaft Ihrer Ressourcenanwendung accessTokenAcceptedVersion auf 1 oder nullfestgelegt ist.

Es gibt drei Ansätze zum Authentifizieren von HTTP-Anforderungen für Ihre Funktions-App und zum Überprüfen des Tokens.

Überprüfen von Token mithilfe 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. Legen Sie die folgenden Funktionsanwendungseinstellungen fest.

  1. Wechseln Sie in Ihrer Funktions-App zur Registerkarte "Authentifizierung".
  2. Klicken Sie auf "Identitätsanbieter hinzufügen".
  3. Wählen Sie "Microsoft" als Identitätsanbieter aus.
  4. Wählen Sie "Details einer vorhandenen App-Registrierung angeben" aus.
  5. 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 azp Ansprüche oder appid im Token).

Wenn Sie Ihre API mit einem anderen Client testen möchten, bei dem es sich nicht um den Azure AD-Authentifizierungsdienst 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 angenommen.

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 in der Datei local.settings.json 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 angenommen.

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 folgenden Anwendungseinstellungen in der Datei local.settings.json fest :

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

Schnellstart

  • Visual Studio 2019

    • Starten von VisualStudio
    • Wählen Sie "Neues Projekt erstellen" aus.
    • Suchen Sie im Vorlagensuchbereich, und wählen Sie "AzureAuthEventsTrigger" aus.
    • Geben Sie Ihrem Projekt einen aussagekräftigen Projektnamen, einen aussagekräftigen Standort, einen Projektmappennamen und einen Projektmappennamen.

  • Visual Studio Code

    • Starten Sie Visual Studio Code.
    • Führen Sie den Befehl "Create Azure Authentication Events Trigger Project" über die Befehlspalette aus.
    • Befolgen Sie die Projekterstellungsaufforderungen.

  • Bitte beachten Sie: Bei einer ersten Ausführung kann es eine Weile dauern, bis die erforderlichen Pakete heruntergeladen werden.

  • Zu Entwicklungszwecken wenden Sie die Tokenvalidierung für Tests an:

  • Fügen Sie den AuthenticationEvents__BypassTokenValidation-Anwendungsschlüssel zum Abschnitt "Werte" in der Datei local.settings.json hinzu, und legen Sie den Wert auf true fest. Wenn Sie keine local.settings.json-Datei in Ihrer lokalen Umgebung haben, erstellen Sie eine datei im Stammverzeichnis Ihrer Funktions-App.

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "FUNCTIONS_WORKER_RUNTIME": "dotnet",
    "AuthenticationEvents__BypassTokenValidation": true
  }
}
  • Nachdem das Projekt geladen wurde, können Sie den Beispielcode ausführen. Die Anwendung des Azure Functions-Entwicklers sollte Ihren Endpunkt laden.

Wichtige Begriffe

.NET SDK

Die wichtigsten Konzepte des Azure .NET SDK finden Sie hier.

Benutzerdefinierte Azure AD-Erweiterungen

Mit benutzerdefinierten Erweiterungen können Sie Azure AD-Ereignisse verarbeiten, in externe Systeme integrieren und die Vorgänge in Ihrer Anwendungsauthentifizierung anpassen. Ein benutzerdefinierter Anspruchsanbieter ist beispielsweise eine benutzerdefinierte Erweiterung, mit der Sie Anwendungstoken mit Informationen von externen Systemen anreichern oder anpassen können, die nicht als Teil des Azure AD-Verzeichnisses gespeichert werden können.

Trigger für Authentifizierungsereignisse

Mit dem Trigger für Authentifizierungsereignisse kann eine Funktion ausgeführt werden, wenn ein Authentifizierungsereignis vom Azure AD-Ereignisdienst gesendet wird.

Ausgabebindung bei Authentifizierungsereignissen

Die Ausgabebindung für Authentifizierungsereignisse ermöglicht es einer Funktion, Authentifizierungsereignisaktionen an den Azure AD-Ereignisdienst zu senden.

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 die Vorschau verschoben wird, werden keine breaking Änderungen vorgenommen, und es wäre so einfach, die NuGet-Quelle zu entfernen, die auf die private Vorschau verweist.

Beispiele

Gehen Sie zum Testen der Tokenerweiterung wie folgt vor.

  • Starten Sie Visual Studio.
  • Öffnen Sie das Projekt, das im vorherigen Schritt erstellt wurde. (Schnellstart)
  • Führen Sie die Anwendung aus. (F5)
  • Nachdem die Anwendung des Azure Functions-Entwicklers gestartet wurde, kopieren Sie die Lausch-URL, die beim Starten der Anwendung angezeigt wird.
  • Hinweis: Alle Authentifizierungsfunktionen werden aufgelistet, falls ein Funktionslistener mit dem Namen "OnTokenIssuanceStart" registriert ist.
  • Ihr Funktionsendpunkt ist dann eine Kombination aus der Lausch-URL und -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/{tenantId}/applications/{resourceAppId}",
  "data":{
    "@odata.type": "microsoft.graph.onTokenIssuanceStartCalloutData",
    "tenantId": "30000000-0000-0000-0000-000000000003",
    "authenticationEventListenerId1": "10000000-0000-0000-0000-000000000001",
    "customAuthenticationExtensionId": "10000000-0000-0000-0000-000000000002",
    "authenticationContext1":{
      "correlationId": "20000000-0000-0000-0000-000000000002",
      "client": {
        "ip": "127.0.0.1",
        "locale": "en-us",
        "market": "en-au"
      },
      "authenticationProtocol": "OAUTH2.0",
      "clientServicePrincipal": {
        "id": "40000000-0000-0000-0000-000000000001",
        "appId": "40000000-0000-0000-0000-000000000002",
        "appDisplayName": "Test client app",
        "displayName": "Test client application"
      },
      "resourceServicePrincipal": {
        "id": "40000000-0000-0000-0000-000000000003",
        "appId": "40000000-0000-0000-0000-000000000004",
        "appDisplayName": "Test resource app",
        "displayName": "Test resource application"
      },
      "user": {
        "companyName": "Nick Gomez",
        "country": "USA",
        "createdDateTime": "0001-01-01T00:00:00Z",
        "displayName": "Dummy display name",
        "givenName": "Example",
        "id": "60000000-0000-0000-0000-000000000006",
        "mail": "test@example.com",
        "onPremisesSamAccountName": "testadmin",
        "onPremisesSecurityIdentifier": "DummySID",
        "onPremisesUserPrincipalName": "Dummy Name",
        "preferredDataLocation": "DummyDataLocation",
        "preferredLanguage": "DummyLanguage",
        "surname": "Test",
        "userPrincipalName": "testadmin@example.com",
        "userType": "UserTypeCloudManaged"
      }
    }
  }
}
  • 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 Bitte Azurite.
    • Wenn der folgende Fehler unter Windows angezeigt wird (es handelt sich um einen Fehler), wenn Sie versuchen, die erstellte Projektierung auszuführen.
    • Dies kann behoben werden, indem Sie diesen Befehl in PowerShell Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope LocalMachine ausführen weitere Informationen dazu 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. https://learn.microsoft.com/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 an 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.