Tokeny dostępu platformy tożsamości firmy MicrosoftMicrosoft identity platform access tokens

Tokeny dostępu umożliwiają klientom bezpieczne wywoływanie chronionych interfejsów API sieci Web, które są używane przez interfejsy API sieci Web do uwierzytelniania i autoryzacji.Access tokens enable clients to securely call protected web APIs, and are used by web APIs to perform authentication and authorization. W przypadku specyfikacji OAuth tokeny dostępu są nieprzezroczystymi ciągami bez formatu zestawu — niektórzy dostawcy tożsamości (dostawców tożsamości) używają identyfikatorów GUID, a inne używają szyfrowanych obiektów BLOB.Per the OAuth specification, access tokens are opaque strings without a set format - some identity providers (IDPs) use GUIDs, others use encrypted blobs. Platforma tożsamości firmy Microsoft korzysta z różnych formatów tokenów dostępu w zależności od konfiguracji interfejsu API, który akceptuje token.The Microsoft identity platform uses a variety of access token formats depending on the configuration of the API that accepts the token. Niestandardowe interfejsy API zarejestrowane przez deweloperów na platformie tożsamości firmy Microsoft mogą wybierać spośród dwóch różnych formatów tokenów sieci Web JSON (JWTs) o nazwie "v1" i "v2", a interfejsy API opracowane przez firmę Microsoft, takie jak Microsoft Graph lub interfejsy API na platformie Azure, mają dodatkowe formaty tokenów własnych.Custom APIs registered by developers on the Microsoft identity platform can choose from two different formats of JSON Web Tokens (JWTs), called "v1" and "v2", and Microsoft-developed APIs like Microsoft Graph or APIs in Azure have additional proprietary token formats. Te formaty zastrzeżone mogą być zaszyfrowane tokeny, JWTs lub specjalne tokeny podobne do JWT, które nie będą weryfikowane.These proprietary formats might be encrypted tokens, JWTs, or special JWT-like tokens that will not validate.

Klienci muszą traktować tokeny dostępu jako ciągi nieprzezroczyste, ponieważ zawartość tokenu jest przeznaczona tylko dla zasobu (API).Clients must treat access tokens as opaque strings because the contents of the token are intended for the resource (the API) only. Tylko do celów związanych z walidacją i debugowaniem deweloperzy mogą zdekodować JWTs za pomocą witryny, takiej jak JWT.MS.For validation and debugging purposes only, developers can decode JWTs using a site like jwt.ms. Należy jednak pamiętać, że tokeny otrzymane dla interfejsu API firmy Microsoft mogą nie zawsze być JWT i nie można ich dekodować.Be aware, however, that the tokens you receive for a Microsoft API might not always be a JWT, and that you can't always decode them.

Aby uzyskać szczegółowe informacje o tym, co znajduje się w tokenie dostępu, klienci powinni używać danych odpowiedzi o tokenach, które są zwracane z tokenem dostępu do klienta.For details on what's inside the access token, clients should use the token response data that's returned with the access token to your client. Gdy klient zażąda tokenu dostępu, platforma tożsamości firmy Microsoft zwróci również metadane dotyczące tokenu dostępu dla użycia aplikacji.When your client requests an access token, the Microsoft identity platform also returns some metadata about the access token for your app's consumption. Te informacje obejmują czas wygaśnięcia tokenu dostępu i zakresy, dla których jest on prawidłowy.This information includes the expiry time of the access token and the scopes for which it's valid. Te dane umożliwiają aplikacji inteligentne buforowanie tokenów dostępu bez konieczności analizowania samego tokenu dostępu.This data allows your app to do intelligent caching of access tokens without having to parse the access token itself.

Zapoznaj się z następującymi sekcjami, aby dowiedzieć się, jak interfejs API może sprawdzać poprawność oświadczeń i używać ich w ramach tokenu dostępuSee the following sections to learn how your API can validate and use the claims inside an access token.

Uwaga

Wszystkie dokumenty na tej stronie, z wyjątkiem sytuacji, gdy zaznaczono inaczej, mają zastosowanie tylko do tokenów wystawionych dla zarejestrowanych interfejsów API.All documentation on this page, except where noted, applies only to tokens issued for APIs you've registered. Nie ma zastosowania do tokenów wystawionych dla interfejsów API firmy Microsoft, a tokeny te nie mogą być używane do sprawdzania, jak platforma tożsamości firmy Microsoft będzie wystawiała tokeny dla tworzonego interfejsu API.It does not apply to tokens issued for Microsoft-owned APIs, nor can those tokens be used to validate how the Microsoft identity platform will issue tokens for an API you create.

Formaty i własności tokenuToken formats and ownership

Wersja 1.0 i wersja 2.0v1.0 and v2.0

Istnieją dwie wersje tokenów dostępu dostępne na platformie tożsamości firmy Microsoft: v 1.0 i 2.0.There are two versions of access tokens available in the Microsoft identity platform: v1.0 and v2.0. Te wersje określają, jakie oświadczenia znajdują się w tokenie, dzięki czemu interfejs API sieci Web może kontrolować, jak wyglądają ich tokeny.These versions govern what claims are in the token, ensuring that a web API can control what their tokens look like. Interfejsy API sieci Web mają jedną z wybranych jako domyślne podczas rejestracji w wersji 1.0 dla aplikacji obsługujących usługę Azure AD i 2.0 dla aplikacji, które obsługują konta klientów.Web APIs have one of these selected as a default during registration - v1.0 for Azure AD-only apps, and v2.0 for apps that support consumer accounts. Jest to kontrolowane przez aplikacje korzystające z accessTokenAcceptedVersion Ustawienia w manifeście aplikacji, gdzie null i 1 wynik w tokenach v 1.0, a 2 wyniki w tokenach v 2.0.This is controllable by applications using the accessTokenAcceptedVersion setting in the app manifest, where null and 1 result in v1.0 tokens, and 2 results in v2.0 tokens.

Jakiej aplikacji jest token "for"?What app is a token "for"?

Żądanie tokenu dostępu obejmuje dwie strony: klient, który żąda tokenu oraz zasób (interfejs API) akceptujący token, gdy wywoływany jest interfejs API.There are two parties involved in an access token request: the client, who requests the token, and the resource (the API) that accepts the token when the API is called. audW tokenie wskazuje zasób, dla którego jest przeznaczony token (jego odbiorcy).The aud claim in a token indicates the resource the token is intended for (its audience). Klienci używają tokenu, ale nie powinni zrozumieć ani próbować go przeanalizować.Clients use the token but should not understand or attempt to parse it. Zasoby akceptują token.Resources accept the token.

Platforma tożsamości firmy Microsoft obsługuje wystawianie dowolnej wersji tokenu z poziomu punktu końcowego wersji — nie są one powiązane.The Microsoft identity platform supports issuing any token version from any version endpoint - they are not related. Dlatego ustawienie zasobu accessTokenAcceptedVersion 2 oznacza, że klient wywołujący punkt końcowy v 1.0 do uzyskania tokenu dla tego interfejsu API otrzyma token dostępu w wersji 2.0.This is why a resource setting accessTokenAcceptedVersion to 2 means that a client calling the v1.0 endpoint to get a token for that API will receive a v2.0 access token. Zasoby zawsze są właścicielami swoich tokenów (z ich aud wnioskiem) i są jedynymi aplikacjami, które mogą zmieniać swoje szczegóły tokenu.Resources always own their tokens (those with their aud claim) and are the only applications that can change their token details. Z tego powodu zmiana opcjonalnych oświadczeń tokenu dostępu dla klienta nie powoduje zmiany tokenu dostępu otrzymanego, gdy wymagany jest token dla user.read , który należy do zasobu Microsoft Graph.This is why changing the access token optional claims for your client does not change the access token received when a token is requested for user.read, which is owned by the Microsoft Graph resource.

Przykładowe tokenySample tokens

