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:

1. Jelentkezzen be a Microsoft Entra felügyeleti központba legalább egy felhőalapú alkalmazásként Rendszergazda istratorként.

2. Keresse meg az Identity>Applications>Enterprise-alkalmazásokat.

3. Válassza ki a bejelentkezési naplókat, majd válassza ki a legújabb bejelentkezési naplót.

4. 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.

Hozzáférési jogkivonat beszerzése

A hozzáférési jogkivonat beszerzése után adja át a HTTP-fejlécet Authorization . Hozzáférési jogkivonat beszerzéséhez kövesse az alábbi lépéseket:

1. Jelentkezzen be a Microsoft Entra felügyeleti központba legalább egy felhőalapú alkalmazásként Rendszergazda istratorként.

2. Keresse meg az Identitásalkalmazások>>alkalmazásregisztrációit.

3. Válassza ki az Azure Functions hitelesítési események API-alkalmazásregisztrációját , amely korábban konfigurálva volt egy egyéni jogcímszolgáltató konfigurálásához egy jogkivonat-kiállítási eseményhez.

4. Másolja ki az alkalmazásazonosítót.

5. Ha még nem hozott létre alkalmazáskulcsot, kövesse az alábbi lépéseket:

   1. Válassza a Tanúsítványok > titkos>ügyfélkulcsok új ügyféltitkot>.
   2. Adja meg titkos ügyfélkódja leírását.
   3. Válasszon lejáratot a titkos kódhoz, vagy adjon meg egy egyéni élettartamot.
   4. Válassza a Hozzáadás lehetőséget.
   5. Jegyezze fel a titkos kód értékét az ügyfélalkalmazás kódjában való használatra. Ez a titkos érték soha többé nem jelenik meg a lap elhagyása után.

6. A menüben válassza az API-k felfedése lehetőséget, és másolja ki az alkalmazásazonosító URI értékét. Például: api://contoso.azurewebsites.net/00001111-aaaa-2222-bbbb-3333cccc4444.

7. Nyissa meg az előnyben részesített API-tesztelési eszközt, és hozzon létre egy új HTTP-lekérdezést.

8. Módosítsa a HTTP-metódust a következőre POST: .

9. Adja meg a következő URL-címet. Cserélje le a {tenantID} bérlőazonosítót.

   https://login.microsoftonline.com/{tenantID}/oauth2/v2.0/token
   

10. A Törzs területen válassza ki az űrlapadatokat, és adja hozzá a következő kulcsokat:

    Kulcs	Érték
    grant_type	client_credentials
    client_id	Az alkalmazás ügyfélazonosítója .
    client_secret	Az alkalmazás titkos ügyfélkódja .
    scope	Az alkalmazás alkalmazásazonosítójának URI-ja , majd adja hozzá .default. Például: api://contoso.azurewebsites.net/00001111-aaaa-2222-bbbb-3333cccc4444/.default

11. Futtassa a HTTP-lekérdezést, és másolja a access_tokenhttps://jwt.ms webalkalmazásba.

12. Hasonlítsa össze az iss API-ban konfigurált kiállító nevével.

13. Hasonlítsa össze az aud API-ban konfigurált ügyfélazonosítót.

API-tesztelési eszközök

Ha közvetlenül az előnyben részesített API-tesztelési eszközzel szeretné tesztelni az API-t, kövesse az alábbi lépéseket:

Feljegyzés

Ha a Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents NuGet csomagot használta, kapcsolja ki a tokenérvényesítést tesztelés céljából. Nyissa meg local.settings.json , és adja hozzá a következő paramétert

"AuthenticationEvents__BypassTokenValidation": true

A tesztelés befejezése után győződjön meg arról, hogy eltávolítja.

1. A REST API-ban tiltsa le a jogcím érvényesítésétappid.azp Tekintse meg, hogyan szerkesztheti a korábban létrehozott függvény API-t .

2. Hozzon létre új HTTP-kérést, és állítsa a HTTP-metódust a következőre POST: .

3. A Törzs területen válassza a Nyers, majd a JSON lehetőséget.

4. Illessze be a következő JSON-t, 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/<Your tenant GUID>/applications/<Your Test Application App Id>",
       "data": {
           "@odata.type": "microsoft.graph.onTokenIssuanceStartCalloutData",
           "tenantId": "<Your tenant GUID>",
           "authenticationEventListenerId": "<GUID>",
           "customAuthenticationExtensionId": "<Your custom authentication extension ID>",
           "authenticationContext": {
               "correlationId": "<Enter correlation ID here>",
               "client": {
                   "ip": "127.0.0.1",
                   "locale": "en-us",
                   "market": "en-us"
               },
               "protocol": "OAUTH2.0",
               "clientServicePrincipal": {
                   "id": "<Your Test Applications servicePrincipal objectId>",
                   "appId": "<Your Test Application App Id>",
                   "appDisplayName": "My Test application",
                   "displayName": "My Test application"
               },
               "resourceServicePrincipal": {
                   "id": "<Your Test Applications servicePrincipal objectId>",
                   "appId": "<Your Test Application App Id>",
                   "appDisplayName": "My Test application",
                   "displayName": "My Test application"
               },
               "user": {
                   "companyName": "Casey Jensen",
                   "createdDateTime": "2023-08-16T00:00:00Z",
                   "displayName": "Casey Jensen",
                   "givenName": "Casey",
                   "id": "90847c2a-e29d-4d2f-9f54-c5b4d3f26471", // Client ID representing the Microsoft Entra authentication events service
                   "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.

5. 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:

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

Lásd még

• REST API létrehozása jogkivonat kiállításának kezdő eseményével
• SAML-alkalmazás konfigurálása külső tárolóból származó jogcímekkel rendelkező jogkivonatok fogadásához
• Egyéni jogcímszolgáltató referenciacikke .