Referenční informace k vlastnímu poskytovateli deklarací identity

Článek
07/27/2024

V tomto referenčním článku se dozvíte o struktuře zásad mapování deklarací identity pro vlastní události zprostředkovatele deklarací identity.

Počáteční událost vystavení tokenu

Událost vystavení tokenu vlastního zprostředkovatele deklarací identity umožňuje rozšířit nebo přizpůsobit tokeny aplikace informacemi z externích systémů. Tyto informace, které nelze uložit jako součást profilu uživatele v adresáři Microsoft Entra.

Přehled komponent

Pokud chcete nastavit a integrovat vlastní rozšíření s vaší aplikací, vyžaduje připojení více komponent. Následující diagram znázorňuje základní zobrazení bodů konfigurace a relací vytvořených pro implementaci vlastního rozšíření.

Měli byste mít veřejně dostupný koncový bod rozhraní REST API. V tomto diagramu je reprezentovaná funkcí Azure Functions. Rozhraní REST API vygeneruje a vrací vlastní deklarace identity do vlastního rozšíření. Je přidružená k registraci aplikace Microsoft Entra.
Musíte nakonfigurovat vlastní rozšíření v Microsoft Entra ID, které je nakonfigurované pro připojení k vašemu rozhraní API.
Vyžadujete aplikaci, která přijímá přizpůsobené tokeny. Například https://jwt.ms webová aplikace vlastněná Microsoftem, která zobrazuje dekódovaný obsah tokenu.
Aplikace, například https://jwt.ms musí být zaregistrovaná v Microsoft Entra ID pomocí registrace aplikace.
Musíte vytvořit přidružení mezi aplikací a vlastním rozšířením.
Volitelně můžete funkci Azure Functions zabezpečit pomocí zprostředkovatele ověřování. V tomto článku používáme vaše ID Microsoft Entra.

REST API

Koncový bod rozhraní REST API zodpovídá za propojení s podřízenými službami. Například databáze, jiná rozhraní REST API, adresáře LDAP nebo jiná úložiště obsahující atributy, které chcete přidat do konfigurace tokenu.

Rozhraní REST API vrátí odpověď HTTP na ID Microsoft Entra obsahující atributy. Atributy, které vrací vaše rozhraní REST API, se do tokenu nepřidávají automaticky. Místo toho musí být zásady mapování deklarací identity aplikace nakonfigurované pro všechny atributy, které se mají zahrnout do tokenu. V Microsoft Entra ID zásady mapování deklarací upraví deklarace identity generované v tokenech vydaných pro konkrétní aplikace.

Schéma rozhraní REST API

K vývoji vlastního rozhraní REST API pro počáteční událost vystavení tokenu použijte následující kontrakt dat rozhraní REST API. Schéma popisuje kontrakt pro návrh obslužné rutiny požadavku a odpovědi.

Vaše vlastní rozšíření v Microsoft Entra ID provede volání HTTP do rozhraní REST API s datovou částí JSON. Datová část JSON obsahuje data profilu uživatele, atributy kontextu ověřování a informace o aplikaci, kterou chce uživatel přihlásit. id Hodnota v následujícím formátu JSON je aplikace Microsoftu, která představuje službu událostí ověřování Microsoft Entra. Atributy JSON je možné použít k provedení další logiky rozhraní API. Požadavek na vaše rozhraní API je v následujícím formátu:

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"
            }
        }
    }
}

Formát odpovědi rozhraní REST API, který Azure očekává, je v následujícím formátu, ve kterém se deklarace identity DateOfBirth vrací do CustomRoles Azure:

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

Když se uživatel B2B z organizace Fabrikam ověří v organizaci Společnosti Contoso, datová část požadavku odeslaná do rozhraní REST API má user prvek v následujícím formátu:

"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"
}

Podporované datové typy

Následující tabulka uvádí datové typy podporované vlastními zprostředkovateli deklarací identity pro počáteční událost vystavení tokenu:

Datový typ	Podporováno
String	True
Pole řetězců	True
Logický	False
JSON	False

Omezení velikosti deklarací identity

Maximální velikost deklarace identity, kterou může poskytovatel deklarací vrátit, je omezená na 3 kB. Toto je součet všech párů klíč a hodnota vrácených rozhraním REST API.

Zásady mapování deklarací identity

V Microsoft Entra ID zásady mapování deklarací upraví deklarace identity generované v tokenech vydaných pro konkrétní aplikace. Zahrnuje deklarace identity od vašeho vlastního zprostředkovatele deklarací identity a jejich vystavení do tokenu.

{
    "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"
        }]
    }
}

Element ClaimsSchema obsahuje seznam deklarací identity, které se mají mapovat s následujícími atributy:

Zdroj popisuje zdroj atributu , .CustomClaimsProvider Všimněte si, že poslední prvek obsahuje pevnou hodnotu s verzí zásady pro účely testování. source Atribut je proto vynechán.
ID je název deklarací identity, které se vrátí z funkce Azure Functions, kterou jste vytvořili.

Důležité

V hodnotě atributu ID se rozlišují malá a velká písmena. Ujistěte se, že jste název deklarace identity zadali přesně tak, jak vrátila funkce Azure Functions.
JwtClaimType je volitelný název deklarace identity v generovaném tokenu pro aplikaci OpenID Connect. Umožňuje zadat jiný název, který se vrátí v tokenu JWT. Pokud má například odpověď ID rozhraní API hodnotu dateOfBirth, může se vygenerovat jako birthdate v tokenu.

Po vytvoření zásad mapování deklarací identity je dalším krokem jeho nahrání do tenanta Microsoft Entra. Ve svém tenantovi použijte následující rozhraní Graph API claimsMappingPolicy .

Důležité

Element definice by měl být pole s jednou řetězcovou hodnotou. Řetězec by měl být řetězcový a řídicí verze zásad mapování deklarací identity. Můžete použít nástroje, jako je https://jsontostring.com/ stringify zásad mapování deklarací identity.

Sdílet prostřednictvím