Egyéni jogcímszolgáltatói referencia

Cikk
03/19/2024

Ebben a referenciacikkben megismerheti az egyéni jogcímszolgáltatói események REST API-sémáját és jogcímleképezési szabályzatstruktúráját.

Jogkivonat kiállításának kezdő eseménye

Az egyéni jogcímszolgáltatói jogkivonat kiállítási eseménye lehetővé teszi az alkalmazásjogkivonatok külső rendszerekből származó információval való bővítését vagy testreszabását. Ezek az információk nem tárolhatók a Microsoft Entra címtárban található felhasználói profil részeként.

Összetevők áttekintése

Ha egyéni bővítményt szeretne beállítani és integrálni az alkalmazással, több összetevőt kell csatlakoztatni. Az alábbi ábrán a konfigurációs pontok és az egyéni bővítmények implementálásához létrehozott kapcsolatok magas szintű nézete látható.

Nyilvánosan elérhető REST API-végpontnak kell lennie. Ebben a diagramban az Azure-függvényt ábrázolja. A REST API egyéni jogcímeket hoz létre és ad vissza az egyéni bővítménynek. Egy Microsoft Entra-alkalmazásregisztrációhoz van társítva.
Egyéni bővítményt kell konfigurálnia a Microsoft Entra ID-ban, amely úgy van konfigurálva, hogy csatlakozzon az API-hoz.
Olyan alkalmazásra van szüksége, amely megkapja a testre szabott jogkivonatokat. Például https://jwt.ms egy Microsoft-tulajdonú webalkalmazás, amely egy jogkivonat dekódolt tartalmát jeleníti meg.
Az alkalmazást, például az https://jwt.ms alkalmazást alkalmazásregisztrációval kell regisztrálni a Microsoft Entra-azonosítóba.
Létre kell hoznia egy társítás az alkalmazás és az egyéni bővítmény között.
Az Azure-függvényt opcionálisan egy hitelesítési szolgáltatóval is biztonságossá teheti, ebben a cikkben a Microsoft Entra-azonosítóját használjuk.

REST API

A REST API-végpont felelős az alsóbb rétegbeli szolgáltatásokkal való együttműködésért. Ilyenek például az adatbázisok, más REST API-k, LDAP-könyvtárak vagy bármely más olyan tárolók, amelyek tartalmazzák a jogkivonat konfigurációjához hozzáadni kívánt attribútumokat.

A REST API HTTP-választ ad vissza az attribútumokat tartalmazó Microsoft Entra-azonosítóra. A REST API által visszaadott attribútumok nem lesznek automatikusan hozzáadva egy jogkivonathoz. Ehelyett az alkalmazás jogcímleképezési szabályzatát konfigurálni kell ahhoz, hogy bármely attribútum szerepeljen a jogkivonatban. A Microsoft Entra ID-ban a jogcímleképezési szabályzat módosítja az adott alkalmazásokhoz kibocsátott jogkivonatokban kibocsátott jogcímeket.

REST API-séma

Ha saját REST API-t szeretne fejleszteni a jogkivonat kiállításának kezdő eseményéhez, használja a következő REST API-adatszerződést. A séma a kérés- és válaszkezelő tervezésére vonatkozó szerződést írja le.

A Microsoft Entra ID egyéni bővítménye HTTP-hívást indít a REST API-ba egy JSON hasznos adattal. A JSON hasznos adatai felhasználói profiladatokat, hitelesítési környezet attribútumokat és információkat tartalmaznak arról az alkalmazásról, amelybe a felhasználó be szeretne jelentkezni. Az id alábbi JSON értéke egy Microsoft-alkalmazás, amely a Microsoft Entra hitelesítési események szolgáltatását jelöli. A JSON-attribútumok további logikát hajthatnak végre az API-ban. Az API-nak küldött kérés formátuma a következő:

POST https://your-api.com/endpoint

{
    "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 extension ID>",
        "authenticationContext": {
            "correlationId": "<GUID>",
            "client": {
                "ip": "30.51.176.110",
                "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": "2016-03-01T15:23:40Z",
                "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": "caseyjensen",
                "onPremisesSecurityIdentifier": "<Enter Security Identifier>",
                "onPremisesUserPrincipalName": "Casey Jensen",
                "preferredLanguage": "en-us",
                "surname": "Jensen",
                "userPrincipalName": "casey@contoso.com",
                "userType": "Member"
            }
        }
    }
}

