Dokumentacja dostawcy oświadczeń niestandardowych

W tym przewodniku można dowiedzieć się o schemacie interfejsu API REST i strukturze zasad mapowania roszczeń dla niestandardowych zdarzeń dostawcy roszczeń.

Zdarzenie rozpoczęcia wystawiania tokenu

Zdarzenie wystawiania tokenu niestandardowego dostawcy oświadczeń umożliwia wzbogacanie lub dostosowywanie tokenów aplikacji za pomocą informacji z systemów zewnętrznych. Te informacje nie mogą być przechowywane jako część profilu użytkownika w katalogu Microsoft Entra.

Omówienie składnika

Aby skonfigurować i zintegrować rozszerzenie niestandardowe z aplikacją, wymaga połączenia wielu składników. Na poniższym diagramie przedstawiono ogólny widok punktów konfiguracji oraz relacje tworzone w celu zaimplementowania rozszerzenia niestandardowego.

Zrzut ekranu przedstawiający składniki do skonfigurowania w usłudze Microsoft Entra ID w celu skonfigurowania i zintegrowania niestandardowego dostawcy oświadczeń.

  • Punkt końcowy interfejsu API REST powinien być publicznie dostępny. Na tym diagramie jest reprezentowana przez funkcję platformy Azure. Interfejs API REST generuje i zwraca niestandardowe żądania do własnego rozszerzenia. Jest ona skojarzona z rejestracją aplikacji Firmy Microsoft Entra.
  • Musisz skonfigurować rozszerzenie niestandardowe w usłudze Microsoft Entra ID, które jest skonfigurowane do nawiązywania połączenia z interfejsem API.
  • Wymagana jest aplikacja , która odbiera dostosowane tokeny. Na przykład https://jwt.ms aplikacja internetowa firmy Microsoft, która wyświetla zdekodowana zawartość tokenu.
  • Aplikacja, taka jak https://jwt.ms , musi być zarejestrowana w identyfikatorze Entra firmy Microsoft przy użyciu rejestracji aplikacji.
  • Należy utworzyć skojarzenie między aplikacją a rozszerzeniem niestandardowym.
  • Opcjonalnie możesz zabezpieczyć funkcję platformy Azure za pomocą dostawcy uwierzytelniania, w tym artykule użyjemy Twojego identyfikatora Entra firmy Microsoft.

interfejs API REST

Punkt końcowy interfejsu API REST jest odpowiedzialny za współdziałanie z usługami podrzędnymi. Na przykład bazy danych, inne interfejsy API REST, katalogi LDAP lub inne magazyny zawierające atrybuty, które chcesz dodać do konfiguracji tokenu.

Interfejs API REST zwraca odpowiedź HTTP na identyfikator Entra firmy Microsoft zawierający atrybuty. Atrybuty zwracane przez interfejs API REST nie są automatycznie dodawane do tokenu. Zamiast tego zasady mapowania oświadczeń aplikacji muszą być skonfigurowane pod kątem dowolnego atrybutu, który ma zostać uwzględniony w tokenie. W usłudze Microsoft Entra ID zasady mapowania oświadczeń modyfikują oświadczenia emitowane w tokenach wystawionych dla określonych aplikacji.

Żądanie do interfejsu API REST

Aby opracować własny interfejs API REST dla zdarzenia rozpoczęcia wystawiania tokenu, użyj następującego kontraktu danych interfejsu API REST. Schemat opisuje kontrakt do projektowania procedury obsługi żądań i odpowiedzi.

Rozszerzenie niestandardowe w usłudze Microsoft Entra ID wykonuje wywołanie HTTP do interfejsu API REST za pomocą ładunku JSON. Ładunek JSON zawiera dane profilu użytkownika, atrybuty kontekstu uwierzytelniania i informacje o aplikacji, którą użytkownik chce zalogować. Wartość id w poniższym formacie JSON to aplikacja firmy Microsoft reprezentująca usługę zdarzeń uwierzytelniania Entra firmy Microsoft. Atrybuty JSON mogą służyć do wykonywania dodatkowej logiki przez interfejs API.

