Behandeln von Problemen mit Ihrer benutzerdefinierten Authentifizierungserweiterung
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:
Melden Sie sich beim Microsoft Entra Admin Center mindestens als Cloudanwendungsadministrator an.
Browsen Sie zu Identität>Anwendungen>Unternehmensanwendungen.
Wählen Sie Anmeldeprotokolle und dann das neueste Anmeldeprotokoll aus.
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:
- Abrufen eines Zugriffstokens mit einer Anwendungsregistrierung, die den benutzerdefinierten Authentifizierungserweiterungen zugeordnet ist
- Testen Sie Ihre API lokal mithilfe eines API-Testtools.
Öffnen Sie für lokale Entwicklungs- und Testzwecke local.settings.json, und ersetzen Sie den Code durch den folgenden JSON-Code:
{ "IsEncrypted": false, "Values": { "AzureWebJobsStorage": "", "AzureWebJobsSecretStorageType": "files", "FUNCTIONS_WORKER_RUNTIME": "dotnet", "AuthenticationEvents__BypassTokenValidation" : false } }
Hinweis
Wenn Sie das NuGet-Paket Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents verwendet haben, müssen Sie
"AuthenticationEvents__BypassTokenValidation" : true
für lokale Testzwecke festlegen.Erstellen Sie mithilfe Ihres bevorzugten API-Testtools eine neue HTTP-Anforderung, und legen Sie die HTTP-Methode auf
POST
fest.Fügen Sie den folgenden JSON-Text ein, der die Anforderung imitiert, die Microsoft Entra ID an Ihre REST-API sendet.
{ "type": "microsoft.graph.authenticationEvent.tokenIssuanceStart", "source": "/tenants/aaaabbbb-0000-cccc-1111-dddd2222eeee/applications/00001111-aaaa-2222-bbbb-3333cccc4444", "data": { "@odata.type": "microsoft.graph.onTokenIssuanceStartCalloutData", "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee", "authenticationEventListenerId": "11112222-bbbb-3333-cccc-4444dddd5555", "customAuthenticationExtensionId": "22223333-cccc-4444-dddd-5555eeee6666", "authenticationContext": { "correlationId": "aaaa0000-bb11-2222-33cc-444444dddddd", "client": { "ip": "127.0.0.1", "locale": "en-us", "market": "en-us" }, "protocol": "OAUTH2.0", "clientServicePrincipal": { "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb", "appId": "00001111-aaaa-2222-bbbb-3333cccc4444", "appDisplayName": "My Test application", "displayName": "My Test application" }, "resourceServicePrincipal": { "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb", "appId": "00001111-aaaa-2222-bbbb-3333cccc4444", "appDisplayName": "My Test application", "displayName": "My Test application" }, "user": { "companyName": "Casey Jensen", "createdDateTime": "2023-08-16T00:00:00Z", "displayName": "Casey Jensen", "givenName": "Casey", "id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee", "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.
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:
- 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.
- 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.
- 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.
- Führen Sie automatisierte Integrationstests für Ihre Authentifizierungen aus. Sie können auch API-Testtools verwenden, um nur Ihre API-Leistung zu testen.