Dokumentacja oświadczeń tokenu identyfikatora

Artykuł
10/24/2023

Tokeny identyfikatorów to tokeny internetowe JSON (JWT). Tokeny identyfikatorów w wersji 1.0 i 2.0 mają różnice w posiadanych informacjach. Wersja jest oparta na punkcie końcowym, z którego zażądano. Chociaż istniejące aplikacje prawdopodobnie używają punktu końcowego usługi Azure AD w wersji 1.0, nowe aplikacje powinny używać punktu końcowego w wersji 2.0.

Wersja 1.0: https://login.microsoftonline.com/common/oauth2/authorize
Wersja 2.0: https://login.microsoftonline.com/common/oauth2/v2.0/authorize

Wszystkie oświadczenia JWT wymienione w poniższych sekcjach są wyświetlane zarówno w tokenach w wersji 1.0, jak i 2.0, chyba że określono inaczej. Tokeny identyfikatorów składają się z nagłówka, ładunku i podpisu. Nagłówek i podpis są używane do weryfikowania autentyczności tokenu, podczas gdy ładunek zawiera informacje o użytkowniku żądanym przez klienta.

Oświadczenia nagłówka

W poniższej tabeli przedstawiono oświadczenia nagłówka obecne w tokenach identyfikatorów.

Oświadczenie	Format	opis
`typ`	Ciąg — zawsze "JWT"	Wskazuje, że token jest tokenem JWT.
`alg`	String	Wskazuje algorytm użyty do podpisania tokenu. Na przykład: "RS256"
`kid`	String	Określa odcisk palca klucza publicznego, który może służyć do weryfikowania podpisu tokenu. Emitowane w tokenach identyfikatorów w wersji 1.0 i 2.0.
`x5t`	String	Funkcje takie same (w użyciu i wartości) co `kid`. `x5t` to starsze oświadczenie emitowane tylko w tokenach identyfikatorów w wersji 1.0 na potrzeby zgodności.

Oświadczenia ładunku

W poniższej tabeli przedstawiono oświadczenia, które są domyślnie w większości tokenów identyfikatorów (z wyjątkiem przypadków zanotowane). Jednak aplikacja może użyć opcjonalnych oświadczeń, aby zażądać większej liczby oświadczeń w tokenie identyfikatora. Opcjonalne oświadczenia mogą wahać się od groups oświadczenia do informacji o nazwie użytkownika.

