Sdílet prostřednictvím

Odstraňování problémů s vlastním rozšířením ověřování

Události ověřování a vlastní poskytovatelé deklarací umožňují přizpůsobit prostředí ověřování služby 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 tak, aby přijímala tokeny s deklaracemi z externího úložiště.

Projev chyby

Když se volání rozhraní API nezdaří, chování chyby je následující:

  • U aplikací OpenId Connect – „Microsoft Entra ID“ přesměruje uživatele zpět do klientské aplikace s chybou. Token není ražený.
  • 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 k uživateli je všeobecný. 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 vlastních deklarací, musí rozhraní REST API zpracovávat záznamy. 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

Kromě protokolů rozhraní REST API a diagnostických řešení hostitelského 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é mohou ovlivnit přihlášení uživatelů. Protokoly přihlašování Microsoft Entra poskytují informace o stavu HTTP, kódu chyby, době trvání spuštění a počtu opakování, ke kterým došlo při volání rozhraní API 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:

  1. Přihlaste se do Centra pro správu Microsoft Entra jako alespoň správce cloudových aplikací.

  2. Přejděte dopodnikové aplikace>.

  3. Vyberte protokoly přihlášení a pak vyberte nejnovější protokol přihlášení.

  4. Další podrobnosti získáte tak, že vyberete kartu Události ověřování. Zobrazí se informace týkající se volání REST API pro vlastní rozšíření ověřování, včetně kódů chyb.

    Snímek obrazovky znázorňující informace o událostech ověřování

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 Neočekávaná chyba obsluhy událostí Při zpracování obslužné funkce události došlo k neočekávané chybě.
1003001 Neočekávaná chyba přizpůsobitelného rozšíření Při volání vlastního rozhraní API rozšíření došlo k neočekávané chybě.
1003002 Neplatný stav HTTP pro vlastní rozšíření 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 Neplatný obsah odpovědi vlastního rozšíření Při analýze textu odpovědi uživatelsky definované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 Chyba CustomExtensionThrottlingError Existuje příliš mnoho vlastních požadavků na rozšíření. Tato výjimka je vyvolána při volání rozhraní API vlastních rozšíření, když jsou dosaženy limity omezování.
1003005 Časový limit vlastní rozšíření vypršel Vlastní rozšíření neodpovědělo v rámci povoleného časového 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 Neplatný typ obsahu odpovědi pro uživatelské rozšíření Typ obsahu odpovědi vlastního rozšíření není 'application/json'.
1003007 VlastníRozšířeníNulovéOdpovědiNaNároky Rozhraní API vlastního rozšíření odpovědělo s prázdnou sadou deklarací identity.
1003008 Neplatná verze schématu API odpovědi vlastní rozšiřitelnosti Rozhraní API vlastního rozšíření neodpovědělo stejnou verzí apiSchema, ke které bylo voláno.
1003009 Vlastní rozšíření prázdná odpověď Text odpovědi rozhraní API vlastního rozšíření měl hodnotu null, když se to neočekávalo.
1003010 Neplatný počet akcí vlastní rozšíření Odpověď rozhraní API pro vlastní rozšíření obsahovala jiný počet akcí než akce podporované pro tento vlastní typ rozšíření.
1003011 VlastníRozšířeníNenalezeno Vlastní rozšíření přidružené k posluchači událostí nebylo nalezeno.
1003012 NeplatnýTypAkceVlastníhoRozšíření Vlastní rozšíření vrátilo neplatný typ akce definovaný pro tento vlastní typ rozšíření.
1003014 Nesprávný formát ID prostředku v přizpůsobeném rozšíření 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 CustomExtensionDomainNameNeodpovídá Cílová adresa URL a identifikátor zdroje (resourceId) vlastního rozšíření by měly mít stejný plně kvalifikovaný název domény.
1003016 Hlavní objekt služby CustomExtensionResource nenalezen AppId identifikátoru prostředku rozšíření by měl odpovídat opravdové hlavní službě v rámci nájemce.
1003017 Hlavní služba klienta pro vlastní rozšíření nebyla nalezena Hlavní objekt služby prostředku vlastního rozšíření není nalezen v tenantovi.
1003018 Služba klienta vlastních rozšíření je zakázána Hlavní služba vlastního rozšíření je v tomto tenantovi zakázána.
1003019 Zakázaný hlavní účet služby vlastního rozšíření Hlavní služba vlastního rozšíření je v tomto tenantovi zakázána.
1003020 Neplatný formát cílového URL v rozšíření na míru Cílová adresa URL je v nesprávném formátu. Musí to být platná adresa URL, která začíná https.
1003021 Oprávnění vlastního rozšíření nebylo uděleno hlavní službě Služební objekt nemá souhlas správce pro roli aplikace Microsoft Graph CustomAuthenticationExtensions.Receive.Payload (označovanou také jako oprávnění aplikace), která je nutná k tomu, aby aplikace mohla přijímat vlastní požadavky HTTP rozšíření ověřování.
1003022 Vlastní rozšíření: Service Principal pro MsGraph je zakázán nebo nebyl nalezen Hlavní služební účet MS Graph je v tomto nájemci zakázán nebo nebyl nalezen.
1003023 Vlastní rozšíření blokováno Koncový bod používaný pro vlastní rozšíření je blokován službou.
1003024 VelikostOdpovědiRozšířeníPřesáhlaLimit Velikost odpovědi vlastního rozšíření překročila maximální limit.
1003025 PřekročenaVelikostNárokůOdpovědiVlastníhoRozšíření Celková velikost nároků v odpovědi na vlastní rozšíření překročila maximální limit.
1003026 Nepodporovaný klíč žádného nebo prázdného nároku v rozšíření CustomExtension Rozhraní API vlastního rozšíření odpovědělo deklaracemi obsahujícími hodnotu null nebo prázdný klíč.
1003027 Chyba připojení k zařízení 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. Můžete otestovat své rozhraní API;

  • Získání přístupového tokenu s registrací aplikace spojenou s vlastními rozšířeními ověřování
  • Otestujte rozhraní API místně pomocí testovacího nástroje rozhraní API.

  1. 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í.

  2. Pomocí preferovaného testovacího nástroje rozhraní API vytvořte nový požadavek HTTP a nastavte metodu HTTP na POST.

  3. Použijte následující tělo JSON, které napodobuje požadavek, který Microsoft Entra ID odesílá k 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"
            }
        }
    }
}

    Doporučení

    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.

  4. 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 poskytovatele nároků nereaguje během 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ů:

  1. 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.
  2. 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.
  3. 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.
  4. 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é