Udostępnij za pośrednictwem

Dostosowywanie oświadczeń przy użyciu niestandardowych zasad oświadczeń programu Microsoft Graph (wersja zapoznawcza)

  • Artykuł

Oświadczenie to informacje, które dostawca tożsamości stwierdza o użytkowniku wewnątrz tokenu, który wystawia dla tego użytkownika. Dostosowywanie oświadczeń jest używane przez administratorów dzierżawy do dostosowywania oświadczeń emitowanych w tokenach dla określonej aplikacji w dzierżawie. Dostosowywanie oświadczeń obsługuje konfigurowanie oświadczeń dla aplikacji przy użyciu protokołów SAML, OAuth i OpenID Connect. Dostosowania oświadczeń można użyć do:

  • Wybierz oświadczenia uwzględnione w tokenach.
  • Utwórz typy oświadczeń, które jeszcze nie istnieją.
  • Wybierz lub zmień źródło danych emitowanych w określonych oświadczeniach.

W tym przewodniku z instrukcjami omówimy kilka typowych scenariuszy, które mogą ułatwić zrozumienie sposobu korzystania z zasad oświadczeń niestandardowych.

Wymagania wstępne

  • Dzierżawa firmy Microsoft Entra.
  • Aplikacja dla przedsiębiorstw skonfigurowana w centrum administracyjnym firmy Microsoft Entra.
  • W przypadku użytkowników programu PowerShell pobierz najnowszy zestaw Microsoft Graph PowerShell SDK. To krok jest opcjonalny.

Dostosowywanie oświadczeń w identyfikatorze Entra firmy Microsoft

Identyfikator Entra firmy Microsoft obsługuje dwa sposoby dostosowywania oświadczeń przy użyciu programu Microsoft Graph/programu PowerShell dla aplikacji:

W poniższych przykładach utworzysz, zaktualizujesz i zastąpisz zasady dla jednostek usługi. Niestandardowe zasady oświadczeń są zawsze połączone z obiektami jednostki usługi. Przed utworzeniem niestandardowych zasad oświadczeń dla aplikacji/jednostki usługi upewnij się, że aplikacja dla przedsiębiorstw została skonfigurowana jako część wymagań wstępnych.

Otwórz Eksploratora programu Microsoft Graph w przeglądarce zaloguj się do Eksploratora programu Microsoft Graph jako co najmniej administrator aplikacji, wybierz jeden z następujących scenariuszy.

Po utworzeniu zasad oświadczeń niestandardowych należy skonfigurować aplikację, aby potwierdzić, że tokeny zawierają dostosowane oświadczenia. Aby uzyskać więcej informacji, zapoznaj się z zagadnieniami dotyczącymi zabezpieczeń.

Pomijanie podstawowych oświadczeń z tokenów

W tym przykładzie utworzysz niestandardowe zasady oświadczeń, które usuwają podstawowy zestaw oświadczeń z tokenów wystawionych dla połączonej jednostki usługi.

  1. W Eksploratorze programu Microsoft Graph zidentyfikuj aplikację, dla której chcesz skonfigurować niestandardowe zasady oświadczeń na potrzeby korzystania z interfejsu API jednostki usługi.

  2. Utwórz zasady oświadczeń niestandardowych, uruchamiając następujący interfejs API. Ta zasada, połączona z jednostką usługi, pomija podstawowe oświadczenia z tokenów.

    PUT https://graph.microsoft.com/beta/servicePrincipals/<servicePrincipal-id>/claimsPolicy

    Treść żądania:

    {
    "includeBasicClaimSet": false
}

  3. Aby wyświetlić nowe zasady, uruchom następujące polecenie

    GET https://graph.microsoft.com/beta/servicePrincipals/<servicePrincipal-id>/claimsPolicy

    Reakcja:

    HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "…",
    "id": "aaaaaaaa-bbbb-cccc-1111-222222222222.",
    "includeBasicClaimSet": false,
    "includeApplicationIdInIssuer": false,
    "audienceOverride": null,
    "groupFilter": null,
    "claims": []
}

Uwzględnij EmployeeID elementy i TenantCountry jako oświadczenia w tokenach