Oświadczenie	Format	opis
`aud`	Ciąg, identyfikator GUID identyfikatora aplikacji	Identyfikuje zamierzonego adresata tokenu. W `id_tokens`programie odbiorcy to identyfikator aplikacji aplikacji przypisany do aplikacji w witrynie Azure Portal. Ta wartość powinna zostać zweryfikowana. Token powinien zostać odrzucony, jeśli nie będzie zgodny z identyfikatorem aplikacji aplikacji.
`iss`	Ciąg, identyfikator URI wystawcy	Identyfikuje wystawcę lub "serwer autoryzacji", który konstruuje i zwraca token. Identyfikuje również dzierżawę, dla której użytkownik został uwierzytelniony. Jeśli token został wystawiony przez punkt końcowy w wersji 2.0, identyfikator URI kończy się na .`/v2.0` Identyfikator GUID wskazujący, że użytkownik jest użytkownikiem konsumenckim z konta Microsoft, to `9188040d-6c67-4c5b-b112-36a304b66dad`. Aplikacja powinna używać części identyfikatora GUID oświadczenia, aby ograniczyć zestaw dzierżaw, które mogą logować się do aplikacji, jeśli ma to zastosowanie.
`iat`	int, sygnatura czasowa systemu Unix	Wskazuje, kiedy wystąpiło uwierzytelnianie tokenu.
`idp`	Ciąg, zazwyczaj identyfikator URI usługi STS	Rejestruje dostawcę tożsamości, który uwierzytelnił podmiot tokenu. Ta wartość jest identyczna z wartością oświadczenia wystawcy, chyba że konto użytkownika nie znajduje się w tej samej dzierżawie co wystawca — na przykład goście. Jeśli oświadczenie nie jest obecne, oznacza to, że można zamiast tego użyć wartości `iss` . W przypadku kont osobistych używanych w kontekście organizacyjnym (na przykład konta osobistego zaproszonego do dzierżawy) `idp` oświadczenie może mieć wartość "live.com" lub identyfikator URI usługi STS zawierający dzierżawę `9188040d-6c67-4c5b-b112-36a304b66dad`konta Microsoft.
`nbf`	int, sygnatura czasowa systemu Unix	Określa czas, przed którym nie można zaakceptować JWT do przetwarzania.
`exp`	int, sygnatura czasowa systemu Unix	Określa czas wygaśnięcia w dniu lub po upływie którego nie można zaakceptować JWT do przetwarzania. W pewnych okolicznościach zasób może odrzucić token przed tym razem. Jeśli na przykład wymagana jest zmiana uwierzytelniania lub wykryto odwołanie tokenu.
`c_hash`	String	Skrót kodu jest uwzględniany w tokenach identyfikatorów tylko wtedy, gdy token identyfikatora jest wystawiony za pomocą kodu autoryzacji OAuth 2.0. Może służyć do weryfikowania autentyczności kodu autoryzacji. Aby dowiedzieć się, jak to zrobić, zobacz specyfikację openID Połączenie. To oświadczenie nie jest zwracane w tokenach identyfikatorów z punktu końcowego /token.
`at_hash`	String	Skrót tokenu dostępu jest uwzględniany w tokenach identyfikatorów tylko wtedy, gdy token identyfikatora jest wystawiany z `/authorize` punktu końcowego przy użyciu tokenu dostępu OAuth 2.0. Może służyć do weryfikowania autentyczności tokenu dostępu. Aby dowiedzieć się, jak to zrobić, zobacz specyfikację openID Połączenie. To oświadczenie nie jest zwracane w tokenach identyfikatorów z punktu końcowego `/token` .
`aio`	Nieprzezroczystym ciągiem	Wewnętrzne oświadczenie używane do rejestrowania danych w celu ponownego użycia tokenu. Należy zignorować.
`preferred_username`	String	Podstawowa nazwa użytkownika reprezentująca użytkownika. Może to być adres e-mail, numer telefonu lub ogólna nazwa użytkownika bez określonego formatu. Jego wartość jest modyfikowalna i może ulec zmianie w czasie. Ponieważ jest on modyfikowalny, tej wartości nie można użyć do podejmowania decyzji dotyczących autoryzacji. Może służyć do wskazówek dotyczących nazwy użytkownika i interfejsu użytkownika czytelnego dla człowieka jako nazwy użytkownika. Zakres jest wymagany do otrzymania `profile` tego oświadczenia. Obecne tylko w tokenach w wersji 2.0.
`email`	String	Prezentuj domyślnie dla kont gości, które mają adres e-mail. Aplikacja może zażądać oświadczenia e-mail dla użytkowników zarządzanych (z tej samej dzierżawy co zasób) przy użyciu opcjonalnego `email`oświadczenia. Ta wartość nie ma gwarancji, że jest poprawna i jest modyfikowalna w czasie. Nigdy nie używaj go do autoryzacji lub zapisywania danych dla użytkownika. Jeśli potrzebujesz adresowego adresu e-mail w aplikacji, zażądaj tych danych od użytkownika bezpośrednio, używając tego oświadczenia jako sugestii lub wstępnego wypełniania środowiska użytkownika. W punkcie końcowym w wersji 2.0 aplikacja może również zażądać `email` zakresu openID Połączenie — nie musisz żądać zarówno opcjonalnego oświadczenia, jak i zakresu, aby uzyskać oświadczenie.
`name`	String	Oświadczenie `name` zawiera czytelną dla człowieka wartość, która identyfikuje temat tokenu. Nie ma gwarancji, że wartość jest unikatowa, można ją zmienić i powinna być używana tylko do celów wyświetlania. Zakres jest wymagany do otrzymania `profile` tego oświadczenia.
`nonce`	String	Nonce pasuje do parametru uwzględnionego w oryginalnym żądaniu autoryzacji do dostawcy tożsamości. Jeśli nie jest ona zgodna, aplikacja powinna odrzucić token.
`oid`	Ciąg, identyfikator GUID	Niezmienny identyfikator obiektu, w tym przypadku konto użytkownika. Ten identyfikator jednoznacznie identyfikuje użytkownika w aplikacjach — dwa różne aplikacje logując się w tym samym użytkowniku otrzymują tę samą wartość w oświadczeniu `oid` . Program Microsoft Graph zwraca ten identyfikator jako `id` właściwość konta użytkownika. Ze względu na to `oid` , że aplikacja zezwala wielu aplikacjom na korelowanie użytkowników, zakres jest wymagany do otrzymania `profile` tego oświadczenia. Jeśli jeden użytkownik istnieje w wielu dzierżawach, użytkownik zawiera inny identyfikator obiektu w każdej dzierżawie — są traktowane jako różne konta, mimo że użytkownik loguje się do każdego konta przy użyciu tych samych poświadczeń. Oświadczenie `oid` jest identyfikatorem GUID i nie można go ponownie użyć.
`roles`	Tablica ciągów	Zestaw ról przypisanych do użytkownika, który się loguje.
`rh`	Nieprzezroczystym ciągiem	Wewnętrzne oświadczenie używane do ponownego stosowania tokenów. Należy zignorować.
`sub`	String	Temat informacji w tokenie. Na przykład użytkownik aplikacji. Ta wartość jest niezmienna i nie można jej ponownie przypisać ani ponownie użyć. Temat jest identyfikatorem parowania i jest unikatowy dla identyfikatora aplikacji. Jeśli jeden użytkownik zaloguje się do dwóch różnych aplikacji przy użyciu dwóch różnych identyfikatorów klientów, te aplikacje otrzymają dwie różne wartości oświadczenia podmiotu. Możesz lub nie chcesz mieć dwóch wartości w zależności od architektury i wymagań dotyczących prywatności.
`tid`	Ciąg, identyfikator GUID	Reprezentuje dzierżawę, do której loguje się użytkownik. W przypadku kont służbowych identyfikator GUID jest niezmiennym identyfikatorem dzierżawy organizacji, do której loguje się użytkownik. W przypadku logowania się do osobistej dzierżawy konta Microsoft (usług takich jak Xbox, Teams for Life lub Outlook) wartość to `9188040d-6c67-4c5b-b112-36a304b66dad`.
`unique_name`	String	Obecne tylko w tokenach w wersji 1.0. Udostępnia zrozumiałą wartość identyfikującą podmiot tokenu. Ta wartość nie ma gwarancji, że jest unikatowa w ramach dzierżawy i powinna być używana tylko do celów wyświetlania.
`uti`	String	Oświadczenie identyfikatora tokenu, równoważne `jti` w specyfikacji JWT. Unikatowy identyfikator dla tokenu, który jest uwzględniany w wielkości liter.
`ver`	Ciąg, 1.0 lub 2.0	Wskazuje wersję tokenu identyfikatora.
`hasgroups`	Wartość logiczna	Jeśli jest obecny, zawsze prawda, oznaczanie użytkownika znajduje się w co najmniej jednej grupie. Używane zamiast oświadczenia grup dla zestawów JWTs w przepływach niejawnych udzielania, gdy oświadczenie pełne grupy rozszerza fragment identyfikatora URI poza limity długości adresu URL (obecnie sześć lub więcej grup). Wskazuje, że klient powinien używać interfejsu API programu Microsoft Graph do określania grup użytkownika (`https://graph.microsoft.com/v1.0/users/{userID}/getMemberObjects`).
`groups:src1`	Obiekt JSON	W przypadku żądań tokenów, które nie mają ograniczonej długości (zobacz `hasgroups`), ale nadal są zbyt duże dla tokenu, dołączono link do pełnej listy grup dla użytkownika. W przypadku zestawów JWTs jako oświadczenia rozproszonego w przypadku protokołu SAML jako nowego oświadczenia zamiast `groups` oświadczenia. Przykładowa wartość JWT: `"groups":"src1"` `"_claim_sources`: `"src1" : { "endpoint" : "https://graph.microsoft.com/v1.0/users/{userID}/getMemberObjects" }` Aby uzyskać więcej informacji, zobacz Oświadczenia dotyczące nadwyżki grup.

