Tokeny dostępu na platformie tożsamości firmy Microsoft

Artykuł
03/30/2023
Czas czytania: 23 min

Tokeny dostępu umożliwiają klientom bezpieczne wywoływanie chronionych internetowych interfejsów API. Tokeny dostępu są używane przez internetowe interfejsy API do przeprowadzania uwierzytelniania i autoryzacji.

Zgodnie ze specyfikacją protokołu OAuth tokeny dostępu są nieprzezroczyste ciągi bez ustawionego formatu. Niektórzy dostawcy tożsamości używają identyfikatorów GUID, a inne używają zaszyfrowanych obiektów blob. Format tokenu dostępu może zależeć od sposobu konfigurowania tokenu przez interfejs API, który akceptuje token.

Niestandardowe interfejsy API zarejestrowane przez deweloperów w Platforma tożsamości Microsoft mogą wybierać spośród dwóch różnych formatów tokenów sieci Web JSON (JWTs) wywoływanych v1.0 i v2.0. Interfejsy API opracowane przez firmę Microsoft, takie jak Program Microsoft Graph lub interfejsy API na platformie Azure, mają inne zastrzeżone formaty tokenów. Te zastrzeżone formaty mogą być zaszyfrowanymi tokenami, zestawami JWT lub specjalnymi tokenami przypominającymi JWT, które nie zostaną zweryfikowane.

Klienci muszą traktować tokeny dostępu jako nieprzezroczyste ciągi, ponieważ zawartość tokenu jest przeznaczona tylko dla interfejsu API. Tylko do celów walidacji i debugowania deweloperzy mogą dekodować JWTs przy użyciu witryny, takiej jak jwt.ms. Tokeny odbierane dla interfejsu API firmy Microsoft mogą nie zawsze być JWT i nie zawsze mogą być dekodowane.

Aby uzyskać szczegółowe informacje na temat tego, co znajduje się w tokenie dostępu, klienci powinni używać danych odpowiedzi tokenu zwróconych przy użyciu tokenu dostępu do klienta. Gdy klient żąda tokenu dostępu, Platforma tożsamości Microsoft również zwraca pewne metadane dotyczące tokenu dostępu do użycia aplikacji. Te informacje obejmują czas wygaśnięcia tokenu dostępu oraz zakresy, dla których są prawidłowe. Te dane umożliwiają aplikacji inteligentne buforowanie tokenów dostępu bez konieczności analizowania samego tokenu dostępu.

Zapoznaj się z poniższymi sekcjami, aby dowiedzieć się, jak interfejs API może weryfikować oświadczenia i używać ich w tokenie dostępu.

Uwaga

Cała dokumentacja na tej stronie, z wyjątkiem sytuacji, w której została zanotowana, ma zastosowanie tylko do tokenów wystawionych dla zarejestrowanych interfejsów API. Nie ma zastosowania do tokenów wystawionych dla interfejsów API należących do firmy Microsoft ani nie można ich używać do sprawdzania, w jaki sposób Platforma tożsamości Microsoft wystawia tokeny dla zarejestrowanego interfejsu API.

Formaty tokenów

W Platforma tożsamości Microsoft dostępne są dwie wersje tokenów dostępu: v1.0 i v2.0. Te wersje określają oświadczenia, które znajdują się w tokenie i upewnij się, że internetowy interfejs API może kontrolować zawartość tokenu.

Interfejsy API sieci Web mają jedną z następujących wersji wybranych jako domyślna podczas rejestracji:

Wersja 1.0 dla aplikacji tylko Azure AD. W poniższym przykładzie przedstawiono token w wersji 1.0 (ten przykład tokenu nie zostanie zweryfikowany, ponieważ klucze zostały obrócone przed publikacją i dane osobowe zostały usunięte):

eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSIsImtpZCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSJ9.eyJhdWQiOiJlZjFkYTlkNC1mZjc3LTRjM2UtYTAwNS04NDBjM2Y4MzA3NDUiLCJpc3MiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC9mYTE1ZDY5Mi1lOWM3LTQ0NjAtYTc0My0yOWYyOTUyMjIyOS8iLCJpYXQiOjE1MzcyMzMxMDYsIm5iZiI6MTUzNzIzMzEwNiwiZXhwIjoxNTM3MjM3MDA2LCJhY3IiOiIxIiwiYWlvIjoiQVhRQWkvOElBQUFBRm0rRS9RVEcrZ0ZuVnhMaldkdzhLKzYxQUdyU091TU1GNmViYU1qN1hPM0libUQzZkdtck95RCtOdlp5R24yVmFUL2tES1h3NE1JaHJnR1ZxNkJuOHdMWG9UMUxrSVorRnpRVmtKUFBMUU9WNEtjWHFTbENWUERTL0RpQ0RnRTIyMlRJbU12V05hRU1hVU9Uc0lHdlRRPT0iLCJhbXIiOlsid2lhIl0sImFwcGlkIjoiNzVkYmU3N2YtMTBhMy00ZTU5LTg1ZmQtOGMxMjc1NDRmMTdjIiwiYXBwaWRhY3IiOiIwIiwiZW1haWwiOiJBYmVMaUBtaWNyb3NvZnQuY29tIiwiZmFtaWx5X25hbWUiOiJMaW5jb2xuIiwiZ2l2ZW5fbmFtZSI6IkFiZSAoTVNGVCkiLCJpZHAiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC83MmY5ODhiZi04NmYxLTQxYWYtOTFhYi0yZDdjZDAxMjIyNDcvIiwiaXBhZGRyIjoiMjIyLjIyMi4yMjIuMjIiLCJuYW1lIjoiYWJlbGkiLCJvaWQiOiIwMjIyM2I2Yi1hYTFkLTQyZDQtOWVjMC0xYjJiYjkxOTQ0MzgiLCJyaCI6IkkiLCJzY3AiOiJ1c2VyX2ltcGVyc29uYXRpb24iLCJzdWIiOiJsM19yb0lTUVUyMjJiVUxTOXlpMmswWHBxcE9pTXo1SDNaQUNvMUdlWEEiLCJ0aWQiOiJmYTE1ZDY5Mi1lOWM3LTQ0NjAtYTc0My0yOWYyOTU2ZmQ0MjkiLCJ1bmlxdWVfbmFtZSI6ImFiZWxpQG1pY3Jvc29mdC5jb20iLCJ1dGkiOiJGVnNHeFlYSTMwLVR1aWt1dVVvRkFBIiwidmVyIjoiMS4wIn0.D3H6pMUtQnoJAGq6AHd

