Behandeln von Problemen im Zusammenhang mit Ihrer API für benutzerdefinierte Anspruchsanbieter

Mit Authentifizierungsereignissen und benutzerdefinierten Anspruchsanbietern können Sie die Microsoft Entra-Authentifizierung anpassen, indem Sie sie in externe Systeme integrieren. Beispielsweise können Sie eine benutzerdefinierte Anspruchsanbieter-API erstellen und eine OpenID Connect-App oder SAML-App so konfigurieren, dass Token mit Ansprüchen aus einem externen Speicher empfangen werden.

Fehlerverhalten

Wenn ein API-Aufruf fehlschlägt, ist das Fehlerverhalten wie folgt:

• Für OpenId Connect-Apps: Microsoft Entra ID leitet Benutzer*innen mit einem Fehler zurück zur Clientanwendung. Ein Token wird nicht erstellt.
• Für SAML-Apps: Microsoft Entra ID zeigt Benutzer*innen einen Fehlerbildschirm auf der Authentifizierungsoberfläche an. Der Benutzer wird nicht zurück zur Clientanwendung geleitet.

Der an die Anwendung oder den Benutzer zurückgesendete Fehlercode ist generisch. Überprüfen Sie zur Problembehandlung die Anmeldeprotokolle auf die Fehlercodes.

Protokollierung

Um Probleme mit dem REST-API-Endpunkt Ihres benutzerdefinierten Anspruchsanbieters zu beheben, muss die REST-API die Protokollierung verarbeiten. Azure Functions und andere API-Entwicklungsplattformen bieten detaillierte Protokollierungslösungen. Verwenden Sie diese Lösungen, um detaillierte Informationen zum Verhalten der APIs zu erhalten und Probleme mit der API-Logik zu beheben.

Microsoft Entra-Anmeldeprotokolle

Tipp

Die Schritte in diesem Artikel können je nach dem Portal, mit dem Sie beginnen, geringfügig variieren.

Sie können zusätzlich zu Ihren REST-API-Protokollen auch Microsoft Entra-Anmeldeprotokolle und Diagnoselösungen für Hostingumgebungen verwenden. Mithilfe von Microsoft Entra-Anmeldeprotokollen können Sie Fehler finden, die sich auf die Anmeldungen der Benutzer*innen auswirken können. Die Microsoft Entra-Anmeldeprotokolle enthalten Informationen über den HTTP-Status, den Fehlercode, die Ausführungsdauer und die Anzahl der Wiederholungsversuche, die beim Aufruf der API durch Microsoft Entra ID aufgetreten sind.

Microsoft Entra-Anmeldeprotokolle können auch in Azure Monitor integriert werden. Sie können Warnungen und Überwachung einrichten, die Daten visualisieren und in SIEM-Tools (Security Information and Event Management) integrieren. Sie können beispielsweise Benachrichtigungen einrichten, wenn die Anzahl der Fehler einen bestimmten von Ihnen gewählten Schwellenwert überschreitet.

So greifen Sie auf die Microsoft Entra-Anmeldeprotokolle zu:

1. Melden Sie sich beim Microsoft Entra Admin Center mindestens mit der Rolle Cloudanwendungsadministrator an.

2. Browsen Sie zu Identität>Anwendungen>Unternehmensanwendungen.

3. Wählen Sie Anmeldeprotokolle und dann das neueste Anmeldeprotokoll aus.

4. Für weitere Informationen wählen Sie die Registerkarte Authentifizierungsereignisse aus. Informationen im Zusammenhang mit dem REST-API-Aufruf der benutzerdefinierten Authentifizierungserweiterung werden einschließlich aller Fehlercodes angezeigt.

   

Referenz zu Fehlercodes

Verwenden Sie die folgende Tabelle, um einen Fehlercode zu diagnostizieren.