tokeny 1.0 i v 2.0 wyglądają podobnie i zawierają wiele z tych samych oświadczeń.v1.0 and v2.0 tokens look similar and contain many of the same claims. Przykładem każdego z nich jest tutaj.An example of each is provided here. Te przykładowe tokeny nie będą zweryfikowane, jednak ponieważ klucze zostały obrócone przed publikacją i dane osobowe zostały z nich usunięte.These example tokens will not validate, however, as the keys have rotated prior to publication and personal information has been removed from them.

Wersja 1.0v1.0

eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSIsImtpZCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSJ9.eyJhdWQiOiJlZjFkYTlkNC1mZjc3LTRjM2UtYTAwNS04NDBjM2Y4MzA3NDUiLCJpc3MiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC9mYTE1ZDY5Mi1lOWM3LTQ0NjAtYTc0My0yOWYyOTUyMjIyOS8iLCJpYXQiOjE1MzcyMzMxMDYsIm5iZiI6MTUzNzIzMzEwNiwiZXhwIjoxNTM3MjM3MDA2LCJhY3IiOiIxIiwiYWlvIjoiQVhRQWkvOElBQUFBRm0rRS9RVEcrZ0ZuVnhMaldkdzhLKzYxQUdyU091TU1GNmViYU1qN1hPM0libUQzZkdtck95RCtOdlp5R24yVmFUL2tES1h3NE1JaHJnR1ZxNkJuOHdMWG9UMUxrSVorRnpRVmtKUFBMUU9WNEtjWHFTbENWUERTL0RpQ0RnRTIyMlRJbU12V05hRU1hVU9Uc0lHdlRRPT0iLCJhbXIiOlsid2lhIl0sImFwcGlkIjoiNzVkYmU3N2YtMTBhMy00ZTU5LTg1ZmQtOGMxMjc1NDRmMTdjIiwiYXBwaWRhY3IiOiIwIiwiZW1haWwiOiJBYmVMaUBtaWNyb3NvZnQuY29tIiwiZmFtaWx5X25hbWUiOiJMaW5jb2xuIiwiZ2l2ZW5fbmFtZSI6IkFiZSAoTVNGVCkiLCJpZHAiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC83MmY5ODhiZi04NmYxLTQxYWYtOTFhYi0yZDdjZDAxMjIyNDcvIiwiaXBhZGRyIjoiMjIyLjIyMi4yMjIuMjIiLCJuYW1lIjoiYWJlbGkiLCJvaWQiOiIwMjIyM2I2Yi1hYTFkLTQyZDQtOWVjMC0xYjJiYjkxOTQ0MzgiLCJyaCI6IkkiLCJzY3AiOiJ1c2VyX2ltcGVyc29uYXRpb24iLCJzdWIiOiJsM19yb0lTUVUyMjJiVUxTOXlpMmswWHBxcE9pTXo1SDNaQUNvMUdlWEEiLCJ0aWQiOiJmYTE1ZDY5Mi1lOWM3LTQ0NjAtYTc0My0yOWYyOTU2ZmQ0MjkiLCJ1bmlxdWVfbmFtZSI6ImFiZWxpQG1pY3Jvc29mdC5jb20iLCJ1dGkiOiJGVnNHeFlYSTMwLVR1aWt1dVVvRkFBIiwidmVyIjoiMS4wIn0.D3H6pMUtQnoJAGq6AHd

Wyświetl ten token v 1.0 w JWT.MS.View this v1.0 token in JWT.ms.

Wersja 2.0v2.0

eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSJ9.eyJhdWQiOiI2ZTc0MTcyYi1iZTU2LTQ4NDMtOWZmNC1lNjZhMzliYjEyZTMiLCJpc3MiOiJodHRwczovL2xvZ2luLm1pY3Jvc29mdG9ubGluZS5jb20vNzJmOTg4YmYtODZmMS00MWFmLTkxYWItMmQ3Y2QwMTFkYjQ3L3YyLjAiLCJpYXQiOjE1MzcyMzEwNDgsIm5iZiI6MTUzNzIzMTA0OCwiZXhwIjoxNTM3MjM0OTQ4LCJhaW8iOiJBWFFBaS84SUFBQUF0QWFaTG8zQ2hNaWY2S09udHRSQjdlQnE0L0RjY1F6amNKR3hQWXkvQzNqRGFOR3hYZDZ3TklJVkdSZ2hOUm53SjFsT2NBbk5aY2p2a295ckZ4Q3R0djMzMTQwUmlvT0ZKNGJDQ0dWdW9DYWcxdU9UVDIyMjIyZ0h3TFBZUS91Zjc5UVgrMEtJaWpkcm1wNjlSY3R6bVE9PSIsImF6cCI6IjZlNzQxNzJiLWJlNTYtNDg0My05ZmY0LWU2NmEzOWJiMTJlMyIsImF6cGFjciI6IjAiLCJuYW1lIjoiQWJlIExpbmNvbG4iLCJvaWQiOiI2OTAyMjJiZS1mZjFhLTRkNTYtYWJkMS03ZTRmN2QzOGU0NzQiLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJhYmVsaUBtaWNyb3NvZnQuY29tIiwicmgiOiJJIiwic2NwIjoiYWNjZXNzX2FzX3VzZXIiLCJzdWIiOiJIS1pwZmFIeVdhZGVPb3VZbGl0anJJLUtmZlRtMjIyWDVyclYzeERxZktRIiwidGlkIjoiNzJmOTg4YmYtODZmMS00MWFmLTkxYWItMmQ3Y2QwMTFkYjQ3IiwidXRpIjoiZnFpQnFYTFBqMGVRYTgyUy1JWUZBQSIsInZlciI6IjIuMCJ9.pj4N-w_3Us9DrBLfpCt

Wyświetl ten token v 2.0 w JWT.MS.View this v2.0 token in JWT.ms.

Oświadczenia w tokenach dostępuClaims in access tokens

JWTs (tokeny sieci Web JSON) są podzielone na trzy sztuki:JWTs (JSON Web Tokens) are split into three pieces:

  • Nagłówek — zawiera informacje na temat weryfikowania tokenu, w tym informacje o typie tokenu i sposobie jego podpisywania.Header - Provides information about how to validate the token including information about the type of token and how it was signed.
  • Ładunek — zawiera wszystkie ważne dane dotyczące użytkownika lub aplikacji próbujących wywołać usługę.Payload - Contains all of the important data about the user or app that is attempting to call your service.
  • Signature — jest surowcem używanym do sprawdzania poprawności tokenu.Signature - Is the raw material used to validate the token.

Każdy element jest oddzielony kropką ( . ) i osobno zakodowany w formacie base64.Each piece is separated by a period (.) and separately Base64 encoded.

Oświadczenia są obecne tylko wtedy, gdy istnieje wartość do wypełnienia.Claims are present only if a value exists to fill it. Twoja aplikacja nie powinna podejmować zależności od obecnego żądania.Your app shouldn't take a dependency on a claim being present. Przykładowo pwd_exp (nie każdy dzierżawca wymaga hasła) i family_name (przepływypoświadczeń klienta znajdują się w imieniu aplikacji, które nie mają nazw).Examples include pwd_exp (not every tenant requires passwords to expire) and family_name (client credential flows are on behalf of applications which don't have names). Oświadczenia używane do sprawdzania poprawności tokenu dostępu będą zawsze obecne.Claims used for access token validation will always be present.

Niektóre oświadczenia są używane do zabezpieczania tokenów usługi Azure AD w przypadku ponownego użycia.Some claims are used to help Azure AD secure tokens in case of reuse. Są one oznaczane jako nieprzeznaczone do użycia publicznego w opisie jako "nieprzezroczyste".These are marked as not being for public consumption in the description as "Opaque". Te oświadczenia mogą lub nie mogą występować w tokenie, a nowe mogą zostać dodane bez powiadomienia.These claims may or may not appear in a token, and new ones may be added without notice.

Oświadczenia nagłówkaHeader claims