Następujące żądanie HTTP pokazuje, jak Microsoft Entra wywołuje Twój interfejs API REST. To żądanie HTTP może służyć do debugowania interfejsu API REST, symulując żądanie od firmy Microsoft Entra.

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

Content-Type: application/json

[Request payload]

Poniższy dokument JSON zawiera przykład ładunku żądania:

{
    "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", 
                "mail": "casey@contoso.com",
                "onPremisesSamAccountName": "caseyjensen",
                "onPremisesSecurityIdentifier": "<Enter Security Identifier>",
                "onPremisesUserPrincipalName": "Casey Jensen",
                "preferredLanguage": "en-us",
                "surname": "Jensen",
                "userPrincipalName": "casey@contoso.com",
                "userType": "Member"
            }
        }
    }
}

Gdy użytkownik B2B z organizacji Fabrikam uwierzytelnia się w organizacji firmy Contoso, ładunek żądania wysłany do interfejsu API REST ma element user w następującym formacie:

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

Odpowiedź z interfejsu API REST

Identyfikator Entra firmy Microsoft oczekuje odpowiedzi interfejsu API REST w następującym protokole HTTP.

HTTP/1.1 200 OK

Content-Type: application/json

[JSON document]

W odpowiedzi HTTP podaj następujący dokument JSON, w którym oświadczenia DateOfBirth i CustomRoles są zwracane do firmy Microsoft Entra:

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

Jeśli nie trzeba zwracać żadnego dodatkowego oświadczenia, podaj pusty claims obiekt:

{
    "data": {
        "@odata.type": "microsoft.graph.onTokenIssuanceStartResponseData",
        "actions": [
            {
                "@odata.type": "microsoft.graph.tokenIssuanceStart.provideClaimsForToken",
                "claims": {
                }
            }
        ]
    }
}

Obsługiwane typy danych:

W poniższej tabeli przedstawiono typy danych obsługiwane przez dostawców oświadczeń niestandardowych dla zdarzenia rozpoczęcia wystawiania tokenu:

Typ danych Wspierane
Sznurek Prawda
Tablica ciągów Prawda
logiczny Fałsz
JSON Fałsz

Ograniczenia rozmiaru oświadczeń

Maksymalny rozmiar oświadczenia, który dostawca oświadczeń może zwrócić, jest ograniczony do 3 KB. Jest to suma wszystkich par klucz i wartość zwracanych przez interfejs API REST.

Polityka mapowania oświadczeń

W usłudze Microsoft Entra ID zasady mapowania oświadczeń modyfikują oświadczenia emitowane w tokenach wystawionych dla określonych aplikacji. Obejmuje ona oświadczenia od dostawcy oświadczeń niestandardowych i wystawia je 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 zawiera listę oświadczeń, które mają być mapowane z następującymi atrybutami:

  • Źródło opisuje źródło atrybutu , CustomClaimsProvider. Należy pamiętać, że ostatni element zawiera stałą wartość z wersją zasad na potrzeby testowania. W związku z tym source atrybut zostanie pominięty.

  • ID jest nazwą roszczeń zwracanych przez utworzoną funkcję Azure.

    Ważne

    W wartości atrybutu identyfikatora jest uwzględniana wielkość liter. Upewnij się, że wpisujesz nazwę oświadczenia dokładnie tak, jak zwróciła ją funkcja Azure.

  • JwtClaimType to opcjonalna nazwa roszczenia w emitowanym tokenie dla aplikacji OpenID Connect. Umożliwia podanie innej nazwy zwracanej w tokenie JWT. Na przykład, jeśli odpowiedź interfejsu API ma wartość ID, można ją wyemitować jako dateOfBirth w tokenie.

Po utworzeniu zasad mapowania oświadczeń następnym krokiem jest przekazanie ich do dzierżawy usługi Microsoft Entra. Użyj następujących oświadczeńMappingPolicy Graph API w dzierżawie.

Ważne

Element definicji powinien być tablicą z pojedynczą wartością ciągu. Ciąg powinien być ciągiem ciągowanym i unikniętą wersją zasad mapowania oświadczeń. Możesz użyć narzędzi, takich jak https://jsontostring.com/, aby zmienić na ciąg znaków swoją politykę mapowania oświadczeń.

Zobacz też