Udostępnij za pośrednictwem

Konfigurowanie opcjonalnych oświadczeń

  • Artykuł

Tokeny zwracane przez firmę Microsoft Entra są przechowywane mniejsze, aby zapewnić optymalną wydajność przez klientów, którzy ich żądają. W związku z tym kilka oświadczeń nie jest już obecnych w tokenie domyślnie i musi zostać poproszonych o podanie w szczególności dla poszczególnych aplikacji.

Opcjonalne oświadczenia dla aplikacji można skonfigurować za pomocą interfejsu użytkownika lub manifestu aplikacji centrum administracyjnego firmy Microsoft Entra.

Wymagania wstępne

Konfigurowanie opcjonalnych oświadczeń w aplikacji

  1. Zaloguj się do centrum administracyjnego firmy Microsoft Entra co najmniej jako administrator aplikacji w chmurze.
  2. Przejdź do aplikacji tożsamości>> Rejestracje aplikacji.
  3. Wybierz aplikację, dla której chcesz skonfigurować opcjonalne oświadczenia na podstawie scenariusza i żądanego wyniku.
  1. W obszarze Zarządzanie wybierz pozycję Konfiguracja tokenu.
  2. Wybierz Dodaj opcjonalne roszczenie.
  3. Wybierz typ tokenu, który chcesz skonfigurować, na przykład Access.
  4. Wybierz opcjonalne oświadczenia do dodania.
  5. Wybierz Dodaj.

Obiekt optionalClaims deklaruje opcjonalne oświadczenia żądane przez aplikację. Aplikacja może skonfigurować opcjonalne oświadczenia zwracane w tokenach identyfikatorów, tokenach dostępu i tokenach SAML 2. Aplikacja może skonfigurować inny zestaw opcjonalnych oświadczeń, które mają być zwracane w każdym typie tokenu.

Nazwisko Pisz Opis
idToken Kolekcja Opcjonalne oświadczenia zwrócone w tokenie identyfikatora JWT.
accessToken Kolekcja Opcjonalne oświadczenia zwrócone w tokenie dostępu JWT.
saml2Token Kolekcja Opcjonalne oświadczenia zwrócone w tokenie SAML.

Jeśli jest obsługiwane przez określone oświadczenie, możesz również zmodyfikować zachowanie opcjonalnego oświadczenia przy użyciu additionalProperties pola .

Nazwisko Pisz Opis
name Edm.String Nazwa opcjonalnego oświadczenia.
source Edm.String Źródło (obiekt katalogu) oświadczenia. Istnieją wstępnie zdefiniowane oświadczenia i oświadczenia zdefiniowane przez użytkownika z właściwości rozszerzenia. Jeśli wartość źródłowa ma wartość null, oświadczenie jest wstępnie zdefiniowanym opcjonalnym oświadczeniem. Jeśli wartość źródłowa jest użytkownikiem, wartość we właściwości name jest właściwością rozszerzenia z obiektu użytkownika.
essential Edm.Boolean Jeśli wartość ma wartość true, oświadczenie określone przez klienta jest konieczne, aby zapewnić bezproblemowe środowisko autoryzacji dla określonego zadania żądanego przez użytkownika końcowego. Wartość domyślna to false.
additionalProperties Kolekcja (Edm.String) Inne właściwości oświadczenia. Jeśli właściwość istnieje w tej kolekcji, modyfikuje zachowanie opcjonalnego oświadczenia określonego we właściwości name.

Konfigurowanie opcjonalnych oświadczeń rozszerzenia katalogu

Oprócz standardowego opcjonalnego zestawu oświadczeń można również skonfigurować tokeny w celu uwzględnienia rozszerzeń programu Microsoft Graph. Aby uzyskać więcej informacji, zobacz Dodawanie niestandardowych danych do zasobów przy użyciu rozszerzeń.

Ważne

Tokeny dostępu są zawsze generowane przy użyciu manifestu zasobu, a nie klienta. W żądaniu ...scope=https://graph.microsoft.com/user.read...zasób jest interfejsem API programu Microsoft Graph. Token dostępu jest tworzony przy użyciu manifestu interfejsu API programu Microsoft Graph, a nie manifestu klienta. Zmiana manifestu aplikacji nigdy nie powoduje, że tokeny interfejsu API programu Microsoft Graph wyglądają inaczej. Aby sprawdzić, czy accessToken zmiany zostały wprowadzone, zażądaj tokenu dla aplikacji, a nie innej aplikacji.