Niezawodne identyfikowanie użytkownika przy użyciu oświadczeń

Podczas identyfikowania użytkownika kluczowe jest użycie informacji, które pozostają stałe i unikatowe w czasie. Starsze aplikacje czasami używają pól, takich jak adres e-mail, numer telefonu lub nazwa UPN. Wszystkie te pola mogą się zmieniać w czasie i mogą być również ponownie używane w czasie. Na przykład gdy pracownik zmieni nazwę lub pracownik otrzyma adres e-mail zgodny z poprzednim, nie jest już obecny pracownik. Aplikacja nie może używać danych czytelnych dla człowieka, aby zidentyfikować użytkownika — czytelne dla człowieka zazwyczaj oznacza, że ktoś może go odczytać i chce go zmienić. Zamiast tego należy użyć oświadczeń dostarczonych przez standard OIDC lub oświadczeń rozszerzeń dostarczonych przez firmę Microsoft — oświadczenia sub i oid .

Aby poprawnie przechowywać informacje dla użytkownika, użyj sub lub oid sam (który jako identyfikatory GUID są unikatowe) z użyciem tid routingu lub fragmentowania w razie potrzeby. Jeśli musisz udostępniać dane między usługami i oidtid najlepiej, ponieważ wszystkie aplikacje uzyskują te same oid oświadczenia i tid oświadczenia dla użytkownika działającego w dzierżawie. Oświadczenie sub jest parą mądrą wartością, która jest unikatowa. Wartość jest oparta na kombinacji adresata tokenu, dzierżawy i użytkownika. Dwie aplikacje, które żądają tokenów identyfikatorów dla użytkownika, otrzymują różne sub oświadczenia, ale te same oid oświadczenia dla tego użytkownika.

