Řešení potíží s vlastním rozšířením ověřování
Události ověřování a vlastní zprostředkovatelé deklarací identity umožňují přizpůsobit prostředí ověřování Microsoft Entra integrací s externími systémy. Můžete například vytvořit vlastní rozhraní API zprostředkovatele deklarací identity a nakonfigurovat aplikaci OpenID Connect nebo aplikaci SAML tak, aby přijímala tokeny s deklaracemi z externího úložiště.
Chování chyby
Když se volání rozhraní API nezdaří, chování chyby je následující:
- U aplikací OpenId Connect – ID Microsoft Entra přesměruje uživatele zpět do klientské aplikace s chybou. Token není vytěsněný.
- U aplikací SAML – ID Microsoft Entra zobrazuje uživateli chybovou obrazovku v prostředí ověřování. Uživatel se nepřesměruje zpět do klientské aplikace.
Kód chyby odeslaný zpět do aplikace nebo uživatel je obecný. Pokud chcete potíže vyřešit, zkontrolujte kódy chyb v protokolech přihlašování.
Protokolování
Aby bylo možné řešit problémy s koncovým bodem rozhraní REST API zprostředkovatele deklarací identity, musí rozhraní REST API zpracovávat protokolování. Azure Functions a další platformy pro vývoj rozhraní API poskytují podrobná řešení protokolování. Pomocí těchto řešení získáte podrobné informace o chování rozhraní API a řešení potíží s logikou rozhraní API.
Protokoly přihlašování Microsoft Entra
Tip
Postup v tomto článku se může mírně lišit v závislosti na portálu, od který začínáte.
Kromě protokolů rozhraní REST API a hostování diagnostických řešení prostředí můžete použít také protokoly přihlašování Microsoft Entra. Pomocí protokolů přihlašování Microsoft Entra můžete najít chyby, které můžou mít vliv na přihlášení uživatelů. Protokoly přihlášení Microsoft Entra poskytují informace o stavu HTTP, kódu chyby, době trvání spuštění a počtu opakování, ke kterým rozhraní API došlo, volal Microsoft Entra ID.
Protokoly přihlašování Microsoft Entra se také integrují se službou Azure Monitor. Můžete nastavit výstrahy a monitorování, vizualizovat data a integrovat je s nástroji pro správu událostí a informací o zabezpečení (SIEM). Pokud například počet chyb překročí určitou prahovou hodnotu, kterou zvolíte, můžete nastavit oznámení.
Přístup k protokolům přihlašování Microsoft Entra:
Přihlaste se do Centra pro správu Microsoft Entra jako alespoň správce cloudových aplikací.
Přejděte k podnikovým aplikacím> identit.>
Vyberte protokoly přihlášení a pak vyberte nejnovější protokol přihlášení.
Další podrobnosti získáte tak, že vyberete kartu Události ověřování. Zobrazí se informace související s voláním rozhraní REST API vlastního rozšíření ověřování, včetně kódů chyb.
Referenční informace ke kódům chyb
K diagnostice kódu chyby použijte následující tabulku.
| Kód chyby | Název chyby | Popis |
|---|---|---|
| 1003000 | EventHandlerUnexpectedError | Při zpracování obslužné rutiny události došlo k neočekávané chybě. |
| 1003001 | CustomExtenstionUnexpectedError | Při volání vlastního rozhraní API rozšíření došlo k neočekávané chybě. |
| 1003002 | CustomExtensionInvalidHTTPStatus | Rozhraní API vlastního rozšíření vrátilo neplatný stavový kód HTTP. Zkontrolujte, jestli rozhraní API vrací přijatý stavový kód definovaný pro tento vlastní typ rozšíření. |
| 1003003 | CustomExtensionInvalidResponseBody | Při analýze textu odpovědi vlastního rozšíření došlo k potížím. Zkontrolujte, jestli je tělo odpovědi rozhraní API v přijatelném schématu pro tento vlastní typ rozšíření. |
| 1003004 | CustomExtensionThrottlingError | Existuje příliš mnoho vlastních požadavků na rozšíření. Tato výjimka se vyvolá pro volání rozhraní API vlastních rozšíření při dosažení limitů omezování. |
| 1003005 | CustomExtensionTimedOut | Vlastní rozšíření neodpovědělo v povoleném časovém limitu. Zkontrolujte, že vaše rozhraní API reaguje v rámci nakonfigurovaného časového limitu pro vlastní rozšíření. Může také znamenat, že přístupový token je neplatný. Postupujte podle pokynů k přímému volání rozhraní REST API. |
| 1003006 | CustomExtensionInvalidResponseContentType | Typ obsahu odpovědi vlastního rozšíření není application/json. |
| 1003007 | CustomExtensionNullClaimsResponse | Rozhraní API vlastního rozšíření odpovědělo s taškou deklarací identity null. |
| 1003008 | CustomExtensionInvalidResponseApiSchemaVersion | Rozhraní API vlastního rozšíření neodpovědělo se stejným rozhraním apiSchemaVersion, ke kterému bylo volána. |
| 1003009 | CustomExtensionEmptyResponse | Text odpovědi rozhraní API vlastního rozšíření měl hodnotu null, pokud se to neočekávalo. |
| 1003010 | CustomExtensionInvalidNumberOfActions | Odpověď rozhraní API pro vlastní rozšíření obsahovala jiný počet akcí než akce podporované pro tento vlastní typ rozšíření. |
| 1003011 | CustomExtensionNotFound | Vlastní rozšíření přidružené k naslouchacímu procesu událostí se nepodařilo najít. |
| 1003012 | CustomExtensionInvalidActionType | Vlastní rozšíření vrátilo neplatný typ akce definovaný pro tento vlastní typ rozšíření. |
| 1003014 | CustomExtensionIncorrectResourceIdFormat | Vlastnost identifierUris v manifestu pro registraci aplikace pro vlastní rozšíření by měla být ve formátu "api://{plně kvalifikovaný název domény}/{appid}. |
| 1003015 | CustomExtensionDomainNameDoesNotMatch | TargetUrl a resourceId vlastního rozšíření by měly mít stejný plně kvalifikovaný název domény. |
| 1003016 | CustomExtensionResourceServicePrincipalNotFound | AppId vlastního id prostředku rozšíření by měl odpovídat skutečnému instančnímu objektu v tenantovi. |
| 1003017 | CustomExtensionClientServicePrincipalNotFound | Instanční objekt prostředku vlastního rozšíření není v tenantovi nalezen. |
| 1003018 | CustomExtensionClientServiceDisabled | Instanční objekt prostředku vlastního rozšíření je v tomto tenantovi zakázaný. |
| 1003019 | CustomExtensionResourceServicePrincipalDisabled | Instanční objekt prostředku vlastního rozšíření je v tomto tenantovi zakázaný. |
| 1003020 | CustomExtensionIncorrectTargetUrlFormat | Cílová adresa URL je v nesprávném formátu. Musí to být platná adresa URL, která začíná https. |
| 1003021 | CustomExtensionPermissionNotGrantedToServicePrincipal | Instanční objekt nemá souhlas správce pro roli aplikace Microsoft Graph CustomAuthenticationExtensions.Receive.Payload (označovanou také jako oprávnění aplikace), která je nutná pro příjem vlastních požadavků HTTP rozšíření ověřování. |
| 1003022 | CustomExtensionMsGraphServicePrincipalDisabledOrNotFound | Instanční objekt MS Graphu je v tomto tenantovi zakázaný nebo se nenašel. |
| 1003023 | CustomExtensionBlocked | Služba blokuje koncový bod používaný pro vlastní rozšíření. |
| 1003024 | CustomExtensionResponseSizeExceededed | Velikost odpovědi vlastního rozšíření překročila maximální limit. |
| 1003025 | CustomExtensionResponseClaimsSizeExceed | Celková velikost deklarací identity v odpovědi vlastního rozšíření překročila maximální limit. |
| 1003026 | CustomExtensionNullOrEmptyClaimKeyNotSupported | Rozhraní API vlastního rozšíření odpovědělo deklaracemi obsahujícími hodnotu null nebo prázdný klíč. |
| 1003027 | CustomExtensionConnectionError | Při připojování k vlastnímu rozhraní API rozšíření došlo k chybě. |
Přímé volání rozhraní REST API
Vaše rozhraní REST API je chráněné přístupovým tokenem Microsoft Entra. Rozhraní API můžete otestovat podle;
- Získání přístupového tokenu s registrací aplikace přidruženou k vlastním rozšířením ověřování
- Otestujte rozhraní API místně pomocí testovacího nástroje rozhraní API.
Pro účely místního vývoje a testování otevřete local.settings.json a nahraďte kód následujícím kódem JSON:
{ "IsEncrypted": false, "Values": { "AzureWebJobsStorage": "", "AzureWebJobsSecretStorageType": "files", "FUNCTIONS_WORKER_RUNTIME": "dotnet", "AuthenticationEvents__BypassTokenValidation" : false } }Poznámka:
Pokud jste použili balíček NuGet Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents , nezapomeňte nastavit
"AuthenticationEvents__BypassTokenValidation" : truepro účely místního testování.Pomocí preferovaného testovacího nástroje rozhraní API vytvořte nový požadavek HTTP a nastavte metodu HTTP na
POST.Použijte následující text JSON, který napodobuje požadavek Microsoft Entra ID odesílá do rozhraní REST API.
{ "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" } } } }Tip
Pokud používáte přístupový token získaný z ID Microsoft Entra, vyberte Autorizaci a pak vyberte Nosný token a vložte přístupový token, který jste získali z Microsoft Entra ID.
Vyberte Odeslat a měli byste obdržet odpověď JSON podobnou této:
{ "data": { "@odata.type": "microsoft.graph.onTokenIssuanceStartResponseData", "actions": [ { "@odata.type": "microsoft.graph.tokenIssuanceStart.provideClaimsForToken", "claims": { "customClaim1": "customClaimValue1", "customClaim2": [ "customClaimString1", "customClaimString2" ] } } ] } }
Běžná vylepšení výkonu
Jedním z nejběžnějších problémů je, že vaše rozhraní API zprostředkovatele deklarací identity nereaguje během časového limitu dvousekundového časového limitu. Pokud vaše rozhraní REST API nereaguje v dalších opakováních, ověřování se nezdaří. Pokud chcete zvýšit výkon rozhraní REST API, postupujte podle následujících návrhů:
- Pokud vaše rozhraní API přistupuje k jakýmkoli podřízeným rozhraním API, uloží přístupový token použitý k volání těchto rozhraní API do mezipaměti, takže při každém spuštění není nutné získat nový token.
- Problémy s výkonem často souvisejí s podřízenými službami. Přidejte protokolování, které zaznamenává dobu procesu volání do všech podřízených služeb.
- Pokud k hostování rozhraní API používáte poskytovatele cloudu, použijte plán hostování, který rozhraní API udržuje vždy "teplé". Pro Azure Functions to může být plán Premium nebo plán Dedicated.
- Spusťte automatizované integrační testy pro vaše ověřování. K otestování výkonu rozhraní API můžete použít také testovací nástroje rozhraní API.
Viz také
- Vytvoření rozhraní REST API s počáteční událostí vystavení tokenu
- Konfigurace aplikace SAML pro příjem tokenů s deklaracemi identity z externího úložiště
- Článek s referenčními informacemi o vlastních zprostředkovateli deklarací identity