Opcjonalne oświadczenia obsługują atrybuty rozszerzenia i rozszerzenia katalogu. Ta funkcja jest przydatna do dołączania większej liczby informacji o użytkowniku, których aplikacja może używać. Na przykład inne identyfikatory lub ważne opcje konfiguracji ustawione przez użytkownika. Jeśli manifest aplikacji żąda rozszerzenia niestandardowego, a użytkownik MSA loguje się do aplikacji, te rozszerzenia nie są zwracane.

Formatowanie rozszerzenia katalogu

Podczas konfigurowania opcjonalnych oświadczeń rozszerzenia katalogu przy użyciu manifestu aplikacji użyj pełnej nazwy rozszerzenia (w formacie: extension_<appid>_<attributename>). Jest <appid> to stripped wersja identyfikatora appId (lub identyfikatora klienta) aplikacji żądającej oświadczenia.

W JWT te oświadczenia są emitowane w następującym formacie nazwy: extn.<attributename>. W tokenach SAML te oświadczenia są emitowane w następującym formacie identyfikatora URI: http://schemas.microsoft.com/identity/claims/extn.<attributename>

Konfigurowanie opcjonalnych oświadczeń grup

Napiwek

Kroki opisane w tym artykule mogą się nieznacznie różnić w zależności od portalu, od którego zaczynasz.

W tej sekcji opisano opcje konfiguracji w ramach opcjonalnych oświadczeń dotyczących zmiany atrybutów grupy używanych w oświadczeniach grupy z domyślnego identyfikatora obiektu grupy do atrybutów zsynchronizowanych z lokalnej usługi Active Directory systemu Windows. Opcjonalne oświadczenia dla aplikacji można skonfigurować za pomocą witryny Azure Portal lub manifestu aplikacji. Opcjonalne oświadczenia grupy są emitowane tylko w JWT dla podmiotów zabezpieczeń użytkowników. Jednostki usługi nie są uwzględniane w opcjonalnych oświadczeniach grupy emitowanych w zestawie JWT.

Ważne

Liczba grup emitowanych w tokenie jest ograniczona do 150 dla asercji SAML i do 200 dla JWT, uwzględniając grupy zagnieżdżone. Aby uzyskać więcej informacji na temat limitów grup i ważnych zastrzeżeń dotyczących oświadczeń grup z atrybutów lokalnych, zobacz Konfigurowanie oświadczeń grup dla aplikacji.

Wykonaj następujące kroki, aby skonfigurować opcjonalne oświadczenia grup w witrynie Azure Portal:

  1. Wybierz aplikację, dla której chcesz skonfigurować opcjonalne oświadczenia.
  2. W obszarze Zarządzanie wybierz pozycję Konfiguracja tokenu.
  3. Wybierz pozycję Dodaj oświadczenie grup.
  4. Wybierz typy grup, które mają być zwracane (grupy zabezpieczeń lub role katalogu, Wszystkie grupy i/lub grupy przypisane do aplikacji):
    • Opcja Grupy przypisane do aplikacji obejmuje tylko grupy przypisane do aplikacji. Opcja Grupy przypisane do aplikacji jest zalecana dla dużych organizacji ze względu na limit liczby grup w tokenie. Aby zmienić grupy przypisane do aplikacji, wybierz aplikację z listy Aplikacje dla przedsiębiorstw. Wybierz pozycję Użytkownicy i grupy , a następnie dodaj użytkownika/grupę. Wybierz grupy, które chcesz dodać do aplikacji z obszaru Użytkownicy i grupy.
    • Opcja Wszystkie grupy obejmuje pozycje SecurityGroup, DirectoryRole i DistributionList, ale nie grupy przypisane do aplikacji.
  5. Opcjonalnie: wybierz właściwości określonego typu tokenu, aby zmodyfikować wartość oświadczenia grup, aby zawierała atrybuty grupy lokalnej lub zmienić typ oświadczenia na rolę.
  6. Wybierz pozycję Zapisz.