Uwaga

Nie używaj idp oświadczenia do przechowywania informacji o użytkowniku w celu skorelowania użytkowników między dzierżawami. Nie działa, ponieważ oid oświadczenia i sub dla użytkownika zmieniają się w dzierżawach zgodnie z projektem, aby zapewnić, że aplikacje nie mogą śledzić użytkowników w różnych dzierżawach.

Scenariusze gościa, w których użytkownik znajduje się w jednej dzierżawie i uwierzytelnia się w innej dzierżawie, powinny traktować użytkownika tak, jakby był nowym użytkownikiem usługi. Dokumenty i uprawnienia w jednej dzierżawie nie powinny być stosowane w innej dzierżawie. To ograniczenie jest ważne, aby zapobiec przypadkowemu wyciekowi danych między dzierżawami i wymuszaniu cykli życia danych. Eksmitowanie gościa z dzierżawy powinno również usunąć dostęp do danych utworzonych w tej dzierżawie.

Oświadczenie dotyczące nadwyżki grup

Aby upewnić się, że rozmiar tokenu nie przekracza limitów rozmiaru nagłówka HTTP, liczba identyfikatorów obiektów uwzględnionych w oświadczeniu groups jest ograniczona. Jeśli użytkownik jest członkiem większej liczby grup niż limit nadwyżki (150 dla tokenów SAML, 200 dla tokenów JWT), oświadczenie grup nie jest uwzględnione w tokenie. Zamiast tego zawiera oświadczenie nadwyżkowe w tokenie wskazującym aplikacji na wykonywanie zapytań względem interfejsu API programu Microsoft Graph w celu pobrania członkostwa w grupie użytkownika.

{
  ...
  "_claim_names": {
   "groups": "src1"
    },
    {
  "_claim_sources": {
    "src1": {
        "endpoint":"[Url to get this user's group membership from]"
        }
       }
     }
  ...
}

Następne kroki

Dowiedz się więcej o tokenach identyfikatorów używanych w identyfikatorze Entra firmy Microsoft.

Share via