Fehlercode	Fehlerbezeichnung	BESCHREIBUNG
1003000	EventHandlerUnexpectedError	Beim Verarbeiten eines Ereignishandlers ist ein unerwarteter Fehler aufgetreten.
1003001	CustomExtenstionUnexpectedError	Beim Aufrufen einer benutzerdefinierten Erweiterungs-API ist ein unerwarteter Fehler aufgetreten.
1003002	CustomExtensionInvalidHTTPStatus	Die benutzerdefinierte Erweiterungs-API hat einen ungültigen HTTP-Statuscode zurückgegeben. Überprüfen Sie, ob die API einen zulässigen Statuscode zurückgibt, der für diesen benutzerdefinierten Erweiterungstyp definiert ist.
1003003	CustomExtensionInvalidResponseBody	Beim Analysieren des Antworttexts der benutzerdefinierten Erweiterung ist ein Problem aufgetreten. Überprüfen Sie, ob der API-Antworttext ein zulässiges Schema für diesen benutzerdefinierten Erweiterungstyp aufweist.
1003004	CustomExtensionThrottlingError	Es gibt zu viele Anforderungen der benutzerdefinierten Erweiterung. Diese Ausnahme wird für API-Aufrufe der benutzerdefinierten Erweiterung ausgelöst, wenn Einschränkungsgrenzwerte erreicht wurden.
1003005	CustomExtensionTimedOut	Die benutzerdefinierte Erweiterung hat nicht innerhalb des zulässigen Timeouts geantwortet. Überprüfen Sie, ob Ihre API innerhalb des konfigurierten Timeouts für die benutzerdefinierte Erweiterung antwortet. Dies kann auch darauf hinweisen, dass das Zugriffstoken ungültig ist. Führen Sie die Schritte aus, um Ihre REST-API direkt aufzurufen.
1003006	CustomExtensionInvalidResponseContentType	Der Antwortinhaltstyp der benutzerdefinierten Erweiterung lautet nicht „application/json“.
1003007	CustomExtensionNullClaimsResponse	Die benutzerdefinierte Erweiterungs-API hat mit einem NULL-Anspruchsbehälter geantwortet.
1003008	CustomExtensionInvalidResponseApiSchemaVersion	Die benutzerdefinierte Erweiterungs-API hat nicht mit derselben apiSchemaVersion geantwortet, für die sie aufgerufen wurde.
1003009	CustomExtensionEmptyResponse	Der Antworttext der benutzerdefinierten Erweiterungs-API war NULL, obwohl dies nicht erwartet wurde.
1003010	CustomExtensionInvalidNumberOfActions	Die Antwort der benutzerdefinierten Erweiterungs-API enthielt eine andere Anzahl Aktionen als die, die für diesen benutzerdefinierten Erweiterungstyp unterstützt werden.
1003011	CustomExtensionNotFound	Die einem Ereignislistener zugeordnete benutzerdefinierte Erweiterung wurde nicht gefunden.
1003012	CustomExtensionInvalidActionType	Die benutzerdefinierte Erweiterung hat einen ungültigen Aktionstyp zurückgegeben, der für diesen benutzerdefinierten Erweiterungstyp definiert wurde.
1003014	CustomExtensionIncorrectResourceIdFormat	Die Eigenschaft identifierUris im Manifest für die Anwendungsregistrierung der benutzerdefinierten Erweiterung sollte das Format „api://{vollqualifizierter Domänenname}/{appid}“ aufweisen.
1003015	CustomExtensionDomainNameDoesNotMatch	TargetUrl und resourceId der benutzerdefinierten Erweiterung sollten den gleichen vollqualifizierten Domänennamen aufweisen.
1003016	CustomExtensionResourceServicePrincipalNotFound	Die appId der resourceId der benutzerdefinierten Erweiterung muss einem echten Dienstprinzipal im Mandanten entsprechen.
1003017	CustomExtensionClientServicePrincipalNotFound	Der Ressourcen-Dienstprinzipal der benutzerdefinierten Erweiterung wurde im Mandanten nicht gefunden.
1003018	CustomExtensionClientServiceDisabled	Der Ressourcen-Dienstprinzipal der benutzerdefinierten Erweiterung ist in diesem Mandanten deaktiviert.
1003019	CustomExtensionResourceServicePrincipalDisabled	Der Ressourcen-Dienstprinzipal der benutzerdefinierten Erweiterung ist in diesem Mandanten deaktiviert.
1003020	CustomExtensionIncorrectTargetUrlFormat	Die Ziel-URL weist ein falsches Format auf. Es muss sich um eine gültige URL handeln, die mit https beginnt.
1003021	CustomExtensionPermissionNotGrantedToServicePrincipal	Der Dienstprinzipal besitzt keine Administratoreinwilligung für die Microsoft Graph CustomAuthenticationExtensions.Receive.Payload-App-Rolle (auch als Anwendungsberechtigung bezeichnet), die erforderlich ist, damit die App benutzerdefinierte Authentifizierungserweiterungs-HTTP-Anforderungen empfängt.
1003022	CustomExtensionMsGraphServicePrincipalDisabledOrNotFound	Der MS Graph-Dienstprinzipal ist deaktiviert oder wurde in diesem Mandanten nicht gefunden.
1003023	CustomExtensionBlocked	Der für die benutzerdefinierte Erweiterung verwendete Endpunkt wird vom Dienst blockiert.
1003024	CustomExtensionResponseSizeExceeded	Die Antwortgröße der benutzerdefinierten Erweiterung hat den Höchstwert überschritten.
1003025	CustomExtensionResponseClaimsSizeExceeded	Die Gesamtgröße der Ansprüche in der Antwort der benutzerdefinierten Erweiterung hat den Höchstwert überschritten.
1003026	CustomExtensionNullOrEmptyClaimKeyNotSupported	Die benutzerdefinierte Erweiterungs-API hat mit Ansprüchen geantwortet, die NULL oder einen leeren Schlüssel enthalten.
1003027	CustomExtensionConnectionError	Fehler beim Herstellen einer Verbindung mit der benutzerdefinierten Erweiterungs-API.

