Dokumentacja opcjonalnych oświadczeń

  • Artykuł

Za pomocą opcjonalnych oświadczeń można:

  • Wybierz oświadczenia, które mają być uwzględnione w tokenach dla aplikacji.
  • Zmieniać zachowanie określonych oświadczeń, które platforma tożsamości firmy Microsoft zwraca w tokenach.
  • Dodawać oświadczenia niestandardowe dla aplikacji i uzyskiwać do nich dostęp.

Mimo że opcjonalne oświadczenia są obsługiwane zarówno w tokenach formatu w wersji 1.0, jak i w wersji 2.0 oraz tokenach JĘZYKA SAML, zapewniają większość ich wartości podczas przechodzenia z wersji 1.0 do 2.0. W Platforma tożsamości Microsoft mniejsze rozmiary tokenów są używane w celu zapewnienia optymalnej wydajności przez klientów. W związku z tym w tokenach dostępu i identyfikatorów nie ma już tokenów dostępu i identyfikatorów w wersji 2.0, które muszą zostać poproszone o podanie w szczególności dla poszczególnych aplikacji.

Typ konta Tokeny w wersji 1.0 Tokeny w wersji 2.0
Osobiste konto Microsoft Nie dotyczy Obsługiwane
Konto Microsoft Entra Obsługiwane Obsługiwane

Zestaw opcjonalnych oświadczeń w wersji 1.0 i 2.0

Zestaw opcjonalnych oświadczeń dostępnych domyślnie dla aplikacji do użycia jest wymieniony w poniższej tabeli. Możesz użyć danych niestandardowych w atrybutach rozszerzenia i rozszerzeniach katalogu, aby dodać opcjonalne oświadczenia dla aplikacji. Po dodaniu oświadczeń do tokenu dostępu oświadczenia mają zastosowanie do tokenów dostępu żądanych dla aplikacji (internetowego interfejsu API), a nie oświadczeń żądanych przez aplikację. Niezależnie od tego, jak klient uzyskuje dostęp do interfejsu API, odpowiednie dane znajdują się w tokenie dostępu używanym do uwierzytelniania w interfejsie API.

Uwaga

Większość tych oświadczeń może być uwzględniona w zestawach JWTs dla tokenów w wersji 1.0 i 2.0, ale nie w tokenach JĘZYKA SAML, z wyjątkiem przypadków zanotowania w kolumnie Typ tokenu. Konta konsumentów obsługują podzestaw tych oświadczeń oznaczony w kolumnie Typ użytkownika. Wiele wymienionych oświadczeń nie ma zastosowania do użytkowników konsumentów (nie mają dzierżawy, więc tenant_ctry nie ma wartości).

W poniższej tabeli wymieniono opcjonalny zestaw oświadczeń w wersji 1.0 i 2.0.