Wykonaj następujące kroki, aby skonfigurować opcjonalne oświadczenia grup za pomocą manifestu aplikacji:

  1. Wybierz aplikację, dla której chcesz skonfigurować opcjonalne oświadczenia.

  2. W obszarze Zarządzanie wybierz pozycję Manifest.

  3. Dodaj następujący wpis przy użyciu edytora manifestu:

    Prawidłowe wartości to:

    • "Wszystkie" (ta opcja obejmuje pozycje SecurityGroup, DirectoryRole i DistributionList)
    • "SecurityGroup"
    • "DirectoryRole"
    • "ApplicationGroup" (ta opcja obejmuje tylko grupy przypisane do aplikacji)

    Na przykład:

    "groupMembershipClaims": "SecurityGroup"

    Domyślnie identyfikatory obiektów grupy są emitowane w wartości oświadczenia grupy. Aby zmodyfikować wartość oświadczenia tak, aby zawierała atrybuty grupy lokalnej lub zmienić typ oświadczenia na rolę, użyj optionalClaims konfiguracji w następujący sposób:

  4. Ustaw opcjonalne oświadczenia konfiguracji nazwy grupy.

    Jeśli chcesz, aby grupy w tokenie zawierały atrybuty grupy lokalnej w sekcji opcjonalnych oświadczeń, określ, do którego typu tokenu ma zostać zastosowane opcjonalne oświadczenie. Należy również określić nazwę żądanego oświadczenia opcjonalnego i wszelkie inne żądane właściwości.

    Można wymienić wiele typów tokenów:

    • idToken dla tokenu identyfikatora OIDC
    • accessToken dla tokenu dostępu OAuth
    • Saml2Token dla tokenów SAML.

    Typ Saml2Token dotyczy zarówno tokenów formatu SAML1.1, jak i SAML2.0.

    Dla każdego odpowiedniego typu tokenu zmodyfikuj oświadczenie grup, aby użyć optionalClaims sekcji w manifeście. Schemat optionalClaims jest następujący:

    {
    "name": "groups",
    "source": null,
    "essential": false,
    "additionalProperties": []
}
    Schemat opcjonalnych oświadczeń Wartość
    name Musi być groups
    source Nie używany. Pomiń lub określ wartość null.
    essential Nie używany. Pomiń lub określ wartość false.
    additionalProperties Lista innych właściwości. Prawidłowe opcje to sam_account_name, , netbios_domain_and_sam_account_namedns_domain_and_sam_account_nameemit_as_roles i .cloud_displayname

    Tylko jeden additionalProperties z sam_account_nameelementów dns_domain_and_sam_account_name, netbios_domain_and_sam_account_name jest wymagany. Jeśli istnieje więcej niż jeden, zostanie użyty pierwszy i inne zignorowane. Możesz również dodać cloud_displayname polecenie , aby emitować nazwę wyświetlaną grupy chmury. Ta opcja działa tylko wtedy, gdy groupMembershipClaims jest ustawiona wartość ApplicationGroup.

    Niektóre aplikacje wymagają informacji o grupie użytkownika w oświadczeniu roli. Aby zmienić typ oświadczenia z oświadczenia grupy na oświadczenie roli, dodaj emit_as_roles do additionalProperties. Wartości grupy są emitowane w oświadczeniu roli.

    Jeśli emit_as_roles jest używany, wszystkie role aplikacji skonfigurowane przez użytkownika (lub aplikację zasobów) nie są przypisane do oświadczenia roli.

W poniższych przykładach przedstawiono konfigurację manifestu dla oświadczeń grupy:

Emituj grupy jako nazwy grup w tokenach dostępu OAuth w dnsDomainName\sAMAccountName formacie.

"optionalClaims": {
    "accessToken": [
        {
            "name": "groups",
            "additionalProperties": [
                "dns_domain_and_sam_account_name"
            ]
        }
    ]
}

Emituj nazwy grup, które mają być zwracane w netbiosDomain\sAMAccountName formacie jako oświadczenia ról w tokenach SAML i OIDC ID.

"optionalClaims": {
    "saml2Token": [
        {
            "name": "groups",
            "additionalProperties": [
                "netbios_domain_and_sam_account_name",
                "emit_as_roles"
            ]
        }
    ],
    "idToken": [
        {
            "name": "groups",
            "additionalProperties": [
                "netbios_domain_and_sam_account_name",
                "emit_as_roles"
            ]
        }
    ]
}

Emituj nazwy grup w formacie sam_account_name dla lokalnych grup synchronizowanych i cloud_display nazw grup w chmurze w tokenach SAML i OIDC id dla grup przypisanych do aplikacji.