ClaimClaim FormatFormat OpisDescription
typ Ciąg — zawsze "JWT"String - always "JWT" Wskazuje, że token jest JWT.Indicates that the token is a JWT.
nonce CiągString Unikatowy identyfikator używany do ochrony przed atakami polegającymi na powtarzaniu tokenu.A unique identifier used to protect against token replay attacks. Zasób może zapisać tę wartość, aby chronić przed odtwarzaniem.Your resource can record this value to protect against replays.
alg CiągString Wskazuje algorytm, który został użyty do podpisania tokenu, na przykład "RS256"Indicates the algorithm that was used to sign the token, for example, "RS256"
kid CiągString Określa odcisk palca klucza publicznego, który jest używany do podpisywania tego tokenu.Specifies the thumbprint for the public key that's used to sign this token. Emitowane w tokenach dostępu zarówno w wersji 1.0, jak i 2.0.Emitted in both v1.0 and v2.0 access tokens.
x5t CiągString Działa tak samo (w użyciu i wartości) jak kid .Functions the same (in use and value) as kid. x5t czy starsze zgłoszenie jest emitowane tylko w tokenach dostępu w wersji 1.0 dla celów zgodności.x5t is a legacy claim emitted only in v1.0 access tokens for compatibility purposes.

Oświadczenia ładunkuPayload claims

ClaimClaim FormatFormat OpisDescription
aud Ciąg, identyfikator URI identyfikatora aplikacji lub identyfikator GUIDString, an App ID URI or GUID Identyfikuje zamierzony odbiorcę tokenu — jej odbiorcy.Identifies the intended recipient of the token - its audience. Interfejs API powinien sprawdzić poprawność tej wartości i odrzucić token, jeśli wartość nie jest zgodna.Your API should validate this value and reject the token if the value doesn't match. W tokenach v 2.0 jest to zawsze identyfikator klienta interfejsu API, a w tokenach w wersji 1.0 może to być identyfikator klienta lub identyfikator URI zasobu używany w żądaniu, w zależności od tego, jak klient zażądał tokenu.In v2.0 tokens, this is always the client ID of the API, while in v1.0 tokens it can be the client ID or the resource URI used in the request, depending on how the client requested the token.
iss Ciąg, identyfikator URI usługi STSString, an STS URI Identyfikuje usługę tokenu zabezpieczającego (STS), która konstruuje i zwraca token oraz dzierżawę usługi Azure AD, w której użytkownik został uwierzytelniony.Identifies the security token service (STS) that constructs and returns the token, and the Azure AD tenant in which the user was authenticated. Jeśli token wystawiony jest tokenem v 2.0 (patrz " ver Claim"), identyfikator URI zakończy się /v2.0 .If the token issued is a v2.0 token (see the ver claim), the URI will end in /v2.0. Identyfikator GUID, który wskazuje, że użytkownik jest użytkownikiem konsumenta z konto Microsoft to 9188040d-6c67-4c5b-b112-36a304b66dad .The GUID that indicates that the user is a consumer user from a Microsoft account is 9188040d-6c67-4c5b-b112-36a304b66dad. Twoja aplikacja może użyć części identyfikatora GUID żądania, aby ograniczyć zbiór dzierżawców, którzy mogą logować się do aplikacji, jeśli ma to zastosowanie.Your app can use the GUID portion of the claim to restrict the set of tenants that can sign in to the app, if applicable.
idp Ciąg, zazwyczaj identyfikator URI usługi STSString, usually an STS URI Rejestruje dostawcę tożsamości, który uwierzytelnił podmiot tokenu.Records the identity provider that authenticated the subject of the token. Ta wartość jest taka sama jak wartość odszkodowania wystawcy, chyba że konto użytkownika nie znajduje się w tej samej dzierżawie co wystawcy, na przykład.This value is identical to the value of the Issuer claim unless the user account not in the same tenant as the issuer - guests, for instance. Jeśli oświadczenia nie jest obecny, oznacza to, że iss można użyć zamiast niego wartości.If the claim isn't present, it means that the value of iss can be used instead. W przypadku kont osobistych używanych w kontekście organizacyjnym (np. konta osobistego zaproszonego do dzierżawy usługi Azure AD) idp może istnieć wartość "Live.com" lub identyfikator URI usługi STS zawierający dzierżawcę konto Microsoft 9188040d-6c67-4c5b-b112-36a304b66dad .For personal accounts being used in an organizational context (for instance, a personal account invited to an Azure AD tenant), the idp claim may be 'live.com' or an STS URI containing the Microsoft account tenant 9188040d-6c67-4c5b-b112-36a304b66dad.
iat int, sygnatura czasowa systemu UNIXint, a UNIX timestamp "Wystawiony w" wskazuje, kiedy wystąpiło uwierzytelnianie dla tego tokenu."Issued At" indicates when the authentication for this token occurred.
nbf int, sygnatura czasowa systemu UNIXint, a UNIX timestamp Wartość "NBF" (nie wcześniej) określa czas, po którym nie można zatwierdzić tokenu JWT do przetwarzania.The "nbf" (not before) claim identifies the time before which the JWT must not be accepted for processing.
exp int, sygnatura czasowa systemu UNIXint, a UNIX timestamp Wartość "EXP" (czas wygaśnięcia) określa czas wygaśnięcia w dniu lub, po którym nie można zaakceptować tokenu JWT do przetworzenia.The "exp" (expiration time) claim identifies the expiration time on or after which the JWT must not be accepted for processing. Należy pamiętać, że zasób może odrzucić token przed tym terminem, na przykład jeśli wymagana jest zmiana uwierzytelniania lub wykryto odwołanie do tokenu.It's important to note that a resource may reject the token before this time as well, such as when a change in authentication is required or a token revocation has been detected.
aio Ciąg nieprzezroczystyOpaque String Deklaracja wewnętrzna używana przez usługę Azure AD do rejestrowania danych do ponownego użycia tokenu.An internal claim used by Azure AD to record data for token reuse. Zasoby nie powinny używać tego żądania.Resources should not use this claim.
acr Ciąg, "0" lub "1"String, a "0" or "1" Występuje tylko w tokenach v 1.0.Only present in v1.0 tokens. Wartość żądania "Klasa kontekstu uwierzytelniania".The "Authentication context class" claim. Wartość "0" wskazuje, że uwierzytelnianie użytkownika końcowego nie spełnia wymagań ISO/IEC 29115.A value of "0" indicates the end-user authentication did not meet the requirements of ISO/IEC 29115.
amr Tablica JSON ciągówJSON array of strings Występuje tylko w tokenach v 1.0.Only present in v1.0 tokens. Określa sposób uwierzytelniania podmiotu tokenu.Identifies how the subject of the token was authenticated. Aby uzyskać więcej informacji , zobacz sekcję "AMR ".See the amr claim section for more details.
appid Ciąg, identyfikator GUIDString, a GUID Występuje tylko w tokenach v 1.0.Only present in v1.0 tokens. Identyfikator aplikacji klienta korzystającej z tokenu.The application ID of the client using the token. Aplikacja może działać jako sama lub w imieniu użytkownika.The application can act as itself or on behalf of a user. Identyfikator aplikacji zazwyczaj reprezentuje obiekt aplikacji, ale może również reprezentować obiekt główny usługi w usłudze Azure AD.The application ID typically represents an application object, but it can also represent a service principal object in Azure AD.
azp Ciąg, identyfikator GUIDString, a GUID Występuje tylko w przypadku tokenów v 2.0, Zamiennik dla appid .Only present in v2.0 tokens, a replacement for appid. Identyfikator aplikacji klienta korzystającej z tokenu.The application ID of the client using the token. Aplikacja może działać jako sama lub w imieniu użytkownika.The application can act as itself or on behalf of a user. Identyfikator aplikacji zazwyczaj reprezentuje obiekt aplikacji, ale może również reprezentować obiekt główny usługi w usłudze Azure AD.The application ID typically represents an application object, but it can also represent a service principal object in Azure AD.
appidacr "0", "1" lub "2""0", "1", or "2" Występuje tylko w tokenach v 1.0.Only present in v1.0 tokens. Wskazuje, w jaki sposób klient został uwierzytelniony.Indicates how the client was authenticated. W przypadku klienta publicznego wartością jest "0".For a public client, the value is "0". Jeśli używasz identyfikatora klienta i klucza tajnego klienta, wartość jest równa "1".If client ID and client secret are used, the value is "1". Jeśli certyfikat klienta został użyty do uwierzytelnienia, wartość jest równa "2".If a client certificate was used for authentication, the value is "2".
azpacr "0", "1" lub "2""0", "1", or "2" Występuje tylko w przypadku tokenów v 2.0, Zamiennik dla appidacr .Only present in v2.0 tokens, a replacement for appidacr. Wskazuje, w jaki sposób klient został uwierzytelniony.Indicates how the client was authenticated. W przypadku klienta publicznego wartością jest "0".For a public client, the value is "0". Jeśli używasz identyfikatora klienta i klucza tajnego klienta, wartość jest równa "1".If client ID and client secret are used, the value is "1". Jeśli certyfikat klienta został użyty do uwierzytelnienia, wartość jest równa "2".If a client certificate was used for authentication, the value is "2".
preferred_username CiągString Podstawowa nazwa użytkownika, która reprezentuje użytkownika.The primary username that represents the user. Może to być adres e-mail, numer telefonu lub ogólna nazwa użytkownika bez określonego formatu.It could be an email address, phone number, or a generic username without a specified format. Jego wartość jest modyfikowalna i może ulec zmianie w czasie.Its value is mutable and might change over time. Ponieważ jest modyfikowalny, ta wartość nie może być używana do podejmowania decyzji dotyczących autoryzacji.Since it is mutable, this value must not be used to make authorization decisions. Można go używać na potrzeby wskazówek dotyczących nazw użytkowników, a także w interfejsie użytkownika z możliwością czytania przez człowieka jako nazwę użytkownika.It can be used for username hints, however, and in human-readable UI as a username. profileZakres jest wymagany w celu otrzymania tego żądania.The profile scope is required in order to receive this claim. Obecne tylko w tokenach v 2.0.Present only in v2.0 tokens.
name CiągString Zapewnia czytelną dla człowieka wartość, która identyfikuje podmiot tokenu.Provides a human-readable value that identifies the subject of the token. Wartość nie może być unikatowa, jest modyfikowalna i przeznaczona do użycia tylko do celów wyświetlania.The value is not guaranteed to be unique, it is mutable, and it's designed to be used only for display purposes. profileZakres jest wymagany w celu otrzymania tego żądania.The profile scope is required in order to receive this claim.
scp Ciąg, rozdzielana spacjami lista zakresówString, a space separated list of scopes Zestaw zakresów uwidocznionych przez aplikację, dla których aplikacja kliencka zażądała (i została odebrana).The set of scopes exposed by your application for which the client application has requested (and received) consent. Aplikacja powinna sprawdzić, czy te zakresy są prawidłowe dla danej aplikacji, i podejmować decyzje dotyczące autoryzacji na podstawie wartości tych zakresów.Your app should verify that these scopes are valid ones exposed by your app, and make authorization decisions based on the value of these scopes. Uwzględnione tylko w przypadku tokenów użytkowników.Only included for user tokens.
roles Tablica ciągów, lista uprawnieńArray of strings, a list of permissions Zestaw uprawnień uwidocznionych przez aplikację, dla których aplikacja żądająca lub użytkownik przyznał uprawnienia do wywoływania.The set of permissions exposed by your application that the requesting application or user has been given permission to call. W przypadku tokenów aplikacjijest używany w ramach przepływu poświadczeń klienta (v 1.0, v 2.0) zamiast zakresów użytkowników.For application tokens, this is used during the client credential flow (v1.0, v2.0) in place of user scopes. W przypadku tokenów użytkowników jest to wypełniane rolami przypisanymi do użytkownika w aplikacji docelowej.For user tokens this is populated with the roles the user was assigned to on the target application.
wids Tablica identyfikatorów GUID RoleTemplateIDArray of RoleTemplateID GUIDs Wskazuje role w całej dzierżawie przypisane do tego użytkownika, z sekcji ról znajdujących się w wbudowanych rolach usługi Azure AD.Denotes the tenant-wide roles assigned to this user, from the section of roles present in Azure AD built-in roles. To zgłoszenie jest konfigurowane dla poszczególnych aplikacji, przez groupMembershipClaims Właściwość manifestu aplikacji.This claim is configured on a per-application basis, through the groupMembershipClaims property of the application manifest. Ustawienie go na "All" lub "DirectoryRole" jest wymagane.Setting it to "All" or "DirectoryRole" is required. Może nie być obecny w tokenach uzyskanych za pomocą niejawnego przepływu ze względu na długość tokenu.May not be present in tokens obtained through the implicit flow due to token length concerns.
groups Tablica JSON identyfikatorów GUIDJSON array of GUIDs Dostarcza identyfikatory obiektów, które reprezentują członkostwo w grupach podmiotu.Provides object IDs that represent the subject's group memberships. Te wartości są unikatowe (zobacz identyfikator obiektu) i mogą być bezpiecznie używane do zarządzania dostępem, takie jak wymuszanie autoryzacji dostępu do zasobu.These values are unique (see Object ID) and can be safely used for managing access, such as enforcing authorization to access a resource. Grupy zawarte w ramach roszczeń grup są konfigurowane dla poszczególnych aplikacji, przez groupMembershipClaims Właściwość manifestu aplikacji.The groups included in the groups claim are configured on a per-application basis, through the groupMembershipClaims property of the application manifest. Wartość null spowoduje wykluczenie wszystkich grup, a wartość "Security Group" będzie zawierać tylko Active Directory przynależności do grupy zabezpieczeń, a wartość "All" będzie obejmować zarówno grupy zabezpieczeń, jak i listy dystrybucyjne Microsoft 365.A value of null will exclude all groups, a value of "SecurityGroup" will include only Active Directory Security Group memberships, and a value of "All" will include both Security Groups and Microsoft 365 Distribution Lists.