Nazwa/nazwisko opis Typ tokenu Typ użytkownika Uwagi
acct Stan konta użytkowników w dzierżawie JWT, SAML Jeśli użytkownik jest członkiem dzierżawy, wartość to 0. Jeśli jesteś gościem, wartość to 1.
acrs Identyfikatory kontekstu uwierzytelniania JWT Microsoft Entra ID Wskazuje identyfikatory kontekstu uwierzytelniania operacji, które obiekt nośny kwalifikuje się do wykonania. Identyfikatory kontekstu uwierzytelniania mogą służyć do wyzwalania zapotrzebowania na uwierzytelnianie krokowe z poziomu aplikacji i usług. Często używane wraz z oświadczeniem xms_cc .
auth_time Godzina ostatniego uwierzytelnienia użytkownika. JWT
ctry Kraj/region użytkownika JWT To oświadczenie jest zwracane, jeśli jest obecne, a wartość pola jest standardowym dwuliterowym kodem kraju/regionu, takim jak FR, JP, SZ itd.
email Zgłoszony adres e-mail dla tego użytkownika JWT, SAML MSA, Microsoft Entra ID Ta wartość jest domyślnie uwzględniana, jeśli użytkownik jest gościem w dzierżawie. W przypadku użytkowników zarządzanych (użytkowników wewnątrz dzierżawy) należy zażądać go tylko za pośrednictwem tego opcjonalnego oświadczenia lub tylko w wersji 2.0 z zakresem OpenID. Ta wartość nie ma gwarancji, że jest poprawna i jest modyfikowalna w czasie — nigdy nie używaj jej do autoryzacji ani zapisywania danych dla użytkownika. Aby uzyskać więcej informacji, zobacz Weryfikowanie, czy użytkownik ma uprawnienia dostępu do tych danych. Jeśli używasz oświadczenia e-mail do autoryzacji, zalecamy przeprowadzenie migracji, aby przejść do bezpieczniejszego oświadczenia. Jeśli potrzebujesz adresowego adresu e-mail w aplikacji, zażądaj tych danych bezpośrednio od użytkownika, używając tego oświadczenia jako sugestii lub wstępnego wypełniania środowiska użytkownika.
fwd Adres IP JWT Dodaje oryginalny adres klienta żądającego (w sieci wirtualnej).
groups Opcjonalne formatowanie oświadczeń grup JWT, SAML Oświadczenie groups jest używane z ustawieniem GroupMembershipClaims w manifeście aplikacji, które należy również ustawić.
idtyp Typ tokenu Tokeny dostępu JWT Specjalne: tylko w tokenach dostępu tylko dla aplikacji Wartość jest app wtedy, gdy token jest tokenem tylko dla aplikacji. To oświadczenie jest najbardziej dokładnym sposobem dla interfejsu API w celu określenia, czy token jest tokenem aplikacji, czy tokenem aplikacji i tokenu użytkownika.
login_hint Wskazówka logowania JWT MSA, Microsoft Entra ID Nieprzezroczyste, niezawodne oświadczenie wskazówki logowania, które jest zakodowane w formacie base 64. Nie modyfikuj tej wartości. To oświadczenie jest najlepszą wartością do użycia dla parametru login_hint OAuth we wszystkich przepływach w celu uzyskania logowania jednokrotnego. Może on być przekazywany między aplikacjami, aby ułatwić im dyskretne logowanie jednokrotne — aplikacja A może zalogować użytkownika, odczytać login_hint oświadczenie, a następnie wysłać oświadczenie i bieżący kontekst dzierżawy do aplikacji B w ciągu zapytania lub fragmentu, gdy użytkownik wybierze link, który przeniesie go do aplikacji B. Aby uniknąć problemów z warunkami wyścigu i niezawodnością, login_hint oświadczenie nie obejmuje bieżącej dzierżawy użytkownika i domyślnie jest to dzierżawa domowa użytkownika w przypadku użycia. W scenariuszu gościa, w którym użytkownik pochodzi z innej dzierżawy, należy podać identyfikator dzierżawy w żądaniu logowania. i przekaż je do aplikacji, z których współpracujesz. To oświadczenie jest przeznaczone do użycia z istniejącymi login_hint funkcjami zestawu SDK, jednak uwidocznione.
sid Identyfikator sesji, używany do wylogowania użytkownika sesji JWT Konta osobiste i Microsoft Entra.
tenant_ctry Kraj/region dzierżawy zasobów JWT Tak samo jak ctry w przypadku ustawienia na poziomie dzierżawy przez administratora. Musi również być standardową dwuliterową wartością.
tenant_region_scope Region dzierżawy zasobów JWT
upn UserPrincipalName JWT, SAML Identyfikator użytkownika, który może być używany z parametrem username_hint . Nie jest trwałym identyfikatorem użytkownika i nie powinien być używany do autoryzacji ani do unikatowych informacji o użytkowniku tożsamości (na przykład jako klucza bazy danych). Zamiast tego użyj identyfikatora obiektu użytkownika (oid) jako klucza bazy danych. Aby uzyskać więcej informacji, zobacz Zabezpieczanie aplikacji i interfejsów API przez weryfikowanie oświadczeń. Użytkownicy logujący się przy użyciu alternatywnego identyfikatora logowania nie powinni być wyświetlani ich głównej nazwy użytkownika (UPN). Zamiast tego użyj następujących oświadczeń tokenu identyfikatora, aby wyświetlić stan logowania do użytkownika: preferred_username lub unique_name dla tokenów v1 i preferred_username tokenów w wersji 2. Mimo że to oświadczenie jest automatycznie dołączane, można określić je jako opcjonalne oświadczenie, aby dołączyć inne właściwości w celu zmodyfikowania jego zachowania w przypadku użytkownika-gościa. Należy użyć login_hint oświadczenia do login_hint użycia — identyfikatory czytelne dla człowieka, takie jak NAZWA UPN, są zawodne.
verified_primary_email Źródło z adresu PrimaryAuthoritativeEmail użytkownika JWT
verified_secondary_email Źródło z secondaryAuthoritativeEmail użytkownika JWT
vnet Informacje o specyfikatorze sieci wirtualnej. JWT
xms_cc Możliwości klienta JWT Microsoft Entra ID Wskazuje, czy aplikacja kliencka, która uzyskała token, jest w stanie sprostać wyzwaniom związanym z oświadczeniami. Jest on często używany wraz z oświadczeniem acrs. To oświadczenie jest często używane w scenariuszach dostępu warunkowego i oceny dostępu ciągłego. Serwer zasobów lub aplikacja usługi wystawiona dla tokenu kontroluje obecność tego oświadczenia w tokenie. Wartość cp1 w tokenie dostępu to autorytatywny sposób identyfikowania, że aplikacja kliencka może obsługiwać wyzwanie dotyczące oświadczeń. Aby uzyskać więcej informacji, zobacz Wyzwania dotyczące oświadczeń, żądania oświadczeń i możliwości klienta.
xms_edov Wartość logiczna wskazująca, czy właściciel domeny poczty e-mail użytkownika został zweryfikowany. JWT Wiadomość e-mail jest uważana za zweryfikowaną domenę, jeśli należy do dzierżawy, w której znajduje się konto użytkownika, a administrator dzierżawy dokonał weryfikacji domeny. Ponadto adres e-mail musi pochodzić z konta Microsoft (MSA), konta Google lub używanego do uwierzytelniania przy użyciu przepływu jednorazowego kodu dostępu (OTP). Konta Facebook i SAML/WS-Fed nie mają zweryfikowanych domen. Aby oświadczenie zostało zwrócone w tokenie, wymagana jest obecność email oświadczenia.
xms_pdl Preferowana lokalizacja danych JWT W przypadku dzierżaw multi-geo preferowana lokalizacja danych to trzyliterowy kod pokazujący region geograficzny, w którym znajduje się użytkownik. Aby uzyskać więcej informacji, zobacz dokumentację usługi Microsoft Entra Połączenie dotyczącą preferowanej lokalizacji danych.
xms_pl Preferowany język użytkownika JWT Preferowany język użytkownika, jeśli jest ustawiony. Źródło z dzierżawy głównej w scenariuszach dostępu gościa. Sformatowany LL-CC ("en-us").
xms_tpl Preferowany język dzierżawy JWT Preferowany język dzierżawy zasobów, jeśli jest ustawiony. Sformatowany ll ("en").
ztdid Identyfikator wdrożenia bezdotykowego JWT Tożsamość urządzenia używana dla elementu Windows AutoPilot.

