Udostępnij za pośrednictwem

Dokumentacja oświadczeń tokenu identyfikatora

  • Artykuł

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_tokensprogramie 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-36a304b66dadkonta 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 wykonać tę walidację, zobacz specyfikację openID Connect. 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 wykonać tę walidację, zobacz specyfikację openID Connect. 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 Connect — 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. 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 oid tid 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