Řešení potíží s vlastním rozhraním API zprostředkovatele deklarací identity

Článek
04/10/2024

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 Připojení nebo aplikaci SAML tak, aby přijímaly 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 Připojení – Microsoft Entra ID 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 protokolechpř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.

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ň cloudová aplikace Správa istrator.
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	CustomExtension Připojení ionError	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.

Testovací nástroje rozhraní API
Získání přístupového tokenu

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" : true pro úč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" 
                    ]
                }
            }

        ]
    }
}

Po získání přístupového tokenu ho předejte hlavičku HTTP Authorization . Přístupový token získáte takto:

Přihlaste se do Centra pro správu Microsoft Entra jako alespoň cloudová aplikace Správa istrator.
Přejděte k registracím> aplikací identit.>
Vyberte registraci aplikace API pro události ověřování Azure Functions, která byla dříve nakonfigurována v konfiguraci vlastního zprostředkovatele deklarací identity pro událost vystavení tokenu.
Zkopírujte ID aplikace.
Pokud jste nevytvořili tajný kód aplikace, postupujte takto:
1. Vyberte Certifikáty a tajné>klíče>klienta Nové tajné klíče klienta.
2. Přidejte popis tajného kódu klienta.
3. Vyberte vypršení platnosti tajného kódu nebo zadejte vlastní životnost.
4. Vyberte Přidat.
5. Poznamenejte si hodnotu tajného kódu pro použití v kódu klientské aplikace. Po opuštění této stránky se tento tajný kód už nikdy nezobrazí.
V nabídce vyberte Zveřejnit rozhraní API a zkopírujte hodnotu identifikátoru URI ID aplikace. Například api://contoso.azurewebsites.net/00001111-aaaa-2222-bbbb-3333cccc4444.
Otevřete upřednostňovaný nástroj pro testování rozhraní API a vytvořte nový dotaz HTTP.
Změňte metodu HTTP na POST.
Zadejte následující adresu URL. Nahraďte ID tenanta {tenantID} .
```
https://login.microsoftonline.com/{tenantID}/oauth2/v2.0/token
```

V části Text vyberte data formuláře a přidejte následující klíče:

Key	Hodnota
`grant_type`	`client_credentials`
`client_id`	ID klienta vaší aplikace.
`client_secret`	Tajný klíč klienta vaší aplikace.
`scope`	Identifikátor URI ID aplikace a pak přidejte `.default`. Například `api://contoso.azurewebsites.net/00001111-aaaa-2222-bbbb-3333cccc4444/.default`

Spusťte dotaz HTTP a zkopírujte ho access_tokenhttps://jwt.ms do webové aplikace.
iss Porovnejte název vystavitele, který jste nakonfigurovali ve svém rozhraní API.
aud Porovnejte s ID klienta, které jste nakonfigurovali ve svém rozhraní API.

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

Sdílet prostřednictvím