Rufen Sie die REST-API direkt auf.

Ihre REST-API wird durch das Microsoft Entra-Zugriffstoken geschützt. So können Sie Ihre API testen:

• Rufen Sie ein Zugriffstoken mit einer Anwendungsregistrierung ab, die den benutzerdefinierten Authentifizierungserweiterungen zugeordnet ist.
• Testen Sie Ihre API lokal mithilfe eines API-Testtools.

Abrufen eines Zugriffstokens

Nachdem Sie ein Zugriffstoken abgerufen haben, übergeben Sie es an den HTTP-Authorization-Header. Führen Sie die folgenden Schritte aus, um ein Zugriffstoken abzurufen:

1. Melden Sie sich beim Microsoft Entra Admin Center mindestens mit der Rolle Cloudanwendungsadministrator an.

2. Navigieren Sie zu Identität>Anwendungen>Anwendungsregistrierungen.

3. Wählen Sie die App-Registrierung Azure Functions-Authentifizierungsereignis-API aus, die Sie zuvor mithilfe von Konfigurieren eines benutzerdefinierten Anspruchsanbieters für ein Tokenausstellungsereignis (Vorschau) konfiguriert haben.

4. Kopieren Sie die Anwendungs-ID.

5. Wenn Sie kein App-Geheimnis erstellt haben, führen Sie die folgenden Schritte aus:

   1. Wählen Sie Zertifikate und Geheimnisse>Geheime Clientschlüssel>Neuer geheimer Clientschlüssel aus.
   2. Fügen Sie eine Beschreibung für Ihren geheimen Clientschlüssel hinzu.
   3. Wählen Sie für das Geheimnis eine Ablauffrist aus, oder geben Sie eine benutzerdefinierte Lebensdauer an.
   4. Wählen Sie Hinzufügen.
   5. Notieren Sie sich den Wert des geheimen Clientschlüssels, der in Ihrem Clientanwendungscode verwendet werden soll. Dieser Geheimniswert kann nach Verlassen dieser Seite nicht erneut angezeigt werden.

6. Wählen Sie im Menü Eine API verfügbar machen aus, und kopieren Sie den Wert des Anwendungs-ID-URI. Beispiel: api://contoso.azurewebsites.net/00001111-aaaa-2222-bbbb-3333cccc4444.

7. Öffnen Sie Ihr bevorzugtes API-Testtool, und erstellen Sie eine neue HTTP-Abfrage.

8. Ändern Sie die HTTP-Methode in POST.

9. Geben Sie die folgende URL ein. Ersetzen Sie {tenantID} durch Ihre Mandanten-ID.

   https://login.microsoftonline.com/{tenantID}/oauth2/v2.0/token
   

10. Wählen Sie unter Textkörper die Option form-data aus, und fügen Sie die folgenden Schlüssel hinzu:

    Schlüssel	Wert
    grant_type	client_credentials
    client_id	Die Client-ID der Anwendung.
    client_secret	Den geheimen Clientschlüssel der Anwendung.
    scope	Die Anwendungs-ID-URI der Anwendung, und fügen Sie dann .default hinzu. Beispiel: api://contoso.azurewebsites.net/00001111-aaaa-2222-bbbb-3333cccc4444/.default

11. Führen Sie die HTTP-Abfrage aus, und kopieren Sie das access_token in die Web-App https://jwt.ms.

12. Vergleichen Sie den iss mit dem Ausstellernamen, den Sie in Ihrer API konfiguriert haben.

13. Vergleichen Sie den aud mit der Client-ID, die Sie in Ihrer API konfiguriert haben.

API-Testtools

Führen Sie die folgenden Schritte aus, um Ihre API direkt mit Ihrem bevorzugten API-Testtool zu testen:

Hinweis

Wenn Sie das NuGet-Paket Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents verwendet haben, deaktivieren Sie die Tokenüberprüfung für Testzwecke. Öffnen Sie die Datei local.settings.json, und fügen Sie den folgenden Parameter hinzu:

"AuthenticationEvents__BypassTokenValidation": true

Entfernen Sie ihn nach Abschluss des Tests wieder.

1. Deaktivieren Sie in Ihrer REST-API die appid- oder azp-Anspruchsüberprüfung. Erfahren Sie, wie Sie die zuvor erstellte Funktions-API bearbeiten.

2. Erstellen Sie eine neue HTTP-Anforderung, und legen Sie die HTTP-Methode auf POST fest.