Ostrzeżenie

Nigdy nie używaj email wartości ani oświadczeń do przechowywania lub upn określania, czy użytkownik w tokenie dostępu powinien mieć dostęp do danych. Modyfikowalne wartości oświadczeń, takie jak te, mogą się zmieniać w czasie, co sprawia, że są niezabezpieczone i zawodne na potrzeby autoryzacji.

Zestaw oświadczeń opcjonalnych specyficznych dla wersji 2.0

Te oświadczenia są zawsze uwzględniane w tokenach w wersji 1.0, ale nie są uwzględniane w tokenach w wersji 2.0, chyba że są wymagane. Te oświadczenia mają zastosowanie tylko dla tokenów JWTs (tokenów identyfikatorów i tokenów dostępu).

Oświadczenie JWT Nazwa/nazwisko opis Uwagi
ipaddr Adres IP Adres IP, z którego zalogował się klient.
onprem_sid Identyfikator zabezpieczeń lokalnych
pwd_exp Czas wygaśnięcia hasła Liczba sekund po upływie czasu w oświadczeniu iat , w którym wygasa hasło. To oświadczenie jest uwzględniane tylko wtedy, gdy hasło wygasa wkrótce (zgodnie z definicją "dni powiadomień" w zasadach haseł).
pwd_url Zmienianie adresu URL hasła Adres URL, który użytkownik może odwiedzić, aby zmienić hasło. To oświadczenie jest uwzględniane tylko wtedy, gdy hasło wygasa wkrótce (zgodnie z definicją "dni powiadomień" w zasadach haseł).
in_corp Wewnątrz sieci firmowej Sygnały, czy klient loguje się z sieci firmowej. Jeśli tak nie jest, oświadczenie nie zostanie uwzględnione. Na podstawie ustawień zaufanych adresów IP w usłudze MFA.
family_name Nazwisko Podaje nazwisko, nazwisko lub nazwisko użytkownika zgodnie z definicją w obiekcie użytkownika. Na przykład "family_name":"Miller". Obsługiwane w usługach MSA i Microsoft Entra ID. profile Wymaga zakresu.
given_name Imię Udostępnia pierwszą lub "daną" nazwę użytkownika, ustawioną na obiekcie użytkownika. Na przykład "given_name": "Frank". Obsługiwane w usługach MSA i Microsoft Entra ID. profile Wymaga zakresu.
upn Główna nazwa użytkownika Identyfikator użytkownika, który może być używany z parametrem username_hint . Nie jest trwałym identyfikatorem użytkownika i nie powinien być używany do autoryzacji ani do unikatowych informacji o użytkowniku tożsamości (na przykład jako klucza bazy danych). Aby uzyskać więcej informacji, zobacz Zabezpieczanie aplikacji i interfejsów API przez weryfikowanie oświadczeń. Zamiast tego użyj identyfikatora obiektu użytkownika (oid) jako klucza bazy danych. Użytkownicy logujący się przy użyciu alternatywnego identyfikatora logowania nie powinni być wyświetlani ich głównej nazwy użytkownika (UPN). Zamiast tego użyj następującego preferred_username oświadczenia, aby wyświetlić stan logowania do użytkownika. profile Wymaga zakresu.