"groupMembershipClaims": "ApplicationGroup",
"optionalClaims": {
    "saml2Token": [
        {
            "name": "groups",
            "additionalProperties": [
                "sam_account_name",
                "cloud_displayname"
            ]
        }
    ],
    "idToken": [
        {
            "name": "groups",
            "additionalProperties": [
                "sam_account_name",
                "cloud_displayname"
            ]
        }
    ]
}

Przykład opcjonalnych oświadczeń

Istnieje wiele opcji aktualizowania właściwości konfiguracji tożsamości aplikacji w celu włączenia i skonfigurowania opcjonalnych oświadczeń:

  • Możesz użyć witryny Azure Portal
  • Możesz użyć manifestu.
  • Istnieje również możliwość zapisania aplikacji korzystającej z interfejsu API programu Microsoft Graph w celu zaktualizowania aplikacji. Typ OptionalClaims w przewodniku dokumentacji interfejsu API programu Microsoft Graph może pomóc w konfigurowaniu opcjonalnych oświadczeń.

W poniższym przykładzie witryna Azure Portal i manifest są używane do dodawania opcjonalnych oświadczeń do tokenów dostępu, identyfikatora i języka SAML przeznaczonych dla aplikacji. Różne opcjonalne oświadczenia są dodawane do każdego typu tokenu, który aplikacja może odbierać:

  • Tokeny identyfikatorów zawierają nazwę UPN dla użytkowników federacyjnych w pełnym formularzu (<upn>_<homedomain>#EXT#@<resourcedomain>).
  • Tokeny dostępu, które inni klienci żądają dla tej aplikacji, obejmują auth_time oświadczenie.
  • Tokeny SAML zawierają skypeId rozszerzenie schematu katalogu (w tym przykładzie identyfikator aplikacji dla tej aplikacji to ab603c56068041afb2f6832e2a17e237). Token SAML uwidacznia identyfikator Skype'a jako extension_ab603c56068041afb2f6832e2a17e237_skypeId.

Konfigurowanie oświadczeń w witrynie Azure Portal:

  1. Wybierz aplikację, dla której chcesz skonfigurować opcjonalne oświadczenia.
  2. W obszarze Zarządzanie wybierz pozycję Konfiguracja tokenu.
  3. Wybierz pozycję Dodaj opcjonalne oświadczenie, wybierz typ tokenu identyfikatora , wybierz pozycję upn z listy oświadczeń, a następnie wybierz pozycję Dodaj.
  4. Wybierz pozycję Dodaj opcjonalne oświadczenie, wybierz typ tokenu dostępu , wybierz pozycję auth_time z listy oświadczeń, a następnie wybierz pozycję Dodaj.
  5. Na ekranie przeglądu konfiguracji tokenu wybierz ikonę ołówka obok pozycji upn, wybierz przełącznik Uwierzytelniony zewnętrznie, a następnie wybierz pozycję Zapisz.
  6. Wybierz pozycję Dodaj opcjonalne oświadczenie, wybierz typ tokenu SAML , wybierz pozycję extn.skypeID z listy oświadczeń (dotyczy tylko wtedy, gdy utworzono obiekt użytkownika Microsoft Entra o nazwie skypeID ), a następnie wybierz pozycję Dodaj.

Skonfiguruj oświadczenia w manifeście:

  1. Wybierz aplikację, dla której chcesz skonfigurować opcjonalne oświadczenia.

  2. W obszarze Zarządzanie wybierz pozycję Manifest , aby otworzyć wbudowany edytor manifestu.

  3. Manifest można edytować bezpośrednio przy użyciu tego edytora. Manifest jest zgodny ze schematem jednostki Aplikacja i automatycznie formatuje manifest po zapisaniu. Nowe elementy są dodawane do optionalClaims właściwości .

    "optionalClaims": {
    "idToken": [
        {
            "name": "upn",
            "essential": false,
            "additionalProperties": [
                "include_externally_authenticated_upn"
            ]
        }
    ],
    "accessToken": [
        {
            "name": "auth_time",
            "essential": false
        }
    ],
    "saml2Token": [
        {
            "name": "extension_ab603c56068041afb2f6832e2a17e237_skypeId",
            "source": "user",
            "essential": true
        }
    ]
}

  4. Po zakończeniu aktualizowania manifestu wybierz pozycję Zapisz , aby zapisać manifest.

Ograniczenie

Aplikacja może wydać maksymalną liczbę 10 atrybutów rozszerzenia jako opcjonalne oświadczenia.

Powiązana zawartość