3. Wählen Sie im Textkörper die Option Raw und dann JSON aus.

4. Fügen Sie den folgenden JSON-Code ein, der die Anforderung imitiert, die Microsoft Entra ID an Ihre REST-API sendet.

   {
       "type": "microsoft.graph.authenticationEvent.tokenIssuanceStart",
       "source": "/tenants/<Your tenant GUID>/applications/<Your Test Application App Id>",
       "data": {
           "@odata.type": "microsoft.graph.onTokenIssuanceStartCalloutData",
           "tenantId": "<Your tenant GUID>",
           "authenticationEventListenerId": "<GUID>",
           "customAuthenticationExtensionId": "<Your custom authentication extension ID>",
           "authenticationContext": {
               "correlationId": "<Enter correlation ID here>",
               "client": {
                   "ip": "127.0.0.1",
                   "locale": "en-us",
                   "market": "en-us"
               },
               "protocol": "OAUTH2.0",
               "clientServicePrincipal": {
                   "id": "<Your Test Applications servicePrincipal objectId>",
                   "appId": "<Your Test Application App Id>",
                   "appDisplayName": "My Test application",
                   "displayName": "My Test application"
               },
               "resourceServicePrincipal": {
                   "id": "<Your Test Applications servicePrincipal objectId>",
                   "appId": "<Your Test Application App Id>",
                   "appDisplayName": "My Test application",
                   "displayName": "My Test application"
               },
               "user": {
                   "companyName": "Casey Jensen",
                   "createdDateTime": "2023-08-16T00:00:00Z",
                   "displayName": "Casey Jensen",
                   "givenName": "Casey",
                   "id": "90847c2a-e29d-4d2f-9f54-c5b4d3f26471", // Client ID representing the Microsoft Entra authentication events service
                   "mail": "casey@contoso.com",
                   "onPremisesSamAccountName": "Casey Jensen",
                   "onPremisesSecurityIdentifier": "<Enter Security Identifier>",
                   "onPremisesUserPrincipalName": "Casey Jensen",
                   "preferredLanguage": "en-us",
                   "surname": "Jensen",
                   "userPrincipalName": "casey@contoso.com",
                   "userType": "Member"
               }
           }
       }
   }
   

   Tipp

   Wenn Sie ein aus Microsoft Entra ID abgerufenes Zugriffstoken verwenden, wählen Sie Autorisierung und anschließend Bearertokenaus, und fügen Sie dann das Zugriffstoken aus Microsoft Entra ID ein.

5. Nach dem Klicken auf Senden sollten Sie eine JSON-Antwort erhalten, die in etwa Folgendem entspricht:

   {
       "data": {
           "@odata.type": "microsoft.graph.onTokenIssuanceStartResponseData",
           "actions": [
               {
                   "@odata.type": "microsoft.graph.tokenIssuanceStart.provideClaimsForToken",
                   "claims": {
                       "customClaim1": "customClaimValue1",
                       "customClaim2": [
                           "customClaimString1",
                           "customClaimString2" 
                       ]
                   }
               }
   
           ]
       }
   }
   

Allgemeine Leistungsverbesserungen

Eines der häufigsten Probleme ist, dass Ihre benutzerdefinierte Anspruchsanbieter-API nicht innerhalb des Timeouts von zwei Sekunden reagiert. Wenn Ihre REST-API bei nachfolgenden Wiederholungen nicht reagiert, schlägt die Authentifizierung fehl. Befolgen Sie die folgenden Vorschläge, um die Leistung Ihrer REST-API zu verbessern:

1. Wenn Ihre API auf nachgeschaltete APIs zugreift, speichern Sie das Zugriffstoken zwischen, das zum Aufrufen dieser APIs verwendet wird, damit nicht bei jeder Ausführung ein neues Token abgerufen werden muss.
2. Leistungsprobleme beziehen sich häufig auf nachgelagerte Dienste. Fügen Sie die Protokollierung hinzu, mit der die Prozesszeit für den Aufruf von nachgeschalteten Diensten aufgezeichnet wird.
3. Wenn Sie einen Cloudanbieter zum Hosten Ihrer API verwenden, verwenden Sie einen Hostingplan, der die API immer betriebsbereit hält. Bei Azure Functions kann es sich entweder um den Premium-Plan oder um einen dedizierten Plan handelt.
4. Führen Sie automatisierte Integrationstests für Ihre Authentifizierungen aus. Sie können auch API-Testtools verwenden, um nur Ihre API-Leistung zu testen.

Weitere Informationen

• Erstellen einer REST-API mit einem Startereignis für die Tokenausstellung
• Konfigurieren einer SAML-App zum Empfangen von Token mit Ansprüchen aus einem externen Speicher
• Referenz zu benutzerdefinierten Anspruchsanbietern (Artikel)