Zestaw oświadczeń opcjonalnych specyficznych dla wersji 1.0

Niektóre ulepszenia formatu tokenu w wersji 2 są dostępne dla aplikacji korzystających z formatu tokenu w wersji 1, ponieważ pomagają zwiększyć bezpieczeństwo i niezawodność. Te ulepszenia dotyczą tylko tokenów JWTs, a nie tokenów SAML.

Oświadczenie JWT Nazwa/nazwisko opis Uwagi
aud Odbiorcy Zawsze obecne w zestawach JWTs, ale w tokenach dostępu w wersji 1 można je emitować na różne sposoby — dowolny identyfikator URI appID z ukośnikiem lub bez końcowego ukośnika oraz identyfikator klienta zasobu. Ta losowość może być trudna do zakodowania podczas przeprowadzania weryfikacji tokenu. Użyj additionalProperties tego oświadczenia, aby upewnić się, że jest on zawsze ustawiony na identyfikator klienta zasobu w tokenach dostępu w wersji 1. Tylko tokeny dostępu JWT w wersji 1
preferred_username Preferowana nazwa użytkownika Udostępnia preferowane oświadczenie nazwy użytkownika w tokenach w wersji 1. To oświadczenie ułatwia aplikacjom podawanie wskazówek dotyczących nazwy użytkownika i wyświetlanie czytelnych przez człowieka nazw wyświetlanych, niezależnie od typu tokenu. Zaleca się użycie tego opcjonalnego oświadczenia zamiast używania upn metody lub unique_name. Tokeny identyfikatorów w wersji 1 i tokeny dostępu

