Udostępnij za pośrednictwem

Dokumentacja opcjonalnych oświadczeń

  • Artykuł

Możesz użyć opcjonalnych oświadczeń, aby:

  • Wybierz oświadczenia, które mają być uwzględnione w tokenach dla aplikacji.
  • Zmień zachowanie niektórych oświadczeń zwracanych przez platformę tożsamości firmy Microsoft w tokenach.
  • Dodawanie i uzyskiwanie dostępu do oświadczeń niestandardowych dla aplikacji.

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. Na platformie tożsamości firmy 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 N/A 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 aplikacji. 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.

Nuta

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 Opis Typ tokenu Typ użytkownika Notatki
acct Stan konta użytkowników w dzierżawie JWT, SAML Jeśli użytkownik jest członkiem dzierżawy, wartość jest 0. Jeśli jesteś gościem, wartość jest 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 Validate the user has permission to access this data. 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, 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ć oświadczenie login_hint, a następnie wysłać oświadczenie i bieżący kontekst dzierżawy do aplikacji B w ciągu zapytania lub fragment, gdy użytkownik wybierze link, który przeniesie je do aplikacji B. Aby uniknąć problemów z warunkami wyścigu i niezawodnością, login_hint oświadczenia nie uwzględnić bieżącej dzierżawy dla użytkownika i domyślnie dzierżawy głównej 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 funkcjami login_hint zestawu SDK, jednak uwidocznione.
tenant_ctry Kraj/region dzierżawy zasobów JWT Tak samo jak ctry z wyjątkiem ustawiania na poziomie dzierżawy przez administratora. Musi być również 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 Secure applications and APIs by validating claims. 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 do wyświetlania stanu logowania użytkownikowi: preferred_username lub unique_name dla tokenów v1 i preferred_username dla 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ć oświadczenia login_hint 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 Claims wyzwania, żą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 serwisu Facebook iWS-FedWS-Fed nie zweryfikowane domeny. Aby oświadczenie zostało zwrócone w tokenie, wymagana jest obecność oświadczenia email.
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ę Microsoft Entra Connect 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. Sformatowane 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 na potrzeby Windows AutoPilot.

Ostrzeżenie

Nigdy nie używaj email lub upn wartości oświadczeń do przechowywania lub 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 Opis Notatki
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 zaufanych adresów IP ustawień 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. Wymaga zakresu profile.
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. Wymaga zakresu profile.
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 Secure applications and APIs by validating claims. 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 oświadczenia preferred_username, aby wyświetlić stan logowania do użytkownika. Wymaga zakresu profile.

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 Opis Notatki
aud Audiencja 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 dla 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 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. Te additionalProperties są 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 nazwa additionalProperty 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 wymienione wcześniej, z wyjątkiem tego, ż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 oświadczenia aud. To oświadczenie nie ma wpływu na tokeny w wersji 2 lub tokeny identyfikatorów wersji, gdzie oświadczenie aud 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 jako oświadczenie aud zawsze, a nie zależne od środowiska uruchomieniowego. Jeśli na przykład zasób ustawia tę flagę, a jego identyfikator klienta jest 00001111-aaaa-2222-bbbb-3333cccc4444, każda aplikacja żąda tokenu dostępu dla tego zasobu otrzymuje token dostępu z 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 oraz 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 idtyp dla tokenu 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.

przykład additionalProperties

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

Ten obiekt optionalClaims powoduje, że token identyfikatora zwrócony klientowi zawiera oświadczenie upn z innymi dzierżawami macierzystymi i informacjami 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