Az Azure által várt REST API válaszformátum a következő formátumban van, ahol a jogcímek DateOfBirth visszakerülnek CustomRoles az Azure-ba:

{
    "data": {
        "@odata.type": "microsoft.graph.onTokenIssuanceStartResponseData",
        "actions": [
            {
                "@odata.type": "microsoft.graph.tokenIssuanceStart.provideClaimsForToken",
                "claims": {
                    "DateOfBirth": "01/01/2000",
                    "CustomRoles": [
                        "Writer",
                        "Editor"
                    ]
                }
            }
        ]
    }
}

Amikor egy Fabrikam-szervezet B2B-felhasználója hitelesíti a Contoso szervezetét, a REST API-nak küldött hasznos adatok a következő formátumban vannak user :

"user": {
    "companyName": "Fabrikam",
    "createdDateTime": "2022-07-15T00:00:00Z",
    "displayName": "John Wright",
    "id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    "mail": "johnwright@fabrikam.com",
    "preferredDataLocation": "EUR",
    "userPrincipalName": "johnwright_fabrikam.com#EXT#@contoso.onmicrosoft.com",
    "userType": "Guest"
}

Támogatott adattípusok

Az alábbi táblázat az egyéni jogcímszolgáltatók által a jogkivonat kiállításának kezdő eseményéhez támogatott adattípusokat mutatja be:

Adattípus	Támogatott
Sztring	Igaz
Sztringtömb	Igaz
Logikai	Hamis
JSON	Hamis

Jogcímleképezési szabályzat

A Microsoft Entra ID-ban a jogcímleképezési szabályzat módosítja az adott alkalmazásokhoz kibocsátott jogkivonatokban kibocsátott jogcímeket. Ez magában foglalja az egyéni jogcímszolgáltatótól származó jogcímeket, és kibocsátja őket a jogkivonatba.

{
    "ClaimsMappingPolicy": {
        "Version": 1,
        "IncludeBasicClaimSet": "true",
        "ClaimsSchema": [{
            "Source": "CustomClaimsProvider",
            "ID": "dateOfBirth",
            "JwtClaimType": "birthdate"
        },
        {
            "Source": "CustomClaimsProvider",
            "ID": "customRoles",
            "JwtClaimType": "my_roles"
        },
        {
            "Source": "CustomClaimsProvider",
            "ID": "correlationId",
            "JwtClaimType": "correlation_Id"
        },
        {
            "Source": "CustomClaimsProvider",
            "ID": "apiVersion",
            "JwtClaimType": "apiVersion"
        },
        {
            "Value": "tokenaug_V2",
            "JwtClaimType": "policy_version"
        }]
    }
}

Az ClaimsSchema elem a következő attribútumokkal leképezendő jogcímek listáját tartalmazza:

A forrás az attribútum forrását, a CustomClaimsProvider. Vegye figyelembe, hogy az utolsó elem tesztelési célokra rögzített értéket tartalmaz a szabályzat verziójával. Így az source attribútum ki van hagyva.
Az azonosító a létrehozott Azure-függvényből visszaadott jogcímek neve.

Fontos

Az azonosító attribútum értéke megkülönbözteti a kis- és nagybetűk értékét. Ügyeljen arra, hogy a jogcím nevét pontosan az Azure-függvény által visszaadott módon írja be.
A JwtClaimType a jogcím opcionális neve az OpenID Csatlakozás alkalmazás kibocsátott jogkivonatában. Lehetővé teszi egy másik név megadását, amely a JWT-jogkivonatban tér vissza. Ha például az API-válasz ID értéke dateOfBirtha jogkivonatban található, akkor az kibocsátható birthdate .

Miután létrehozta a jogcímleképezési szabályzatot, a következő lépés az, hogy feltölti azt a Microsoft Entra-bérlőbe. Használja a következő claimsMappingPolicy Graph API-t a bérlőjében.

Fontos

A definícióelemnek egy egyetlen sztringértékkel rendelkező tömbnek kell lennie. A sztringnek a jogcímleképezési szabályzat sztringezett és szöktetett verziójának kell lennie. Használhat olyan eszközöket, mint https://jsontostring.com/ a jogcímleképezési szabályzat sztringezése.

Share via