additionalProperties opcjonalnych oświadczeń

Niektóre opcjonalne oświadczenia można skonfigurować tak, aby zmienić sposób zwracania oświadczenia. Są one additionalProperties najczęściej używane do migracji aplikacji lokalnych z różnymi oczekiwaniami dotyczącymi danych. Na przykład include_externally_authenticated_upn_without_hash pomaga klientom, którzy nie mogą obsługiwać znaków skrótu (#) w nazwie UPN.

Nazwa właściwości additionalProperty Nazwa opis
upn Może być używany zarówno dla odpowiedzi SAML, jak i JWT oraz dla tokenów v1.0 i v2.0.
include_externally_authenticated_upn Zawiera nazwę UPN gościa przechowywaną w dzierżawie zasobów. Na przykład foo_hometenant.com#EXT#@resourcetenant.com.
include_externally_authenticated_upn_without_hash Tak samo jak pokazano wcześniej, z tą różnicą, że znaczniki skrótu (#) są zastępowane podkreśleniami (_), na przykład foo_hometenant.com_EXT_@resourcetenant.com.
aud W tokenach dostępu w wersji 1 to oświadczenie służy do zmiany formatu aud oświadczenia. To oświadczenie nie ma wpływu na tokeny w wersji 2 lub tokeny identyfikatora wersji, gdzie aud oświadczenie jest zawsze identyfikatorem klienta. Użyj tej konfiguracji, aby upewnić się, że interfejs API może łatwiej przeprowadzić walidację odbiorców. Podobnie jak wszystkie opcjonalne oświadczenia wpływające na token dostępu, zasób w żądaniu musi ustawić to opcjonalne oświadczenie, ponieważ zasoby są właścicielem tokenu dostępu.
use_guid Emituje identyfikator klienta zasobu (API) w formacie GUID, ponieważ aud oświadczenie zawsze zamiast jest zależne od środowiska uruchomieniowego. Jeśli na przykład zasób ustawia tę flagę, a jej identyfikator klienta to 00001111-aaaa-2222-bbbb-3333cccc4444, każda aplikacja, która żąda tokenu dostępu dla tego zasobu, otrzymuje token dostępu za pomocą polecenia aud : 00001111-aaaa-2222-bbbb-3333cccc4444. Bez tego zestawu oświadczeń interfejs API może pobrać tokeny z oświadczeniem audapi://MyApi.com, api://MyApi.com/api://myapi.com/AdditionalRegisteredField lub dowolną inną wartością ustawioną jako identyfikator URI identyfikatora aplikacji dla tego interfejsu API i identyfikatorem klienta zasobu.
idtyp To oświadczenie służy do pobierania typu tokenu (aplikacji, użytkownika, urządzenia). Domyślnie jest emitowany tylko dla tokenów tylko aplikacji. Podobnie jak wszystkie opcjonalne oświadczenia wpływające na token dostępu, zasób w żądaniu musi ustawić to opcjonalne oświadczenie, ponieważ zasoby są właścicielem tokenu dostępu.
include_user_token Emituje oświadczenie dla tokenu idtyp użytkowników. Bez tej opcjonalnej dodatkowej właściwości zestawu oświadczeń idtyp interfejs API pobiera tylko oświadczenie dla tokenów aplikacji.

additionalProperties Przykład

"optionalClaims": {
    "idToken": [
        {
            "name": "upn",
            "essential": false,
            "additionalProperties": [
                "include_externally_authenticated_upn"
            ]
        }
    ]
}

Ten optionalClaims obiekt powoduje, że token identyfikatora zwrócony klientowi może dołączyć upn oświadczenie do innej dzierżawy macierzystej i informacji o dzierżawie zasobów. Oświadczenie upn jest zmieniane tylko w tokenie, jeśli użytkownik jest gościem w dzierżawie (który używa innego dostawcy tożsamości do uwierzytelniania).

Zobacz też

Następne kroki