Egyéni jogcímszolgáltatói API hibaelhárítása
A hitelesítési események és az egyéni jogcímszolgáltatók lehetővé teszik a Microsoft Entra hitelesítési élményének testreszabását külső rendszerekkel való integrációval. Létrehozhat például egy egyéni jogcímszolgáltatói API-t, és konfigurálhat egy OpenID Csatlakozás alkalmazást vagy SAML-alkalmazást, hogy jogkivonatokat fogadjon egy külső áruházból származó jogcímekkel.
Hiba viselkedése
Ha egy API-hívás meghiúsul, a hiba viselkedése a következő:
- OpenId Csatlakozás-alkalmazások esetén a Microsoft Entra ID hiba miatt visszairányítja a felhasználót az ügyfélalkalmazásba. A jogkivonat nincs mentve.
- SAML-alkalmazások esetén – A Microsoft Entra ID egy hibaképernyőt jelenít meg a felhasználónak a hitelesítési felületen. A rendszer nem irányítja vissza a felhasználót az ügyfélalkalmazásba.
Az alkalmazásnak vagy a felhasználónak visszaküldött hibakód általános. A hibaelhárításhoz ellenőrizze a bejelentkezési naplókban a hibakódokat.
Naplózás
Az egyéni jogcímszolgáltató REST API-végpontjával kapcsolatos problémák elhárításához a REST API-nak kezelnie kell a naplózást. Az Azure Functions és más API-fejlesztési platformok részletes naplózási megoldásokat biztosítanak. Ezekkel a megoldásokkal részletes információkat kaphat az API-k viselkedéséről, és elháríthatja az API-logikát.
Microsoft Entra bejelentkezési naplók
Tipp.
A cikkben szereplő lépések a portáltól függően kissé eltérhetnek.
A REST API-naplók mellett a Microsoft Entra bejelentkezési naplóit is használhatja, valamint környezeti diagnosztikai megoldásokat is üzemeltethet. A Microsoft Entra bejelentkezési naplóinak használatával olyan hibákat talál, amelyek hatással lehetnek a felhasználók bejelentkezésére. A Microsoft Entra bejelentkezési naplói információt nyújtanak a HTTP-állapotról, a hibakódról, a végrehajtás időtartamáról és az API-t a Microsoft Entra ID által meghívott újrapróbálkozások számáról.
A Microsoft Entra bejelentkezési naplói integrálhatók az Azure Monitorral is. Riasztásokat és monitorozást állíthat be, megjelenítheti az adatokat, és integrálható a biztonsági információ- és eseménykezelési (SIEM) eszközökkel. Beállíthatja például az értesítéseket, ha a hibák száma meghaladja a választott küszöbértéket.
A Microsoft Entra bejelentkezési naplóinak elérése:
Jelentkezzen be a Microsoft Entra felügyeleti központba legalább egy felhőalapú alkalmazásként Rendszergazda istratorként.
Keresse meg az Identity>Applications>Enterprise-alkalmazásokat.
Válassza ki a bejelentkezési naplókat, majd válassza ki a legújabb bejelentkezési naplót.
További részletekért válassza a Hitelesítési események lapot. Megjelenik az egyéni hitelesítési bővítmény REST API-hívásával kapcsolatos információ, beleértve a hibakódokat is.
Hibakódok referenciája
Hibakód diagnosztizálásához használja az alábbi táblázatot.
Hibakód | Hiba neve | Leírás |
---|---|---|
1003000 | EventHandlerUnexpectedError | Váratlan hiba történt egy eseménykezelő feldolgozásakor. |
1003001 | CustomExtenstionUnexpectedError | Váratlan hiba történt egy egyéni bővítmény API meghívása közben. |
1003002 | CustomExtensionInvalidHTTPStatus | Az egyéni bővítmény API érvénytelen HTTP-állapotkódot adott vissza. Ellenőrizze, hogy az API az adott egyéni bővítménytípushoz definiált elfogadott állapotkódot adja-e vissza. |
1003003 | CustomExtensionInvalidResponseBody | Hiba történt az egyéni bővítmény választörzsének elemzésekor. Ellenőrizze, hogy az API választörzse elfogadható sémában van-e az adott egyéni bővítménytípushoz. |
1003004 | CustomExtensionThrottlingError | Túl sok egyéni bővítménykérés van. Ez a kivétel egyéni bővítmény API-hívások esetén jelenik meg, amikor a szabályozási korlátok érik el. |
1003005 | CustomExtensionTimedOut | Az egyéni bővítmény nem válaszolt az engedélyezett időtúllépésen belül. Ellenőrizze, hogy az API az egyéni bővítmény konfigurált időtúllépésén belül válaszol-e. Azt is jelezheti, hogy a hozzáférési jogkivonat érvénytelen. Kövesse a lépéseket a REST API közvetlen meghívásához. |
1003006 | CustomExtensionInvalidResponseContentType | Az egyéni bővítmény választartalma nem "application/json". |
1003007 | CustomExtensionNullClaimsResponse | Az egyéni bővítmény API null jogcímcsomaggal válaszolt. |
1003008 | CustomExtensionInvalidResponseApiSchemaVersion | Az egyéni bővítmény API nem ugyanazzal az apiSchemaVersion-tal válaszolt, mint amelyet a rendszer kért. |
1003009 | CustomExtensionEmptyResponse | Az egyéni bővítmény API választörzse null értékű volt, amikor ez nem várt. |
1003010 | CustomExtensionInvalidNumberOfActions | Az egyéni bővítmény API-válasza eltérő számú műveletet tartalmazott, mint az adott egyéni bővítménytípushoz támogatott műveletek. |
1003011 | CustomExtensionNotFound | Az eseményfigyelőhöz társított egyéni bővítmény nem található. |
1003012 | CustomExtensionInvalidActionType | Az egyéni bővítmény érvénytelen művelettípust adott vissza az adott egyéni bővítménytípushoz. |
1003014 | CustomExtensionIncorrectResourceIdFormat | Az egyéni bővítmény alkalmazásregisztrációjának jegyzékében szereplő identifierUris tulajdonságnak "api://{teljes tartománynév}/{appid} formátumban kell lennie. |
1003015 | CustomExtensionDomainNameDoesNotMatch | Az egyéni bővítmény targetUrl-jének és resourceId-jének ugyanazzal a teljes tartománynévvel kell rendelkeznie. |
1003016 | CustomExtensionResourceServicePrincipalNotFound | Az egyéni bővítmény resourceId-azonosítójának egy valós szolgáltatásnévnek kell lennie a bérlőben. |
1003017 | CustomExtensionClientServicePrincipalNotFound | Az egyéni bővítmény erőforrás-szolgáltatásnév nem található a bérlőben. |
1003018 | CustomExtensionClientServiceDisabled | Az egyéni bővítmény erőforrás-szolgáltatásnév le van tiltva ebben a bérlőben. |
1003019 | CustomExtensionResourceServicePrincipalDisabled | Az egyéni bővítmény erőforrás-szolgáltatásnév le van tiltva ebben a bérlőben. |
1003020 | CustomExtensionIncorrectTargetUrlFormat | A cél URL-címe nem megfelelő formátumú. Érvényes URL-címnek kell lennie, amely https-vel kezdődik. |
1003021 | CustomExtensionPermissionNotGrantedToServicePrincipal | A szolgáltatásnév nem rendelkezik rendszergazdai hozzájárulással a Microsoft Graph CustomAuthenticationExtensions.Receive.Payload alkalmazásszerepkörhöz (más néven alkalmazásengedélyhez), amely ahhoz szükséges, hogy az alkalmazás megkapja az egyéni hitelesítési bővítmény HTTP-kéréseit. |
1003022 | CustomExtensionMsGraphServicePrincipalDisabledOrNotFound | Az MS Graph szolgáltatásnév le van tiltva, vagy nem található ebben a bérlőben. |
1003023 | CustomExtensionBlocked | Az egyéni bővítményhez használt végpontot a szolgáltatás letiltja. |
1003024 | CustomExtensionResponseSizeExceeded | Az egyéni bővítmény válaszmérete túllépte a maximális korlátot. |
1003025 | CustomExtensionResponseClaimsSizeExceeded | Az egyéni bővítmény válaszában szereplő jogcímek teljes mérete túllépte a maximális korlátot. |
1003026 | CustomExtensionNullOrEmptyClaimKeyNotSupported | Az egyéni bővítmény API null vagy üres kulcsot tartalmazó jogcímekkel válaszolt. |
1003027 | CustomExtension Csatlakozás ionError | Hiba történt az egyéni bővítmény API-hoz való csatlakozáskor. |
A REST API meghívása közvetlenül
A REST API-t egy Microsoft Entra hozzáférési jogkivonat védi. Az API-t tesztelheti;
- Hozzáférési jogkivonat beszerzése az egyéni hitelesítési bővítményekhez társított alkalmazásregisztrációval
- Tesztelje helyileg az API-t egy API-teszteszköz használatával.
Helyi fejlesztési és tesztelési célokra nyissa meg a local.settings.json , és cserélje le a kódot a következő JSON-ra:
{ "IsEncrypted": false, "Values": { "AzureWebJobsStorage": "", "AzureWebJobsSecretStorageType": "files", "FUNCTIONS_WORKER_RUNTIME": "dotnet", "AuthenticationEvents__BypassTokenValidation" : false } }
Feljegyzés
Ha a Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents NuGet csomagot használta, győződjön meg arról, hogy helyi tesztelési célokra van beállítva
"AuthenticationEvents__BypassTokenValidation" : true
.Az előnyben részesített API-teszteszköz használatával hozzon létre egy új HTTP-kérést, és állítsa a HTTP-metódust a következőre
POST
: .Használja az alábbi JSON-törzset, amely utánozza a Microsoft Entra ID által a REST API-nak küldött kérést.
{ "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.
Ha Microsoft Entra-azonosítóból beszerzett hozzáférési jogkivonatot használ, válassza az Engedélyezés lehetőséget, majd válassza a Tulajdonos jogkivonatot, majd illessze be a Microsoft Entra-azonosítótól kapott hozzáférési jogkivonatot.
Válassza a Küldés lehetőséget, és a következőhöz hasonló JSON-választ kell kapnia:
{ "data": { "@odata.type": "microsoft.graph.onTokenIssuanceStartResponseData", "actions": [ { "@odata.type": "microsoft.graph.tokenIssuanceStart.provideClaimsForToken", "claims": { "customClaim1": "customClaimValue1", "customClaim2": [ "customClaimString1", "customClaimString2" ] } } ] } }
Gyakori teljesítménybeli fejlesztések
Az egyik leggyakoribb probléma az, hogy az egyéni jogcímszolgáltató API nem válaszol a két másodperces időtúllépésen belül. Ha a REST API nem válaszol a későbbi újrapróbálkozások során, a hitelesítés sikertelen lesz. A REST API teljesítményének javításához kövesse az alábbi javaslatokat:
- Ha az API bármilyen alárendelt API-hoz hozzáfér, gyorsítótárazza az API-k meghívásához használt hozzáférési jogkivonatot, így nem kell minden végrehajtáskor új jogkivonatot beszerezni.
- A teljesítményproblémák gyakran az alárendelt szolgáltatásokhoz kapcsolódnak. Adja hozzá a naplózást, amely rögzíti az alsóbb rétegbeli szolgáltatásokhoz való hívás folyamatideje.
- Ha felhőszolgáltatót használ az API üzemeltetéséhez, használjon egy üzemeltetési tervet, amely mindig "melegen" tartja az API-t. Az Azure Functions esetében ez lehet a Prémium csomag vagy a Dedikált csomag.
- Automatizált integrációs teszteket futtathat a hitelesítésekhez. Az API-tesztelési eszközökkel is tesztelheti az API teljesítményét.