Dokumentacja dostawcy oświadczeń niestandardowych

Artykuł
07/27/2024

W tym artykule referencyjnym przedstawiono schemat interfejsu API REST i strukturę zasad mapowania oświadczeń dla niestandardowych zdarzeń dostawcy oświadczeń.

Zdarzenie rozpoczęcia wystawiania tokenu

Zdarzenie wystawiania tokenu dostawcy oświadczeń niestandardowych umożliwia wzbogacanie lub dostosowywanie tokenów aplikacji za pomocą informacji z systemów zewnętrznych. Te informacje, które 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.

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 oświadczenia do rozszerzenia niestandardowego. 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.

Schemat 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. Żądanie do interfejsu API ma następujący format:

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

Format odpowiedzi interfejsu API REST, którego oczekuje platforma Azure, ma następujący format, w którym oświadczenia DateOfBirth i CustomRoles są zwracane na platformę Azure:

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

Gdy użytkownik B2B z organizacji firmy Fabrikam uwierzytelnia się w organizacji firmy Contoso, ładunek żądania wysłany do interfejsu API REST ma user element 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"
}

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	Obsługiwane
String	Prawda
Tablica ciągów	Prawda
Wartość logiczna	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.

Zasady 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.
Identyfikator to nazwa oświadczeń zwracanych z utworzonej funkcji platformy Azure.

Ważne

W wartości atrybutu identyfikatora jest uwzględniana wielkość liter. Upewnij się, że wpisz nazwę oświadczenia dokładnie tak, jak została zwrócona przez funkcję platformy Azure.
JwtClaimType to opcjonalna nazwa oświadczenia w emitowanego tokenie dla aplikacji OpenID Connect. Umożliwia podanie innej nazwy zwracanej w tokenie JWT. Jeśli na przykład odpowiedź interfejsu API ma ID wartość dateOfBirth, może być emitowana jako birthdate 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/ ciągowanie zasad mapowania oświadczeń.

Udostępnij za pośrednictwem