Wersja 2.0 dla aplikacji obsługujących konta konsumentów. Poniższy przykład przedstawia token w wersji 2.0 (ten przykład tokenu nie zostanie zweryfikowany, ponieważ klucze zostały obrócone przed publikacją i dane osobowe zostały usunięte):

eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSJ9.eyJhdWQiOiI2ZTc0MTcyYi1iZTU2LTQ4NDMtOWZmNC1lNjZhMzliYjEyZTMiLCJpc3MiOiJodHRwczovL2xvZ2luLm1pY3Jvc29mdG9ubGluZS5jb20vNzJmOTg4YmYtODZmMS00MWFmLTkxYWItMmQ3Y2QwMTFkYjQ3L3YyLjAiLCJpYXQiOjE1MzcyMzEwNDgsIm5iZiI6MTUzNzIzMTA0OCwiZXhwIjoxNTM3MjM0OTQ4LCJhaW8iOiJBWFFBaS84SUFBQUF0QWFaTG8zQ2hNaWY2S09udHRSQjdlQnE0L0RjY1F6amNKR3hQWXkvQzNqRGFOR3hYZDZ3TklJVkdSZ2hOUm53SjFsT2NBbk5aY2p2a295ckZ4Q3R0djMzMTQwUmlvT0ZKNGJDQ0dWdW9DYWcxdU9UVDIyMjIyZ0h3TFBZUS91Zjc5UVgrMEtJaWpkcm1wNjlSY3R6bVE9PSIsImF6cCI6IjZlNzQxNzJiLWJlNTYtNDg0My05ZmY0LWU2NmEzOWJiMTJlMyIsImF6cGFjciI6IjAiLCJuYW1lIjoiQWJlIExpbmNvbG4iLCJvaWQiOiI2OTAyMjJiZS1mZjFhLTRkNTYtYWJkMS03ZTRmN2QzOGU0NzQiLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJhYmVsaUBtaWNyb3NvZnQuY29tIiwicmgiOiJJIiwic2NwIjoiYWNjZXNzX2FzX3VzZXIiLCJzdWIiOiJIS1pwZmFIeVdhZGVPb3VZbGl0anJJLUtmZlRtMjIyWDVyclYzeERxZktRIiwidGlkIjoiNzJmOTg4YmYtODZmMS00MWFmLTkxYWItMmQ3Y2QwMTFkYjQ3IiwidXRpIjoiZnFpQnFYTFBqMGVRYTgyUy1JWUZBQSIsInZlciI6IjIuMCJ9.pj4N-w_3Us9DrBLfpCt

Wersję można ustawić dla aplikacji, podając odpowiednią wartość accessTokenAcceptedVersion dla ustawienia w manifeście aplikacji. Wartości null i 1 wynik w tokenach w wersji 1.0 oraz wartość 2 wyników w tokenach w wersji 2.0.

Własność tokenu

Dwie strony są zaangażowane w żądanie tokenu dostępu: klient, który żąda tokenu, oraz zasób (internetowy interfejs API), który akceptuje token. Oświadczenie aud w tokenie wskazuje zasób, dla którego jest przeznaczony token (jego odbiorcy). Klienci używają tokenu, ale nie powinni rozumieć ani próbować go przeanalizować. Zasoby akceptują token.

Platforma tożsamości Microsoft obsługuje wystawianie dowolnej wersji tokenu z dowolnego punktu końcowego wersji — nie są one powiązane. Gdy accessTokenAcceptedVersion jest ustawiona wartość 2, klient wywołujący punkt końcowy w wersji 1.0, aby uzyskać token dla tego zasobu, otrzymuje token dostępu w wersji 2.0.

Zasoby zawsze posiadają swoje tokeny przy użyciu aud oświadczenia i są jedynymi aplikacjami, które mogą zmieniać szczegóły tokenu.

Oświadczenia w tokenach dostępu

JWTs są podzielone na trzy elementy:

Nagłówek — zawiera informacje na temat weryfikowania tokenu, w tym informacji o typie tokenu i sposobie jego podpisania.
Payload — zawiera wszystkie ważne dane dotyczące użytkownika lub aplikacji, które próbują wywołać usługę.
Signature — czy surowiec używany do weryfikacji tokenu.

Każdy element jest oddzielony kropką (.) i oddzielnie zakodowaną w formacie Base64.

Oświadczenia są obecne tylko wtedy, gdy istnieje wartość, aby ją wypełnić. Aplikacja nie powinna mieć zależności od obecnego oświadczenia. Przykłady obejmują pwd_exp (nie każda dzierżawa wymaga wygaśnięcia haseł) i family_name (przepływy poświadczeń klienta są w imieniu aplikacji, które nie mają nazw). Oświadczenia używane do weryfikacji tokenu dostępu są zawsze obecne.

Niektóre oświadczenia są używane do ułatwienia Platforma tożsamości Microsoft zabezpieczania tokenów do ponownego użycia. Te oświadczenia są oznaczone jako nie do użytku publicznego w opisie jako Opaque. Te oświadczenia mogą lub nie mogą pojawić się w tokenie, a nowe mogą zostać dodane bez powiadomienia.

Oświadczenia nagłówkowe