W tym przykładzie utworzysz dostosowanie do oświadczeń, które dodaje EmployeeID element i TenantCountry do tokenów. W tym przykładzie uwzględniamy również podstawowe oświadczenia ustawione w tokenach.

  1. W Eksploratorze programu Microsoft Graph zidentyfikuj aplikację, dla której chcesz skonfigurować niestandardowe zasady oświadczeń na potrzeby korzystania z interfejsu API jednostki usługi.

  2. Utwórz zasady oświadczeń niestandardowych, uruchamiając następujący interfejs API. Te zasady połączone z jednostką usługi dodają oświadczenia EmployeeID i TenantCountry do tokenów.

    PUT https://graph.microsoft.com/beta/servicePrincipals/<servicePrincipal-id>/claimsPolicy

    Treść żądania:

    {
    "includeBasicClaimSet": true,
    "claims": [
        {
            "@odata.type": "#microsoft.graph.customClaim",
            "name": "employeeId",
            "namespace": null,
            "tokenFormat": [
                "jwt"
            ],
            "samlAttributeNameFormat": null,
            "configurations": [
                {
                    "condition": null,
                    "attribute": {
                        "@odata.type": "#microsoft.graph.sourcedAttribute",
                        "id": " employeeid",
                        "source": "user",
                        "isExtensionAttribute": false
                    },
                    "transformations": []
                }
            ]
        },
        {
            "@odata.type": "#microsoft.graph.customClaim",
            "name": "country",
            "namespace": null,
            "tokenFormat": [
                "jwt"
            ],
            "samlAttributeNameFormat": null,
            "configurations": [
                {
                    "condition": null,
                    "attribute": {
                        "@odata.type": "#microsoft.graph.sourcedAttribute",
                        "id": " tenantcountry",
                        "source": "user",
                        "isExtensionAttribute": false
                    },
                    "transformations": []
                }
            ]
        }
    ]
}

  3. Aby wyświetlić nowe zasady, uruchom następujące polecenie:

    GET https://graph.microsoft.com/beta/servicePrincipals/<servicePrincipal-id>/claimsPolicy

    Reakcja:

    {
    "@odata.context": "…",
    "id": "aaaaaaaa-bbbb-cccc-1111-222222222222",
    "includeBasicClaimSet": true,
    "includeApplicationIdInIssuer": false,
    "audienceOverride": null,
    "groupFilter": null,
    "claims": [...]
}

Używanie przekształcenia oświadczeń w tokenach

W tym przykładzie zaktualizujesz zasady w celu emitowania niestandardowego oświadczenia "JoinedData" do zestawów JWTs wystawionych dla połączonych jednostek usługi. To oświadczenie zawiera wartość utworzoną przez dołączenie danych przechowywanych w atrybucie extensionattribute1 w obiekcie użytkownika z parametrem "-ext". W tym przykładzie wykluczamy podstawowe oświadczenia ustawione w tokenach.

  1. W Eksploratorze programu Microsoft Graph zidentyfikuj aplikację, dla której chcesz skonfigurować niestandardowe zasady oświadczeń na potrzeby korzystania z interfejsu API jednostki usługi.

  2. Utwórz zasady oświadczeń niestandardowych, uruchamiając następujący interfejs API. Te zasady emitują niestandardowe oświadczenie JoinedData do tokenów.

    PATCH https://graph.microsoft.com/beta/servicePrincipals/<servicePrincipal-id>/claimsPolicy

    Treść żądania:

    {
    "includeBasicClaimSet": true,
    "claims": 
    [
        {
            "@odata.type": "#microsoft.graph.customClaim",
            "name": "JoinedData",
            "namespace": null,
            "tokenFormat": [
                "jwt"
            ],
            "samlAttributeNameFormat": null,
            "configurations": 
            [
                {
                    "condition": null,
                    "attribute": null,
                    "transformations": 
                    [
                        {
                            "@odata.type": "#microsoft.graph.joinTransformation",
                            "separator": "-",
                            "input": 
                            {
                                "treatAsMultiValue": false,
                                "attribute": 
                                {
                                    "@odata.type": "#microsoft.graph.sourcedAttribute",
                                    "id": "extensionattribute1",
                                    "source": "user",
                                    "isExtensionAttribute": false
                                }
                            },
                            "input2": 
                            {
                                "treatAsMultiValue": false,
                                "attribute": 
                                {
                                    "@odata.type":"#microsoft.graph.valueBasedAttribute",
                                    "value": "ext"
                                 }
                            }
                        }
                    ]
                }
            ]
        }
    ]
}

    Uwaga

    Zasady oświadczeń niestandardowych to silnie typizowane zasady, a każda transformacja używa innej @odata.type wartości.

  3. Aby wyświetlić nowe zasady i pobrać zasady ObjectId, uruchom następujące polecenie:

    GET https://graph.microsoft.com/beta/servicePrincipals/<servicePrincipal-id>/claimsPolicy

    Reakcja:

    {
    "@odata.context": "…",
    "id": "aaaaaaaa-bbbb-cccc-1111-222222222222",
    "includeBasicClaimSet": true,
    "includeApplicationIdInIssuer": false,
    "audienceOverride": null,
    "groupFilter": null,
    "claims": [...]
}

Powiązana zawartość