Zapoznaj się z poniższym zgłoszeniem, hasgroups Aby uzyskać szczegółowe informacje na temat używania groups roszczeń z niejawnym udzieleniem.See the hasgroups claim below for details on using the groups claim with the implicit grant.
W przypadku innych przepływów, jeśli liczba grup, do których należy użytkownik, przekracza limit (150 dla protokołu SAML, 200 dla tokenu JWT), do źródeł roszczeń zostanie dodana wartość nadwyżkowa, która wskazuje na punkt końcowy Microsoft Graph zawierający listę grup dla użytkownika.For other flows, if the number of groups the user is in goes over a limit (150 for SAML, 200 for JWT), then an overage claim will be added to the claim sources pointing at the Microsoft Graph endpoint containing the list of groups for the user.
hasgroups Wartość logicznaBoolean Jeśli jest obecny, zawsze true oznacza to, że użytkownik należy do co najmniej jednej grupy.If present, always true, denoting the user is in at least one group. Używane zamiast groups roszczeń dla JWTs w niejawnej postaci, jeśli w ramach żądania Full Groups zostanie rozszerzona wartość fragmentu identyfikatora URI poza limitami długości adresów URL (obecnie 6 lub więcej grup).Used in place of the groups claim for JWTs in implicit grant flows if the full groups claim would extend the URI fragment beyond the URL length limits (currently 6 or more groups). Wskazuje, że klient powinien używać interfejsu API Microsoft Graph do określenia grup użytkownika ( https://graph.microsoft.com/v1.0/users/{userID}/getMemberObjects ).Indicates that the client should use the Microsoft Graph API to determine the user's groups (https://graph.microsoft.com/v1.0/users/{userID}/getMemberObjects).
groups:src1 Obiekt JSONJSON object W przypadku żądań tokenów, które nie mają ograniczonej długości (patrz hasgroups powyżej), ale wciąż za duże dla tokenu, zostanie uwzględniony link do listy pełnych grup dla użytkownika.For token requests that are not length limited (see hasgroups above) but still too large for the token, a link to the full groups list for the user will be included. W przypadku JWTs jako roszczeń rozproszonych, w przypadku protokołu SAML jako nowego odszkodowania zamiast groups zgłoszenia.For JWTs as a distributed claim, for SAML as a new claim in place of the groups claim.

Przykładowa wartość JWT:Example JWT Value:
"groups":"src1"
"_claim_sources: "src1" : { "endpoint" : "https://graph.microsoft.com/v1.0/users/{userID}/getMemberObjects" }"_claim_sources: "src1" : { "endpoint" : "https://graph.microsoft.com/v1.0/users/{userID}/getMemberObjects" }
sub CiągString Podmiot zabezpieczeń, dla którego token potwierdza informacje, takie jak użytkownik aplikacji.The principal about which the token asserts information, such as the user of an app. Ta wartość jest niezmienna i nie można jej ponownie przypisać ani ponownie użyć.This value is immutable and cannot be reassigned or reused. Może służyć do bezpiecznego sprawdzania autoryzacji, na przykład gdy token jest używany w celu uzyskania dostępu do zasobu i może być używany jako klucz w tabelach bazy danych.It can be used to perform authorization checks safely, such as when the token is used to access a resource, and can be used as a key in database tables. Ponieważ podmiot jest zawsze obecny w tokenach, które są problemy z usługą Azure AD, zalecamy użycie tej wartości w systemie autoryzacji ogólnego przeznaczenia.Because the subject is always present in the tokens that Azure AD issues, we recommend using this value in a general-purpose authorization system. Podmiot jest jednak identyfikatorem parowania — jest unikatowy dla określonego identyfikatora aplikacji.The subject is, however, a pairwise identifier - it is unique to a particular application ID. W związku z tym, jeśli pojedynczy użytkownik zaloguje się do dwóch różnych aplikacji przy użyciu dwóch różnych identyfikatorów klienta, te aplikacje otrzymają dwie różne wartości dla zgłoszenia podmiotu.Therefore, if a single user signs into two different apps using two different client IDs, those apps will receive two different values for the subject claim. Może to być niepotrzebne, w zależności od wymagań dotyczących architektury i ochrony prywatności.This may or may not be desired depending on your architecture and privacy requirements. Zobacz też, jak również to jest oid takie samo, jak w przypadku wszystkich aplikacji w ramach dzierżawy.See also the oid claim (which does remain the same across apps within a tenant).
oid Ciąg, identyfikator GUIDString, a GUID Niezmienny identyfikator dla "podmiotu" żądania — nazwy głównej użytkownika lub usługi, którego tożsamość została zweryfikowana.The immutable identifier for the "principal" of the request - the user or service principal whose identity has been verified. W tokenach identyfikatorów i tokenach użytkownika i aplikacji, jest to identyfikator obiektu użytkownika.In ID tokens and app+user tokens, this is the object ID of the user. W tokenach tylko do aplikacji jest to identyfikator obiektu jednostki usługi wywołującej.In app-only tokens, this is the object id of the calling service principal. Może również służyć do bezpiecznego sprawdzania autoryzacji i jako klucz w tabelach bazy danych.It can also be used to perform authorization checks safely and as a key in database tables. Ten identyfikator jednoznacznie identyfikuje podmiot zabezpieczeń w aplikacjach — dwie różne aplikacje, które logują się w tym samym użytkowniku, otrzymają taką samą wartość w ramach oid roszczeń.This ID uniquely identifies the principal across applications - two different applications signing in the same user will receive the same value in the oid claim. W związku z tym, oid mogą być używane podczas wykonywania zapytań do usługi online firmy Microsoft, takich jak Microsoft Graph.Thus, oid can be used when making queries to Microsoft online services, such as the Microsoft Graph. Microsoft Graph zwróci ten identyfikator jako id Właściwość dla danego konta użytkownika.The Microsoft Graph will return this ID as the id property for a given user account. Ponieważ oid umożliwia wielu aplikacjom skorelowanie podmiotów zabezpieczeń, profile zakres jest wymagany w celu uzyskania tego żądania dla użytkowników.Because the oid allows multiple apps to correlate principals, the profile scope is required in order to receive this claim for users. Należy pamiętać, że jeśli pojedynczy użytkownik istnieje w wielu dzierżawach, użytkownik będzie zawierać inny identyfikator obiektu w każdej dzierżawie — jest uznawany za różne konta, nawet jeśli użytkownik loguje się do każdego konta z tymi samymi poświadczeniami.Note that if a single user exists in multiple tenants, the user will contain a different object ID in each tenant - they are considered different accounts, even though the user logs into each account with the same credentials.
tid Ciąg, identyfikator GUIDString, a GUID Reprezentuje dzierżawę usługi Azure AD, z której korzysta użytkownik.Represents the Azure AD tenant that the user is from. W przypadku kont służbowych identyfikator GUID jest niezmiennym IDENTYFIKATORem dzierżawy organizacji, do której należy użytkownik.For work and school accounts, the GUID is the immutable tenant ID of the organization that the user belongs to. W przypadku kont osobistych wartość to 9188040d-6c67-4c5b-b112-36a304b66dad .For personal accounts, the value is 9188040d-6c67-4c5b-b112-36a304b66dad. profileZakres jest wymagany w celu otrzymania tego żądania.The profile scope is required in order to receive this claim.
unique_name CiągString Występuje tylko w tokenach v 1.0.Only present in v1.0 tokens. Udostępnia zrozumiałą wartość identyfikującą podmiot tokenu.Provides a human readable value that identifies the subject of the token. Ta wartość nie powinna być unikatowa w ramach dzierżawy i powinna być używana tylko do wyświetlania.This value is not guaranteed to be unique within a tenant and should be used only for display purposes.
uti Ciąg nieprzezroczystyOpaque String Wyjątek wewnętrzny używany przez platformę Azure do weryfikacji tokenów.An internal claim used by Azure to revalidate tokens. Zasoby nie powinny korzystać z tego żądania.Resources shouldn't use this claim.
rh Ciąg nieprzezroczystyOpaque String Wyjątek wewnętrzny używany przez platformę Azure do weryfikacji tokenów.An internal claim used by Azure to revalidate tokens. Zasoby nie powinny używać tego żądania.Resources should not use this claim.
ver Ciąg znaków 1.0 lub 2.0String, either 1.0 or 2.0 Wskazuje wersję tokenu dostępu.Indicates the version of the access token.

Zgłoszenie nadwyżkowe grupGroups overage claim

Aby mieć pewność, że rozmiar tokenu nie przekracza limitów rozmiaru nagłówka HTTP, usługa Azure AD ogranicza liczbę identyfikatorów obiektów uwzględnionych w ramach żądania grup.To ensure that the token size doesn't exceed HTTP header size limits, Azure AD limits the number of object IDs that it includes in the groups claim. Jeśli użytkownik jest członkiem większej liczby grup niż limit nadwyżkowy (150 dla tokenów SAML, 200 dla tokenów JWT i tylko 6, jeśli został wystawiony za pośrednictwem niejawnego przepływu), usługa Azure AD nie emituje roszczeń grupowych w tokenie.If a user is member of more groups than the overage limit (150 for SAML tokens, 200 for JWT tokens, and only 6 if issued via the implicit flow), then Azure AD does not emit the groups claim in the token. Zamiast tego zawiera w tokenie wystąpienie nadwyżkowe, które wskazuje aplikacji, w której ma być wysyłana kwerenda Microsoft Graph interfejsu API w celu pobrania członkostwa w grupie użytkownika.Instead, it includes an overage claim in the token that indicates to the application to query the Microsoft Graph API to retrieve the user's group membership.

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

Możesz użyć BulkCreateGroups.ps1 podanego w folderze Skrypty tworzenia aplikacji , aby pomóc w testowaniu scenariuszy.You can use the BulkCreateGroups.ps1 provided in the App Creation Scripts folder to help test overage scenarios.

podstawowe oświadczenia 1.0v1.0 basic claims

Następujące oświadczenia zostaną uwzględnione w tokenach w wersji 1.0, jeśli ma zastosowanie, ale nie są domyślnie uwzględniane w tokenach programu v 2.0.The following claims will be included in v1.0 tokens if applicable, but aren't included in v2.0 tokens by default. Jeśli używasz programu v 2.0 i potrzebujesz jednego z tych oświadczeń, zażądaj ich przy użyciu opcjonalnych oświadczeń.If you're using v2.0 and need one of these claims, request them using optional claims.

ClaimClaim FormatFormat OpisDescription
ipaddr CiągString Adres IP, z którego użytkownik został uwierzytelniony.The IP address the user authenticated from.
onprem_sid Ciąg w formacie identyfikatora SIDString, in SID format W przypadkach, w których użytkownik ma uwierzytelnianie lokalne, to zgłoszenie zapewnia swój identyfikator SID.In cases where the user has an on-premises authentication, this claim provides their SID. Programu można użyć onprem_sid do autoryzacji w starszych aplikacjach.You can use onprem_sid for authorization in legacy applications.
pwd_exp int, sygnatura czasowa systemu UNIXint, a UNIX timestamp Wskazuje, kiedy wygasa hasło użytkownika.Indicates when the user's password expires.
pwd_url CiągString Adres URL, pod którym można wysyłać użytkowników w celu zresetowania hasła.A URL where users can be sent to reset their password.
in_corp booleanboolean Sygnalizuje, czy klient loguje się z sieci firmowej.Signals if the client is logging in from the corporate network. Jeśli nie, oświadczenia nie są uwzględniane.If they aren't, the claim isn't included.
nickname CiągString Dodatkowa nazwa użytkownika, oddzielona od imię lub nazwisko.An additional name for the user, separate from first or last name.
family_name CiągString Zawiera nazwisko, nazwisko lub nazwę rodziny użytkownika, zgodnie z definicją w obiekcie użytkownika.Provides the last name, surname, or family name of the user as defined on the user object.
given_name CiągString Udostępnia imię i nazwisko użytkownika, zgodnie z ustawieniem obiektu użytkownika.Provides the first or given name of the user, as set on the user object.
upn CiągString Nazwa użytkownika.The username of the user. Może to być numer telefonu, adres e-mail lub niesformatowany ciąg.May be a phone number, email address, or unformatted string. Powinna być używana tylko do celów wyświetlania i dostarczająca wskazówki dotyczące nazwy użytkownika w scenariuszach ponownego uwierzytelniania.Should only be used for display purposes and providing username hints in reauthentication scenarios.

Zgłoszenie amrThe amr claim

Tożsamości firmy Microsoft mogą być uwierzytelniane na różne sposoby, które mogą być odpowiednie dla Twojej aplikacji.Microsoft identities can authenticate in different ways, which may be relevant to your application. To amr jest tablica, która może zawierać wiele elementów, takich jak ["mfa", "rsa", "pwd"] , do uwierzytelniania, które używały zarówno hasła, jak i aplikacji uwierzytelniania.The amr claim is an array that can contain multiple items, such as ["mfa", "rsa", "pwd"], for an authentication that used both a password and the Authenticator app.

WartośćValue OpisDescription
pwd Uwierzytelnianie hasła albo hasło użytkownika firmy Microsoft lub klucz tajny klienta aplikacji.Password authentication, either a user's Microsoft password or an app's client secret.
rsa Uwierzytelnianie było oparte na weryfikacji klucza RSA, na przykład z aplikacją Microsoft Authenticator.Authentication was based on the proof of an RSA key, for example with the Microsoft Authenticator app. Obejmuje to, czy uwierzytelnianie zostało wykonane przy użyciu certyfikatu JWT z podpisem własnym z certyfikatem x509 usługi.This includes if authentication was done by a self-signed JWT with a service owned X509 certificate.
otp Jednorazowy kod dostępu przy użyciu wiadomości e-mail lub wiadomości tekstowej.One-time passcode using an email or a text message.
fed Zostało użyte potwierdzenie uwierzytelniania federacyjnego (takie jak JWT lub SAML).A federated authentication assertion (such as JWT or SAML) was used.
wia Zintegrowane uwierzytelnianie systemu WindowsWindows Integrated Authentication
mfa Użyto uwierzytelniania wieloskładnikowego .Multi-factor authentication was used. Gdy jest obecny, zostaną uwzględnione również inne metody uwierzytelniania.When this is present the other authentication methods will also be included.
ngcmfa Równoważne z mfa , używane do inicjowania obsługi niektórych zaawansowanych typów poświadczeń.Equivalent to mfa, used for provisioning of certain advanced credential types.
wiaormfa Użytkownik użył systemu Windows lub poświadczenia usługi MFA do uwierzytelnienia.The user used Windows or an MFA credential to authenticate.
none Nie zostało wykonane żadne uwierzytelnianie.No authentication was done.

Sprawdzanie poprawności tokenówValidating tokens

Nie wszystkie aplikacje powinny weryfikować tokeny.Not all apps should validate tokens. Tylko w przypadku określonych scenariuszy aplikacje weryfikują token:Only in specific scenarios should apps validate a token:

  • Interfejsy API sieci Web muszą weryfikować tokeny dostępu wysyłane do nich przez klienta.Web APIs must validate access tokens sent to them by a client. Muszą akceptować tylko tokeny zawierające ich aud wnioski.They must only accept tokens containing their aud claim.
  • Poufne aplikacje sieci Web, takie jak ASP.NET Core, muszą sprawdzać poprawność identyfikatorów wysyłanych do nich za pośrednictwem przeglądarki użytkownika w przepływie hybrydowym, przed zezwoleniem na dostęp do danych użytkownika lub ustanawianie sesji.Confidential web apps like ASP.NET Core must validate ID tokens sent to them via the user's browser in the hybrid flow, before allowing access to a user's data or establishing a session.

Jeśli żaden z powyższych scenariuszy nie zostanie zastosowany, aplikacja nie będzie korzystać z weryfikacji tokenu i może stanowić zagrożenie bezpieczeństwa i niezawodności, jeśli decyzje są podejmowane na podstawie ważności tokenu.If none of the above scenarios apply, your application will not benefit from validating the token, and may present a security and reliability risk if decisions are made based on the validity of the token. Klienci publiczni, takie jak aplikacje natywne lub aplikacji jednostronicowych, nie korzystają z walidacji tokenów — aplikacja komunikuje się bezpośrednio z dostawcy tożsamości, więc ochrona SSL gwarantuje, że tokeny są prawidłowe.Public clients like native apps or SPAs don't benefit from validating tokens - the app communicates directly with the IDP, so SSL protection ensures the tokens are valid.

Interfejsy API i aplikacje sieci Web muszą sprawdzać tylko tokeny, które są aud zgodne z ich aplikacjami. inne zasoby mogą mieć niestandardowe reguły walidacji tokenów.APIs and web apps must only validate tokens that have an aud claim that matches their application; other resources may have custom token validation rules. Na przykład tokeny dla Microsoft Graph nie będą sprawdzane zgodnie z tymi regułami z powodu ich zastrzeżonego formatu.For example, tokens for Microsoft Graph won't validate according to these rules due to their proprietary format. Sprawdzanie poprawności i akceptowanie tokenów przeznaczonych dla innego zasobu to przykład nieznanego problemu.Validating and accepting tokens meant for another resource is an example of the confused deputy problem.

Jeśli aplikacja wymaga weryfikacji id_token lub access_token zgodnie z powyższym, aplikacja powinna najpierw zweryfikować sygnaturę i wystawcę tokenu względem wartości w dokumencie odnajdywania OpenID Connect.If your application needs to validate an id_token or an access_token according to the above, your app should first validate the token's signature and issuer against the values in the OpenID discovery document. Na przykład wersja dokumentu niezależna od dzierżawy znajduje się w lokalizacji https://login.microsoftonline.com/common/.well-known/openid-configuration .For example, the tenant-independent version of the document is located at https://login.microsoftonline.com/common/.well-known/openid-configuration.

Następujące informacje są dostarczane dla osób, które chcą zrozumieć proces podstawowy.The following information is provided for those who wish to understand the underlying process. Oprogramowanie pośredniczące usługi Azure AD ma wbudowane funkcje do sprawdzania poprawności tokenów dostępu. możesz przeglądać nasze przykłady , aby znaleźć je w wybranym języku.The Azure AD middleware has built-in capabilities for validating access tokens, and you can browse through our samples to find one in the language of your choice. Istnieje również kilka bibliotek Open-Source innych firm dostępnych do sprawdzania poprawności tokenu JWT — istnieje co najmniej jedna opcja dla niemal każdej platformy i języka.There are also several third-party open-source libraries available for JWT validation - there is at least one option for almost every platform and language. Aby uzyskać więcej informacji na temat bibliotek uwierzytelniania i przykładów kodu usługi Azure AD, zobacz biblioteki uwierzytelniania.For more information about Azure AD authentication libraries and code samples, see the authentication libraries.

Weryfikowanie podpisuValidating the signature

Token JWT zawiera trzy segmenty, które są oddzielane . znakiem.A JWT contains three segments, which are separated by the . character. Pierwszy segment jest znany jako nagłówek, drugi jako treść, a trzeci jako sygnatura.The first segment is known as the header, the second as the body, and the third as the signature. Segment podpisu może służyć do weryfikowania autentyczności tokenu, aby mógł być zaufany przez aplikację.The signature segment can be used to validate the authenticity of the token so that it can be trusted by your app.

Tokeny wystawione przez usługę Azure AD są podpisywane przy użyciu standardowych algorytmów szyfrowania asymetrycznego, takich jak RS256.Tokens issued by Azure AD are signed using industry standard asymmetric encryption algorithms, such as RS256. Nagłówek JWT zawiera informacje na temat metody klucza i szyfrowania użytej do podpisania tokenu:The header of the JWT contains information about the key and encryption method used to sign the token:

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

To alg zastrzeżenie wskazuje algorytm, który został użyty do podpisania tokenu, podczas gdy to zgłoszenie kid wskazuje określony klucz publiczny, który został użyty do zweryfikowania tokenu.The alg claim indicates the algorithm that was used to sign the token, while the kid claim indicates the particular public key that was used to validate the token.

W dowolnym momencie usługa Azure AD może podpisać id_token przy użyciu dowolnego zestawu par kluczy publiczny-prywatny.At any given point in time, Azure AD may sign an id_token using any one of a certain set of public-private key pairs. Usługa Azure AD umożliwia okresowe obracanie możliwego zestawu kluczy, dlatego należy napisać aplikację w celu automatycznego obsłużenia tych zmian.Azure AD rotates the possible set of keys on a periodic basis, so your app should be written to handle those key changes automatically. Rozsądna częstotliwość sprawdzania dostępności aktualizacji kluczy publicznych używanych przez usługę Azure AD wynosi co 24 godziny.A reasonable frequency to check for updates to the public keys used by Azure AD is every 24 hours.

Możesz uzyskać dane klucza podpisywania niezbędne do zweryfikowania podpisu za pomocą dokumentu OpenID Connect Connect Metadata w lokalizacji:You can acquire the signing key data necessary to validate the signature by using the OpenID Connect metadata document located at:

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

Porada

Wypróbuj ten adres URL w przeglądarce.Try this URL in a browser!

Ten dokument metadanych:This metadata document:

  • Jest obiektem JSON zawierającym kilka przydatnych informacji, takich jak lokalizacja różnych punktów końcowych wymaganych do wykonania uwierzytelniania OpenID Connect Connect.Is a JSON object containing several useful pieces of information, such as the location of the various endpoints required for doing OpenID Connect authentication.
  • Zawiera element jwks_uri , który zawiera lokalizację zestawu kluczy publicznych używanych do podpisywania tokenów.Includes a jwks_uri, which gives the location of the set of public keys used to sign tokens. Klucz internetowy JSON (JWK) znajdujący się na jwks_uri liście zawiera wszystkie informacje o kluczu publicznym używany w tym konkretnym momencie.The JSON Web Key (JWK) located at the jwks_uri contains all of the public key information in use at that particular moment in time. Format JWK został opisany w dokumencie RFC 7517.The JWK format is described in RFC 7517. Twoja aplikacja może użyć kid w nagłówku JWT żądania, aby wybrać klucz publiczny w tym dokumencie, który został użyty do podpisania określonego tokenu.Your app can use the kid claim in the JWT header to select which public key in this document has been used to sign a particular token. Następnie można sprawdzić poprawność podpisu przy użyciu prawidłowego klucza publicznego i wskazanego algorytmu.It can then do signature validation using the correct public key and the indicated algorithm.

Uwaga

Zalecamy użycie tego kid żądania do zweryfikowania tokenu.We recommend using the kid claim to validate your token. Chociaż tokeny w wersji 1.0 zawierają x5t zarówno kid oświadczenia, jak i, tokeny v 2.0 zawierają tylko kid oświadczenie.Though v1.0 tokens contain both the x5t and kid claims, v2.0 tokens contain only the kid claim.

Sprawdzanie poprawności podpisu jest poza zakresem tego dokumentu — istnieje wiele bibliotek typu "open source", które ułatwiają wykonywanie takich czynności.Doing signature validation is outside the scope of this document - there are many open-source libraries available for helping you do so if necessary. Jednak platforma tożsamości firmy Microsoft ma jedno rozszerzenie podpisywania tokenu do standardów — niestandardowe klucze podpisywania.However, the Microsoft identity platform has one token signing extension to the standards - custom signing keys.

Jeśli aplikacja ma niestandardowe klucze podpisywania w wyniku użycia funkcji mapowania oświadczeń , należy dołączyć appid parametr zapytania zawierający identyfikator aplikacji, aby uzyskać jwks_uri wskazanie informacji o kluczu podpisywania aplikacji, które powinny być używane do walidacji.If your app has custom signing keys as a result of using the claims-mapping feature, you must append an appid query parameter containing the app ID to get a jwks_uri pointing to your app's signing key information, which should be used for validation. Na przykład: https://login.microsoftonline.com/{tenant}/.well-known/openid-configuration?appid=6731de76-14a6-49ae-97bc-6eba6914391e zawiera jwks_uri https://login.microsoftonline.com/{tenant}/discovery/keys?appid=6731de76-14a6-49ae-97bc-6eba6914391e .For example: https://login.microsoftonline.com/{tenant}/.well-known/openid-configuration?appid=6731de76-14a6-49ae-97bc-6eba6914391e contains a jwks_uri of https://login.microsoftonline.com/{tenant}/discovery/keys?appid=6731de76-14a6-49ae-97bc-6eba6914391e.

Autoryzacja oparta na oświadczeniachClaims based authorization

W ramach logiki biznesowej aplikacji zostanie wyznaczony ten krok, niektóre typowe metody autoryzacji są opisane poniżej.Your application's business logic will dictate this step, some common authorization methods are laid out below.

  • Sprawdź scp lub roles Przejmij, aby sprawdzić, czy wszystkie obecne zakresy są zgodne z tymi, które są udostępniane przez interfejs API, i zezwól klientowi na wykonywanie żądanych akcji.Check the scp or roles claim to verify that all present scopes match those exposed by your API, and allow the client to do the requested action.
  • Upewnij się, że klient wywołujący może wywołać interfejs API przy użyciu tego appid żądania.Ensure the calling client is allowed to call your API using the appid claim.
  • Sprawdź poprawność stanu uwierzytelniania klienta wywołującego, appidacr ale nie powinna być równa 0, jeśli klienci publiczni nie mogą wywoływać interfejsu API.Validate the authentication status of the calling client using appidacr - it shouldn't be 0 if public clients aren't allowed to call your API.
  • Sprawdź listę wcześniejszych nonce oświadczeń, aby sprawdzić, czy token nie jest odtwarzany.Check against a list of past nonce claims to verify the token isn't being replayed.
  • Sprawdź, czy jest tid zgodny z dzierżawcą, który może wywołać interfejs API.Check that the tid matches a tenant that is allowed to call your API.
  • Użyj tego amr żądania, aby sprawdzić, czy użytkownik wykonał uwierzytelnianie wieloskładnikowe.Use the amr claim to verify the user has performed MFA. Należy to wymusić przy użyciu dostępu warunkowego.This should be enforced using Conditional Access.
  • Jeśli zażądano roles oświadczeń lub groups oświadczenia w tokenie dostępu, należy sprawdzić, czy użytkownik znajduje się w grupie, która może wykonać tę akcję.If you've requested the roles or groups claims in the access token, verify that the user is in the group allowed to do this action.
    • W przypadku tokenów pobranych przy użyciu niejawnego przepływu prawdopodobnie trzeba będzie wykonać zapytanie dotyczące Microsoft Graph dla tych danych, ponieważ jest ono często zbyt duże, aby zmieścić je w tokenie.For tokens retrieved using the implicit flow, you'll likely need to query the Microsoft Graph for this data, as it's often too large to fit in the token.

Tokeny użytkownika i aplikacjiUser and application tokens

Aplikacja może otrzymywać tokeny dla użytkownika (zazwyczaj omówionego przez przepływ) lub bezpośrednio z aplikacji (za pośrednictwem przepływu poświadczeń klienta).Your application may receive tokens for user (the flow usually discussed) or directly from an application (through the client credentials flow). Te tokeny obsługujące tylko aplikacje wskazują, że to wywołanie pochodzi z aplikacji i nie ma do niego kopii zapasowej.These app-only tokens indicate that this call is coming from an application and does not have a user backing it. Te tokeny są obsługiwane w dużym stopniu:These tokens are handled largely the same:

  • Użyj, roles Aby wyświetlić uprawnienia, które zostały przyznane podmiotowi tokenu.Use roles to see permissions that have been granted to the subject of the token.
  • Użyj oid lub sub , aby sprawdzić, czy nazwa główna usługi wywołującej jest oczekiwana.Use oid or sub to validate that the calling service principal is the expected one.

Jeśli aplikacja musi rozróżnić tokeny dostępu tylko do aplikacji i tokeny dostępu dla użytkowników, należy użyć idtyp opcjonalnego żądania.If your app needs to distinguish between app-only access tokens and access tokens for users, use the idtyp optional claim. Dodając idtyp do accessToken pola i sprawdzając wartość app , można wykryć tokeny dostępu tylko do aplikacji.By adding the idtyp claim to the accessToken field, and checking for the value app, you can detect app-only access tokens. Tokeny identyfikatorów i tokeny dostępu dla użytkowników nie mają idtyp uwzględnionych roszczeń.ID tokens and access tokens for users will not have the idtyp claim included.

Odwołanie do tokenuToken revocation

Tokeny odświeżania można unieważniać lub odwołać w dowolnym momencie, z różnych powodów.Refresh tokens can be invalidated or revoked at any time, for different reasons. Są one podzielone na dwie główne kategorie: przekroczenia limitu czasu i odwołania.These fall into two main categories: timeouts and revocations.

Limity czasu tokenuToken timeouts

Przy użyciu konfiguracji okresu istnienia tokenumożna zmienić okres istnienia tokenów odświeżania.Using token lifetime configuration, the lifetime of refresh tokens can be altered. Jest to normalne i oczekiwane w przypadku niektórych tokenów bez użycia (np. użytkownik nie otwiera aplikacji przez 3 miesiące) i w związku z tym wygasa.It is normal and expected for some tokens to go without use (e.g. the user does not open the app for 3 months) and therefore expire. Aplikacje będą napotykać scenariusze, w których serwer logowania odrzuca token odświeżania z powodu jego wieku.Apps will encounter scenarios where the login server rejects a refresh token due to its age.

  • MaxInactiveTime: Jeśli token odświeżania nie został użyty w czasie określonym przez MaxInactiveTime, token odświeżania nie będzie już prawidłowy.MaxInactiveTime: If the refresh token hasn't been used within the time dictated by the MaxInactiveTime, the Refresh Token will no longer be valid.
  • MaxSessionAge: Jeśli MaxAgeSessionMultiFactor lub MaxAgeSessionSingleFactor została ustawiona na inną niż domyślna (do odwołania), wówczas uwierzytelnianie będzie wymagane po upływie czasu określonego w MaxAgeSession *.MaxSessionAge: If MaxAgeSessionMultiFactor or MaxAgeSessionSingleFactor have been set to something other than their default (Until-revoked), then reauthentication will be required after the time set in the MaxAgeSession* elapses.
  • Przykłady:Examples:
    • Dzierżawa ma MaxInactiveTime przez pięć dni, a użytkownik wyszedł urlop przez tydzień, a więc usługa Azure AD nie widziała nowego żądania tokenu od użytkownika w ciągu 7 dni.The tenant has a MaxInactiveTime of five days, and the user went on vacation for a week, and so Azure AD hasn't seen a new token request from the user in 7 days. Gdy następnym razem użytkownik zażąda nowego tokenu, zobaczy token odświeżenia, który został odwołany, i musi wprowadzić ponownie swoje poświadczenia.The next time the user requests a new token, they'll find their Refresh Token has been revoked, and they must enter their credentials again.
    • Poufne aplikacje mają MaxAgeSessionSingleFactor jeden dzień.A sensitive application has a MaxAgeSessionSingleFactor of one day. Jeśli użytkownik zaloguje się w poniedziałek i we wtorek (po 25 godzinach upłynął), będzie wymagane do ponownego uwierzytelnienia.If a user logs in on Monday, and on Tuesday (after 25 hours have elapsed), they'll be required to reauthenticate.

UnieważniRevocation

Tokeny odświeżania mogą zostać odwołane przez serwer z powodu zmiany poświadczeń lub akcji administratora.Refresh tokens can be revoked by the server due to a change in credentials, or due to use or admin action. Tokeny odświeżania dzielą się na dwie klasy — te wystawione dla klientów poufnych (kolumna z prawej stronie) i wystawione dla klientów publicznych (wszystkie inne kolumny).Refresh tokens fall into two classes - those issued to confidential clients (the rightmost column) and those issued to public clients (all other columns).

ZmianaChange Plik cookie oparty na hasłachPassword-based cookie Token oparty na hasłachPassword-based token Plik cookie bez hasłaNon-password-based cookie Token nieoparty na haśleNon-password-based token Poufny token klientaConfidential client token
Hasło wygasaPassword expires Pozostaje aktywnaStays alive Pozostaje aktywnaStays alive Pozostaje aktywnaStays alive Pozostaje aktywnaStays alive Pozostaje aktywnaStays alive
Hasło zostało zmienione przez użytkownikaPassword changed by user RevokedRevoked RevokedRevoked Pozostaje aktywnaStays alive Pozostaje aktywnaStays alive Pozostaje aktywnaStays alive
Użytkownik wykonuje SSPRUser does SSPR RevokedRevoked RevokedRevoked Pozostaje aktywnaStays alive Pozostaje aktywnaStays alive Pozostaje aktywnaStays alive
Administrator resetuje hasłoAdmin resets password RevokedRevoked RevokedRevoked Pozostaje aktywnaStays alive Pozostaje aktywnaStays alive Pozostaje aktywnaStays alive
Użytkownik odwołuje tokeny odświeżania za pośrednictwem programu PowerShellUser revokes their refresh tokens via PowerShell RevokedRevoked RevokedRevoked RevokedRevoked RevokedRevoked RevokedRevoked
Administrator odwołuje wszystkie tokeny odświeżania dla użytkownika za pośrednictwem programu PowerShellAdmin revokes all refresh tokens for a user via PowerShell RevokedRevoked RevokedRevoked RevokedRevoked RevokedRevoked RevokedRevoked
Logowanie jednokrotne (v 1.0, v 2.0 ) w sieci WebSingle sign-out (v1.0, v2.0 ) on web RevokedRevoked Pozostaje aktywnaStays alive RevokedRevoked Pozostaje aktywnaStays alive Pozostaje aktywnaStays alive

Bez hasłaNon-password-based

Logowanie nieoparte na hasłach to takie, w przypadku których użytkownik nie mógł wpisać hasła, aby go pobrać.A non-password-based login is one where the user didn't type in a password to get it. Przykłady logowania nieoparte na hasłach obejmują:Examples of non-password-based login include:

  • Korzystanie z funkcji Windows Hello na platformieUsing your face with Windows Hello
  • Klucz FIDO2FIDO2 key
  • SMSSMS
  • Połączenia głosoweVoice
  • Kod PINPIN

Sprawdź podstawowe tokeny odświeżania , aby uzyskać więcej informacji na temat podstawowych tokenów odświeżania.Check out Primary Refresh Tokens for more details on primary refresh tokens.

Następne krokiNext steps