Claim	Format	Opis
`typ`	Ciąg — zawsze `JWT`	Wskazuje, że token jest JWT.
`alg`	Ciąg	Wskazuje algorytm, który został użyty do podpisania tokenu, na przykład `RS256`.
`kid`	Ciąg	Określa odcisk palca klucza publicznego, którego można użyć do zweryfikowania tego podpisu tokenu. Emitowane zarówno w tokenach dostępu w wersji 1.0, jak i w wersji 2.0.
`x5t`	Ciąg	Funkcje takie same (w użyciu i wartości) co `kid`. `x5t` i jest starszym oświadczeniem emitowane tylko w tokenach dostępu w wersji 1.0 na potrzeby zgodności.

Oświadczenia ładunku

Claim	Format	Opis	Zagadnienia dotyczące autoryzacji
`aud`	Ciąg, identyfikator URI lub identyfikator GUID identyfikatora aplikacji	Identyfikuje zamierzonych odbiorców tokenu. W tokenach w wersji 2.0 ta wartość jest zawsze identyfikatorem klienta interfejsu API. W tokenach w wersji 1.0 może to być identyfikator klienta lub identyfikator URI zasobu używany w żądaniu. Wartość może zależeć od tego, jak klient zażądał tokenu.	Ta wartość musi zostać zweryfikowana, odrzuć token, jeśli wartość nie jest zgodna z zamierzonymi odbiorcami.
`iss`	Ciąg, identyfikator URI usługi tokenu zabezpieczającego (STS)	Identyfikuje usługę STS, która tworzy i zwraca token, oraz dzierżawę Azure AD, w której użytkownik został uwierzytelniony. Jeśli wystawiony token jest tokenem w wersji 2.0 (zobacz `ver` oświadczenie), identyfikator URI kończy się na `/v2.0`. Identyfikator GUID wskazujący, że użytkownik jest użytkownikiem użytkownika z konta Microsoft, to `9188040d-6c67-4c5b-b112-36a304b66dad`.	Aplikacja może użyć części identyfikatora GUID oświadczenia, aby ograniczyć zestaw dzierżaw, które mogą zalogować się do aplikacji, jeśli ma to zastosowanie.
`idp`	Ciąg, zwykle 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, takich jak goście. Jeśli oświadczenie nie jest obecne, można zamiast tego użyć wartości `iss` . W przypadku kont osobistych używanych w kontekście organizacyjnym (na przykład konto osobiste zaproszone do dzierżawy Azure AD) `idp` oświadczenie może być "live.com" lub identyfikator URI usługi STS zawierający dzierżawę `9188040d-6c67-4c5b-b112-36a304b66dad`konta Microsoft.
`iat`	int, sygnatura czasowa systemu Unix	Określa, kiedy wystąpiło uwierzytelnianie dla tego tokenu.
`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. Zasób może również odrzucić token przed tym razem. Odrzucenie może wystąpić, gdy wymagana jest zmiana uwierzytelniania lub wykryto odwołanie tokenu.
`aio`	Nieprzezroczystych ciągów	Wewnętrzne oświadczenie używane przez Azure AD do rejestrowania danych w celu ponownego użycia tokenu. Zasoby nie powinny używać tego oświadczenia.
`acr`	Ciąg, a `0` lub `1`, obecny tylko w tokenach w wersji 1.0	Wartość `0` oświadczenia "Klasa kontekstu uwierzytelniania" wskazuje, że uwierzytelnianie użytkownika końcowego nie spełnia wymagań ISO/IEC 29115.
`amr`	Tablica ciągów w formacie JSON, obecna tylko w tokenach w wersji 1.0	Określa sposób uwierzytelniania podmiotu tokenu.
`appid`	Ciąg, identyfikator GUID, obecny tylko w tokenach w wersji 1.0	Identyfikator aplikacji klienta przy użyciu tokenu. Aplikacja może działać jako sama lub w imieniu użytkownika. Identyfikator aplikacji zazwyczaj reprezentuje obiekt aplikacji, ale może również reprezentować obiekt jednostki usługi w Azure AD.	`appid` może być używany w decyzjach dotyczących autoryzacji.
`azp`	Ciąg, identyfikator GUID, obecny tylko w tokenach w wersji 2.0	Zamiana dla .`appid` Identyfikator aplikacji klienta przy użyciu tokenu. Aplikacja może działać jako sama lub w imieniu użytkownika. Identyfikator aplikacji zazwyczaj reprezentuje obiekt aplikacji, ale może również reprezentować obiekt jednostki usługi w Azure AD.	`azp` może być używany w decyzjach dotyczących autoryzacji.
`appidacr`	Ciąg, `0`, `1`lub `2`, obecny tylko w tokenach w wersji 1.0	Wskazuje sposób uwierzytelniania klienta. W przypadku klienta publicznego wartość to `0`. Jeśli używany jest identyfikator klienta i klucz tajny klienta, wartość to `1`. Jeśli certyfikat klienta został użyty do uwierzytelniania, wartość to `2`.
`azpacr`	Ciąg, `0`, `1`lub `2`, obecny tylko w tokenach w wersji 2.0	Zamiana dla .`appidacr` Wskazuje sposób uwierzytelniania klienta. W przypadku klienta publicznego wartość to `0`. Jeśli używany jest identyfikator klienta i klucz tajny klienta, wartość to `1`. Jeśli certyfikat klienta został użyty do uwierzytelniania, wartość to `2`.
`preferred_username`	Ciąg, obecny tylko w tokenach w wersji 2.0.	Podstawowa nazwa użytkownika reprezentująca użytkownika. Wartość może być adresem e-mail, numerem telefonu lub ogólną nazwą użytkownika bez określonego formatu. Wartość jest modyfikowalna i może ulec zmianie w czasie. Wartość może być jednak używana dla wskazówek dotyczących nazwy użytkownika i w interfejsie użytkownika czytelnym dla człowieka jako nazwa użytkownika. Zakres jest wymagany do otrzymania `profile` tego oświadczenia.	Ponieważ ta wartość jest modyfikowalna, nie może być używana do podejmowania decyzji dotyczących autoryzacji.
`name`	Ciąg	Udostępnia czytelną dla człowieka wartość, która identyfikuje temat tokenu. Nie ma gwarancji, że wartość jest unikatowa, jest modyfikowalna i jest używana tylko do celów wyświetlania. Zakres jest wymagany do otrzymania `profile` tego oświadczenia.	Ta wartość nie może być używana do podejmowania decyzji dotyczących autoryzacji.
`scp`	Ciąg, spacja rozdzielona listą zakresów	Zestaw zakresów uwidocznionych przez aplikację, dla której aplikacja kliencka zażądała (i otrzymała) zgody. Uwzględniane tylko w przypadku tokenów użytkownika.	Aplikacja powinna sprawdzić, czy te zakresy są prawidłowe uwidocznione przez aplikację, i podejmować decyzje dotyczące autoryzacji na podstawie wartości tych zakresów.
`roles`	Tablica ciągów, lista uprawnień	Zestaw uprawnień uwidocznionych przez aplikację, do którego żądający aplikacja lub użytkownik otrzymał uprawnienia do wywoływania. W przypadku tokenów aplikacji ten zestaw uprawnień jest używany podczas przepływu poświadczeń klienta zamiast zakresów użytkownika. W przypadku tokenów użytkownika ten zestaw wartości jest wypełniany rolami, do których użytkownik został przypisany w aplikacji docelowej.	Te wartości mogą służyć do zarządzania dostępem, takich jak wymuszanie autoryzacji w celu uzyskania dostępu do zasobu.
`wids`	Tablica identyfikatorów GUID roleTemplateID	Określa role dla całej dzierżawy przypisane do tego użytkownika z sekcji ról znajdujących się w Azure AD wbudowanych ról. To oświadczenie jest konfigurowane dla poszczególnych aplikacji za pośrednictwem `groupMembershipClaims` właściwości manifestu aplikacji. Ustawienie go na `All` wartość lub `DirectoryRole` jest wymagane. Może nie być obecny w tokenach uzyskanych za pośrednictwem niejawnego przepływu z powodu problemów z długością tokenu.	Te wartości mogą służyć do zarządzania dostępem, takich jak wymuszanie autoryzacji w celu uzyskania dostępu do zasobu.
`groups`	Tablica identyfikatorów GUID w formacie JSON	Udostępnia identyfikatory obiektów reprezentujące członkostwo w grupie podmiotu. Grupy zawarte w oświadczeniach grup są konfigurowane dla poszczególnych aplikacji za pośrednictwem `groupMembershipClaims` właściwości manifestu aplikacji. Wartość `null` wyklucza wszystkie grupy, wartość `SecurityGroup` obejmuje tylko członkostwo w grupach zabezpieczeń usługi Active Directory, a wartość `All` obejmuje zarówno grupy zabezpieczeń, jak i listy dystrybucyjne platformy Microsoft 365. Zobacz oświadczenie, `hasgroups` aby uzyskać szczegółowe informacje na temat używania `groups` oświadczenia z niejawną dotacją. W przypadku innych przepływów, jeśli liczba grup, w których znajduje się użytkownik, przekroczy 150 dla protokołu SAML i 200 dla JWT, Azure AD dodaje oświadczenie nadwyżkowe do źródeł oświadczeń. Źródła oświadczeń wskazują punkt końcowy usługi Microsoft Graph, który zawiera listę grup dla użytkownika.	Te wartości mogą służyć do zarządzania dostępem, takich jak wymuszanie autoryzacji w celu uzyskania dostępu do zasobu.
`hasgroups`	Wartość logiczna	Jeśli istnieje, zawsze `true`, wskazuje, czy użytkownik należy do co najmniej jednej grupy. Używane zamiast `groups` oświadczenia dla zestawów JWTs w przepływach niejawnych udzielania, jeśli pełne oświadczenie grup rozszerzy fragment identyfikatora URI poza limity długości adresu URL (obecnie sześć lub więcej grup). Wskazuje, że klient powinien używać interfejs Graph API firmy Microsoft do określania grup (`https://graph.microsoft.com/v1.0/users/{userID}/getMemberObjects`) użytkownika.
`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 dla 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" }`
`sub`	Ciąg	Podmiot zabezpieczeń, o którym token potwierdza informacje, takie jak użytkownik aplikacji. Ta wartość jest niezmienna i nie można jej ponownie przypisać ani ponownie użyć. Temat jest identyfikatorem parowania, który jest unikatowy dla określonego 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. W zależności od architektury i wymagań dotyczących prywatności mogą być wymagane dwie różne wartości. Zobacz również `oid` oświadczenie (które pozostaje takie same w aplikacjach w ramach dzierżawy).	Ta wartość może służyć do przeprowadzania kontroli autoryzacji, takich jak użycie tokenu w celu uzyskania dostępu do zasobu i może służyć jako klucz w tabelach bazy danych.
`oid`	Ciąg, identyfikator GUID	Niezmienny identyfikator osoby żądającej, który jest użytkownikiem lub jednostką usługi, której tożsamość została zweryfikowana. Ten identyfikator jednoznacznie identyfikuje osoby żądającej w aplikacjach. Dwie różne aplikacje logując się w tym samym użytkowniku otrzymują tę samą wartość w oświadczeniu `oid` . Można `oid` go użyć podczas wykonywania zapytań w usłudze Microsoft Usługi online, takich jak Microsoft Graph. Program Microsoft Graph zwraca ten identyfikator jako `id` właściwość dla danego konta użytkownika. Ponieważ umożliwia `oid` wielu aplikacjom korelowanie podmiotów zabezpieczeń, `profile` zakres jest wymagany w celu otrzymania tego oświadczenia dla użytkowników. Jeśli jeden użytkownik istnieje w wielu dzierżawach, użytkownik zawiera inny identyfikator obiektu w każdej dzierżawie. Konta są uznawane za inne, mimo że użytkownik loguje się do każdego konta przy użyciu tych samych poświadczeń.	Ta wartość może służyć do przeprowadzania kontroli autoryzacji, takich jak użycie tokenu w celu uzyskania dostępu do zasobu i może służyć jako klucz w tabelach bazy danych.
`tid`	Ciąg, identyfikator GUID	Reprezentuje dzierżawę, do którego loguje się użytkownik. W przypadku kont służbowych identyfikator GUID jest niezmiennym identyfikatorem dzierżawy organizacji, do którego 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`. Aby otrzymać to oświadczenie, aplikacja musi zażądać `profile` zakresu.	Ta wartość powinna być uwzględniana w połączeniu z innymi oświadczeniami w decyzjach dotyczących autoryzacji.
`unique_name`	Ciąg, obecny tylko w tokenach w wersji 1.0	Udostępnia zrozumiałą wartość identyfikującą podmiot tokenu.	Ta wartość nie jest gwarantowana jako unikatowa w ramach dzierżawy i powinna być używana tylko do celów wyświetlania.
`uti`	Ciąg	Oświadczenie identyfikatora tokenu, równoważne `jti` w specyfikacji JWT. Unikatowy identyfikator tokenu uwzględniający wielkość liter.
`rh`	Nieprzezroczystych ciągów	Oświadczenie wewnętrzne używane przez platformę Azure do ponownego określania tokenów. Zasoby nie powinny używać tego oświadczenia.
`ver`	Ciąg lub `1.02.0`	Wskazuje wersję tokenu dostępu.

Oświadczenie nadwyżkowe grup

Azure AD ogranicza liczbę identyfikatorów obiektów uwzględnionych w oświadczeniach grup, aby pozostać w limicie rozmiaru nagłówka HTTP. 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 i tylko 6 w przypadku wystawienia przy użyciu przepływu niejawnego), Azure AD nie emituje oświadczenia grup w tokenie. Zamiast tego zawiera oświadczenie nadwyżkowe w tokenie, który wskazuje aplikacji, aby wysłać zapytanie do firmy Microsoft interfejs Graph API 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]"
        }   
    }
    ...
}

Użyj podanego BulkCreateGroups.ps1 w folderze Skrypty tworzenia aplikacji , aby ułatwić testowanie scenariuszy nadwyżkowych.

Podstawowe oświadczenia w wersji 1.0

Następujące oświadczenia są uwzględniane w tokenach w wersji 1.0, jeśli ma to zastosowanie, ale nie są domyślnie uwzględniane w tokenach w wersji 2.0. Aby użyć tych oświadczeń dla wersji 2.0, aplikacja żąda ich przy użyciu opcjonalnych oświadczeń.

Claim	Format	Opis
`ipaddr`	Ciąg	Adres IP uwierzytelniony przez użytkownika.
`onprem_sid`	Ciąg w formacie SID	W przypadkach, gdy użytkownik ma uwierzytelnianie lokalne, to oświadczenie udostępnia swój identyfikator SID. Użyj tego oświadczenia do autoryzacji w starszych aplikacjach.
`pwd_exp`	int, sygnatura czasowa systemu Unix	Wskazuje, kiedy wygasa hasło użytkownika.
`pwd_url`	Ciąg	Adres URL, pod którym użytkownicy mogą być wysyłani w celu zresetowania hasła.
`in_corp`	boolean	Sygnały, czy klient loguje się z sieci firmowej. Jeśli tak nie jest, oświadczenie nie zostanie uwzględnione.
`nickname`	Ciąg	Inna nazwa użytkownika, oddzielona od imienia lub nazwiska.
`family_name`	Ciąg	Podaje nazwisko, nazwisko lub nazwę rodziny użytkownika zgodnie z definicją w obiekcie użytkownika.
`given_name`	Ciąg	Podaje pierwszą lub podaną nazwę użytkownika ustawioną na obiekcie użytkownika.
`upn`	Ciąg	Nazwa użytkownika. Może to być numer telefonu, adres e-mail lub niesformatowany ciąg. Należy używać tylko do celów wyświetlania i podawania wskazówek dotyczących nazwy użytkownika w scenariuszach ponownego uwierzytelniania.

oświadczenie amr

Tożsamości mogą być uwierzytelniane na różne sposoby, co może być istotne dla aplikacji. Oświadczenie amr jest tablicą, która może zawierać wiele elementów, takich jak , na potrzeby uwierzytelniania, które używało zarówno hasła, jak ["mfa", "rsa", "pwd"]i aplikacji Authenticator.

Wartość	Opis
`pwd`	Uwierzytelnianie hasłem — hasłem firmy Microsoft użytkownika lub wpisem tajnym klienta aplikacji.
`rsa`	Uwierzytelnianie zostało oparte na weryfikacji klucza RSA, na przykład w aplikacji Microsoft Authenticator. Ta wartość wskazuje również, czy uwierzytelnianie zostało wykonane przez JWT z podpisem własnym z certyfikatem X509 należącym do usługi.
`otp`	Jednorazowy kod dostępu przy użyciu wiadomości e-mail lub wiadomości SMS.
`fed`	Użyto asercji uwierzytelniania federacyjnego (na przykład JWT lub SAML).
`wia`	Zintegrowane uwierzytelnianie systemu Windows
`mfa`	Użyto uwierzytelniania wieloskładnikowego. Gdy to oświadczenie jest obecne, są uwzględniane inne metody uwierzytelniania.
`ngcmfa`	`mfa`Odpowiednik , używany do aprowizacji niektórych zaawansowanych typów poświadczeń.
`wiaormfa`	Użytkownik użył systemu Windows lub poświadczeń uwierzytelniania wieloskładnikowego do uwierzytelnienia.
`none`	Nie wykonano uwierzytelniania.

Okres istnienia tokenu dostępu

Domyślny okres istnienia tokenu dostępu to zmienna. Po wystawieniu domyślny okres istnienia tokenu dostępu ma przypisaną wartość losową z zakresu od 60 do 90 minut (średnio 75 minut). Odmiana zwiększa odporność usługi przez rozłożenie zapotrzebowania na tokeny dostępu w czasie, co uniemożliwia godzinowe wzrosty ruchu do Azure AD.

Dzierżawy, które nie korzystają z dostępu warunkowego, mają domyślny okres istnienia tokenu dostępu na dwie godziny dla klientów, takich jak Microsoft Teams i Microsoft 365.

Okres istnienia tokenu dostępu można dostosować w celu kontrolowania, jak często aplikacja kliencka wygasa sesji aplikacji i jak często wymaga ponownego uwierzytelnienia użytkownika (w trybie dyskretnym lub interaktywnym). Aby zastąpić domyślną odmianę okresu istnienia tokenu dostępu, ustaw statyczny domyślny okres istnienia tokenu dostępu przy użyciu konfigurowalnego okresu istnienia tokenu (CTL).

Domyślna odmiana okresu istnienia tokenu jest stosowana do organizacji z włączoną ciągłą oceną dostępu (CAE). Domyślna odmiana okresu istnienia tokenu jest stosowana nawet wtedy, gdy organizacje używają zasad CTL. Domyślny okres istnienia tokenu dla długotrwałego okresu istnienia tokenu waha się od 20 do 28 godzin. Po wygaśnięciu tokenu dostępu klient musi użyć tokenu odświeżania w trybie dyskretnym, aby uzyskać nowy token odświeżania i token dostępu.

Organizacje korzystające z częstotliwości logowania dostępu warunkowego (SIF), aby wymusić, jak często występują logowania, nie mogą zastąpić domyślnej odmiany okresu istnienia tokenu dostępu. Gdy organizacje używają programu SIF, czas między monitami o poświadczenia dla klienta to okres istnienia tokenu z zakresu od 60 do 90 minut oraz interwał częstotliwości logowania.

Oto przykład działania domyślnej odmiany okresu istnienia tokenu z częstotliwością logowania. Załóżmy, że organizacja ustawia częstotliwość logowania co godzinę. Rzeczywisty interwał logowania występuje w dowolnym miejscu od 1 godziny do 2,5 godziny, ponieważ token jest wystawiany z okresem istnienia od 60 do 90 minut (ze względu na odmianę okresu istnienia tokenu).

Jeśli użytkownik z tokenem z okresem istnienia jednej godziny wykonuje logowanie interakcyjne o wartości 59 minut (tuż przed przekroczeniem częstotliwości logowania), nie ma monitu o podanie poświadczeń, ponieważ logowanie jest poniżej progu SIF. Jeśli nowy token zostanie wystawiony z okresem istnienia 90 minut, użytkownik nie zobaczy monitu o podanie poświadczeń przez kolejną godzinę i pół. Po podjęciu próby cichego odnowienia 90-minutowego okresu istnienia tokenu Azure AD wymaga monitu o podanie poświadczeń, ponieważ łączna długość sesji przekroczyła ustawienie częstotliwości logowania wynoszącym 1 godzinę. W tym przykładzie różnica czasu między monitami poświadczeń ze względu na interwał SIF i odmianę okresu istnienia tokenu wynosi 2,5 godziny.

Weryfikowanie tokenów

Nie wszystkie aplikacje powinny weryfikować tokeny. Tylko w określonych scenariuszach aplikacje powinny weryfikować token:

Internetowe interfejsy API muszą weryfikować tokeny dostępu wysyłane do nich przez klienta. Muszą akceptować tylko tokeny zawierające swoje aud oświadczenie.
Poufne aplikacje internetowe, takie jak ASP.NET Core, muszą weryfikować wysyłane do nich tokeny identyfikatorów przy użyciu przeglądarki użytkownika w przepływie hybrydowym, zanim zezwolić na dostęp do danych użytkownika lub ustanowić sesję.

Jeśli żaden z powyższych scenariuszy nie ma zastosowania, aplikacja nie skorzysta z weryfikacji tokenu i może stanowić zagrożenie bezpieczeństwa i niezawodności, jeśli decyzje zostaną podjęte na podstawie ważności tokenu. Klienci publiczni, tacy jak aplikacje natywne lub jednostronicowe, nie korzystają z weryfikacji tokenów, ponieważ aplikacja komunikuje się bezpośrednio z dostawcą tożsamości, gdzie ochrona SSL gwarantuje, że tokeny są prawidłowe.

Interfejsy API i aplikacje internetowe muszą weryfikować tylko tokeny, które mają aud oświadczenie zgodne z aplikacją. Inne zasoby mogą mieć niestandardowe reguły weryfikacji tokenu. Na przykład tokeny dla programu Microsoft Graph nie będą weryfikowane zgodnie z tymi regułami ze względu na ich zastrzeżony format. Weryfikowanie i akceptowanie tokenów przeznaczonych dla innego zasobu jest przykładem zdezorientowanego problemu zastępcy .

Jeśli aplikacja musi zweryfikować token identyfikatora lub token dostępu, najpierw należy zweryfikować podpis tokenu i wystawcę względem wartości w dokumencie odnajdywania OpenID. Na przykład niezależna od dzierżawy wersja dokumentu znajduje się w lokalizacji https://login.microsoftonline.com/common/.well-known/openid-configuration.

Oprogramowanie pośredniczące Azure AD ma wbudowane funkcje sprawdzania poprawności tokenów dostępu. Zobacz przykłady, aby znaleźć je w odpowiednim języku. Istnieje również kilka bibliotek typu open source innych firm dostępnych do weryfikacji JWT. Aby uzyskać więcej informacji na temat bibliotek uwierzytelniania Azure AD i przykładów kodu, zobacz biblioteki uwierzytelniania.

Weryfikowanie podpisu

Zestaw JWT zawiera trzy segmenty, które są oddzielone znakiem . . Pierwszy segment jest znany jako nagłówek, drugi jako treść, a trzeci jako podpis. Segment podpisu może służyć do weryfikowania autentyczności tokenu, aby mógł być zaufany przez aplikację.

Tokeny wystawione przez Azure AD są podpisane przy użyciu standardowych w branży algorytmów szyfrowania asymetrycznego, takich jak RS256. Nagłówek JWT zawiera informacje o kluczu i metodzie szyfrowania używanej do podpisywania tokenu:

{
  "typ": "JWT",
  "alg": "RS256",
  "x5t": "iBjL1Rcqzhiy4fpxIxdZqohM2Yk",
  "kid": "iBjL1Rcqzhiy4fpxIxdZqohM2Yk"
}

Oświadczenie alg wskazuje algorytm, który został użyty do podpisania tokenu, podczas gdy kid oświadczenie wskazuje konkretny klucz publiczny, który został użyty do weryfikacji tokenu.

W dowolnym momencie Azure AD mogą podpisać token identyfikatora przy użyciu dowolnego z określonych zestawów par kluczy publicznych-prywatnych. Azure AD obraca możliwy zestaw kluczy w regularnych okresach, więc aplikacja powinna być zapisywana w celu automatycznego obsługi tych kluczowych zmian. Rozsądną częstotliwością sprawdzania dostępności aktualizacji kluczy publicznych używanych przez Azure AD jest co 24 godziny.

Uzyskaj dane klucza podpisywania niezbędne do zweryfikowania podpisu przy użyciu dokumentu metadanych OpenID Connect znajdującego się w:

https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration

Porada

Spróbuj wykonać tę próbę w przeglądarce: adres URL

Poniższe informacje opisują dokument metadanych:

Jest obiektem JSON zawierającym kilka przydatnych informacji, takich jak lokalizacja różnych punktów końcowych wymaganych do uwierzytelniania openID Connect.
Zawiera element , który daje lokalizację jwks_urizestawu kluczy publicznych odpowiadających kluczom prywatnym używanym do podpisywania tokenów. Klucz internetowy JSON (JWK) znajdujący się w obiekcie zawiera wszystkie informacje o kluczu jwks_uri publicznym używane w tym konkretnym momencie w czasie. Format JWK został opisany w artykule RFC 7517. Aplikacja może użyć kid oświadczenia w nagłówku JWT, aby wybrać klucz publiczny, z tego dokumentu, który odpowiada kluczowi prywatnemu, który został użyty do podpisania określonego tokenu. Następnie może przeprowadzić walidację podpisu przy użyciu poprawnego klucza publicznego i wskazanego algorytmu.

Uwaga

kid Użyj oświadczenia, aby zweryfikować token. Chociaż tokeny w wersji 1.0 zawierają zarówno x5t oświadczenia, jak i kid , tokeny w wersji 2.0 zawierają tylko kid oświadczenie.

Sprawdzanie poprawności podpisu wykracza poza zakres tego dokumentu. Istnieje wiele bibliotek typu open source, które ułatwiają weryfikację podpisu w razie potrzeby. Jednak Platforma tożsamości Microsoft ma jedno rozszerzenie podpisywania tokenu do standardów, które są niestandardowymi kluczami podpisywania.

Jeśli aplikacja ma niestandardowe klucze podpisywania w wyniku korzystania z funkcji mapowania oświadczeń , dołącz appid parametr zapytania zawierający identyfikator aplikacji, aby uzyskać jwks_uri informacje o kluczu podpisywania aplikacji, który powinien być używany do walidacji. Na przykład: https://login.microsoftonline.com/{tenant}/.well-known/openid-configuration?appid=6731de76-14a6-49ae-97bc-6eba6914391e zawiera element jwks_uri .https://login.microsoftonline.com/{tenant}/discovery/keys?appid=6731de76-14a6-49ae-97bc-6eba6914391e

Autoryzacja oparta na oświadczeniach

Logika biznesowa aplikacji określa sposób obsługi autoryzacji. Ogólne podejście do autoryzacji oparte na oświadczeniach tokenu i które oświadczenia powinny być używane, jest opisane poniżej.

Po zweryfikowaniu tokenu z poprawnym aud oświadczeniem dzierżawa tokenu, podmiot, aktor musi być autoryzowany.

Dzierżawa

Najpierw należy zawsze sprawdzić, czy element tid w tokenie jest zgodny z identyfikatorem dzierżawy używanym do przechowywania danych z aplikacją. Gdy informacje są przechowywane dla aplikacji w kontekście dzierżawy, powinny być ponownie dostępne tylko w dalszej części tej samej dzierżawy. Nigdy nie zezwalaj na dostęp do danych w jednej dzierżawie z innej dzierżawy.

Temat

Następnie, aby ustalić, czy podmiot tokenu, taki jak użytkownik (lub sama aplikacja w przypadku tokenu tylko dla aplikacji), jest autoryzowany, sprawdza, czy dany suboid podmiot należy do odpowiedniej roli lub grupy z oświadczeniami roles, groupswids oświadczenia.

Na przykład użyj niezmiennych wartości tid oświadczeń i oid jako klucza połączonego dla danych aplikacji i określ, czy użytkownik powinien udzielić dostępu.

groups Oświadczenia roleslub wids można również użyć do określenia, czy podmiot ma autoryzację do wykonania operacji. Na przykład administrator może mieć uprawnienia do zapisu w interfejsie API, ale nie normalnego użytkownika lub użytkownik może znajdować się w grupie, która może wykonać jakąś akcję.

Ostrzeżenie

Nigdy nie używaj email wartości 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ą ulec zmianie w czasie, co czyni je niezabezpieczonymi i niewiarygodnymi do autoryzacji.

Aktor

Na koniec, gdy aplikacja działa dla użytkownika, ta aplikacja kliencka (aktor) musi być również autoryzowana. scp Użyj oświadczenia (zakresu), aby sprawdzić, czy aplikacja ma uprawnienia do wykonania operacji.

Zakresy są definiowane przez aplikację, a brak scp oświadczenia oznacza uprawnienia pełnego aktora.

Uwaga

Aplikacja może obsługiwać tokeny tylko dla aplikacji (żądania z aplikacji bez użytkowników, takich jak aplikacje demona) i chcieć autoryzować określoną aplikację w wielu dzierżawach, a nie pojedyncze identyfikatory jednostki usługi. W takim przypadku sprawdź token tylko dla aplikacji przy użyciu opcjonalnego idtyp oświadczenia i użyj appid oświadczenia (dla tokenów w wersji 1.0) lub azp oświadczenia (dla tokenów w wersji 2.0) wraz z tid , aby określić autoryzację na podstawie dzierżawy i identyfikatora aplikacji.

Odwołanie tokenu

Tokeny odświeżania można unieważnić lub odwołać w dowolnym momencie z różnych powodów. Przyczyny należą do kategorii limitów czasu i odwołań.

Limity czasu tokenu

Gdy organizacja używa konfiguracji okresu istnienia tokenu, można zmienić okres istnienia tokenów odświeżania. Oczekuje się, że niektóre tokeny mogą być używane bez użycia. Na przykład użytkownik nie otwiera aplikacji przez trzy miesiące, a następnie wygasa token. Aplikacje mogą napotkać scenariusze, w których serwer logowania odrzuca token odświeżania ze względu na jego wiek.

MaxInactiveTime: jeśli token odświeżania nie został użyty w czasie dyktowanym przez maxInactiveTime, token odświeżania nie jest już prawidłowy.
MaxSessionAge: Jeśli parametr MaxAgeSessionMultiFactor lub MaxAgeSessionSingleFactor został ustawiony na inny niż domyślny (do odwołania), po upływie czasu ustawionego w maxAgeSession* jest wymagane ponowne uwierzytelnienie. Przykłady:
- Dzierżawa ma wartość MaxInactiveTime w ciągu pięciu dni, a użytkownik udał się na wakacje przez tydzień, więc Azure AD nie widział nowego żądania tokenu od użytkownika w ciągu siedmiu dni. Następnym razem, gdy użytkownik zażąda nowego tokenu, zostanie odwołany token odświeżania i musi ponownie wprowadzić swoje poświadczenia.
- Aplikacja wrażliwa ma wartość MaxAgeSessionSingleFactor jednego dnia. Jeśli użytkownik loguje się w poniedziałek, a we wtorek (po upływie 25 godzin), będzie musiał ponownie uwierzytelnić.

Odwołania tokenów

Tokeny odświeżania można odwołać przez serwer ze względu na zmianę poświadczeń lub akcję administracyjną. Tokeny odświeżania znajdują się w klasach poufnych klientów i klientów publicznych.

Zmiana	Plik cookie oparty na hasłach	Token oparty na hasłach	Plik cookie nie oparty na hasłach	Token nie oparty na hasłach	Poufny token klienta
Hasło wygasa	Pozostaje przy życiu	Pozostaje przy życiu	Pozostaje przy życiu	Pozostaje przy życiu	Pozostaje przy życiu
Hasło zmienione przez użytkownika	Revoked	Revoked	Pozostaje przy życiu	Pozostaje przy życiu	Pozostaje przy życiu
Użytkownik wykonuje samoobsługowe resetowanie hasła	Revoked	Revoked	Pozostaje przy życiu	Pozostaje przy życiu	Pozostaje przy życiu
Administracja resetuje hasło	Revoked	Revoked	Pozostaje przy życiu	Pozostaje przy życiu	Pozostaje przy życiu
Użytkownik odwołuje swoje tokeny odświeżania przy użyciu programu PowerShell	Revoked	Revoked	Revoked	Revoked	Revoked
Administracja odwołuje wszystkie tokeny odświeżania dla użytkownika przy użyciu programu PowerShell	Revoked	Revoked	Revoked	Revoked	Revoked
Logowanie jednokrotne w internecie	Revoked	Pozostaje przy życiu	Revoked	Pozostaje przy życiu	Pozostaje przy życiu

Nienależące do hasła

Logowanie nie oparte na hasłach jest jednym, w którym użytkownik nie wpisał hasła, aby go pobrać. Przykłady logowania nie opartego na hasłach obejmują:

Używanie twarzy z Windows Hello
Klucz FIDO2
SMS
Połączenia głosowe
Kod PIN

Aby uzyskać więcej informacji, zobacz Podstawowe tokeny odświeżania.

Następne kroki

Dowiedz się więcej id_tokens w Azure AD.
Dowiedz się więcej o uprawnieniach i zgody.

Tokeny dostępu na platformie tożsamości firmy Microsoft

Formaty tokenów

Własność tokenu

Oświadczenia w tokenach dostępu

Oświadczenia nagłówkowe

Oświadczenia ładunku

Oświadczenie nadwyżkowe grup

Podstawowe oświadczenia w wersji 1.0

oświadczenie amr

Okres istnienia tokenu dostępu

Weryfikowanie tokenów

Weryfikowanie podpisu

Autoryzacja oparta na oświadczeniach

Dzierżawa

Temat

Aktor

Odwołanie tokenu

Limity czasu tokenu

Odwołania tokenów

Nienależące do hasła

Następne kroki

Dodatkowe zasoby

Dodatkowe zasoby