Informazioni di riferimento sui token di Azure Active Directory 2.0Azure Active Directory v2.0 tokens reference

L'endpoint di Azure Active Directory (Azure AD) 2.0 genera tipi diversi di token di sicurezza in ogni flusso di autenticazione.The Azure Active Directory (Azure AD) v2.0 endpoint emits several types of security tokens in each authentication flow. Questo articolo di riferimento descrive il formato, le caratteristiche di sicurezza e i contenuti di ogni tipo di token.This reference describes the format, security characteristics, and contents of each type of token.

Nota

Non tutti gli scenari e le funzionalità di Azure Active Directory sono supportati dall'endpoint v2.0.The v2.0 endpoint does not support all Azure Active Directory scenarios and features. Per determinare se è necessario usare l'endpoint 2.0, vedere l'articolo relativo alle limitazioni della versione 2.0.To determine whether you should use the v2.0 endpoint, read about v2.0 limitations.

Tipi di tokenTypes of tokens

L'endpoint 2.0 supporta il protocollo di autorizzazione OAuth 2.0, che usa sia token di accesso che token di aggiornamento.The v2.0 endpoint supports the OAuth 2.0 authorization protocol, which uses access tokens and refresh tokens. L'endpoint 2.0 supporta anche l'autenticazione e l'accesso tramite OpenID Connect.The v2.0 endpoint also supports authentication and sign-in via OpenID Connect. OpenID Connect introduce un terzo tipo di token, il token ID.OpenID Connect introduces a third type of token, the ID token. Ognuno di questi token viene rappresentato come token di connessione.Each of these tokens is represented as a bearer token.

Un token di connessione è un token di sicurezza leggero che consente al portatore di accedere a una risorsa protetta.A bearer token is a lightweight security token that grants the bearer access to a protected resource. Per "portatore" si intende qualsiasi parte che possa presentare il token.The bearer is any party that can present the token. Anche se la ricezione del token di connessione è subordinata al processo di autenticazione in Azure AD, se non vengono adottate le misure necessarie per proteggere il token durante la trasmissione e l'archiviazione, è possibile che venga intercettato e usato da parti non autorizzate.Although a party must authenticate with Azure AD to receive the bearer token, if steps are not taken to secure the token during transmission and storage, it can be intercepted and used by an unintended party. Alcuni token di sicurezza hanno un meccanismo predefinito che ne impedisce l'uso da parti non autorizzate, mentre i token di connessione non lo hannoSome security tokens have a built-in mechanism to prevent unauthorized parties from using them, but bearer tokens do not. e devono essere trasportati usando un canale protetto, ad esempio il protocollo Transport Layer Security (HTTPS).Bearer tokens must be transported in a secure channel such as transport layer security (HTTPS). Se un token di connessione viene trasmesso senza questo tipo di sicurezza, un utente malintenzionato potrebbe ricorrere a un attacco man-in-the-middle per acquisire il token e usarlo per l'accesso non autorizzato a una risorsa protetta.If a bearer token is transmitted without this type of security, a malicious party could use a "man-in-the-middle attack" to acquire the token and use it for unauthorized access to a protected resource. Gli stessi principi di sicurezza si applicano quando un token di connessione viene archiviato o memorizzato nella cache per un uso futuro.The same security principles apply when storing or caching bearer tokens for later use. Assicurarsi sempre che l'app trasmetta e archivi i token di connessione in modo sicuro.Always ensure that your app securely transmits and stores bearer tokens. Per altre considerazioni sulla sicurezza dei token di connessione, vedere la sezione 5 della specifica RFC 6750.For more security considerations for bearer tokens, see RFC 6750 Section 5.

Molti dei token generati dall'endpoint 2.0 vengono implementati come token JWT (token JSON Web).Many of the tokens issued by the v2.0 endpoint are implemented as JSON Web Tokens (JWTs). Un token JWT è una soluzione compatta e sicura per gli URL per trasferire informazioni tra due parti.A JWT is a compact, URL-safe way to transfer information between two parties. Le informazioni contenute in un token JWT sono dette attestazioni.The information in a JWT is called a claim. Si tratta di asserzioni di informazioni relative alla connessione e all'oggetto del token.It's an assertion of information about the bearer and subject of the token. Le attestazioni in un token JWT sono oggetti JavaScript Object Notation (JSON) codificati e serializzati per la trasmissione.The claims in a JWT are JavaScript Object Notation (JSON) objects that are encoded and serialized for transmission. Dato che i token JWT generati dall'endpoint 2.0 sono firmati, ma non crittografati, è possibile esaminarne facilmente i contenuti a scopo di debug.Because the JWTs issued by the v2.0 endpoint are signed but not encrypted, you can easily inspect the contents of a JWT for debugging purposes. Per altre informazioni sui token JWT, vedere le specifiche dei token JWT.For more information about JWTs, see the JWT specification.

Token IDID tokens

I token ID sono un tipo di token di sicurezza di accesso che l'app riceve quando esegue l'autenticazione usando OpenID Connect.An ID token is a form of sign-in security token that your app receives when it performs authentication by using OpenID Connect. Vengono rappresentati come token JWT e contengono attestazioni che è possibile usare per l'accesso degli utenti all'app.ID tokens are represented as JWTs, and they contain claims that you can use to sign the user in to your app. Le attestazioni nei token ID possono essere usate in diversi modi.You can use the claims in an ID token in various ways. In genere, gli amministratori usano i token ID per visualizzare informazioni sull'account o per prendere decisioni relative al controllo di accesso in un'app.Typically, admins use ID tokens to display account information or to make access control decisions in an app. L'endpoint 2.0 genera solo un tipo di token ID che dispone di un set coerente di attestazioni, indipendentemente dal tipo di utente che ha eseguito l'accesso.The v2.0 endpoint issues only one type of ID token, which has a consistent set of claims, regardless of the type of user that is signed in. Il formato e il contenuto dei token ID sono identici per gli utenti con account Microsoft personali e per quelli con account aziendali o dell'istituto di istruzione.The format and content of ID tokens are the same for personal Microsoft account users and for work or school accounts.

Attualmente i token ID sono firmati, ma non crittografati.Currently, ID tokens are signed but not encrypted. Quando l'app riceve un token ID, deve convalidare la firma per dimostrare l'autenticità del token e convalidare alcune attestazioni nel token per dimostrarne la validità.When your app receives an ID token, it must validate the signature to prove the token's authenticity and validate a few claims in the token to prove its validity. A seconda dei requisiti dello scenario, le attestazioni convalidate da un'app possono variare, ma l'app deve eseguire alcune operazioni comuni di convalida delle attestazioni in ogni scenario.The claims validated by an app vary depending on scenario requirements, but your app must perform some common claim validations in every scenario.

Le sezioni seguenti contengono informazioni dettagliate sulle attestazioni nei token ID e un token ID di esempio.We give you the full details about claims in ID tokens in the following sections, in addition to a sample ID token. Si noti che le attestazioni nei token ID non vengono restituite in un ordine specifico.Note that claims in ID tokens are not returned in a specific order. Si noti anche che possono essere introdotte nuove attestazioni nei token ID in qualsiasi momento.Also, new claims can be introduced into ID tokens at any time. L'introduzione di nuove attestazioni non deve interrompere il funzionamento dell'app.Your app should not break when new claims are introduced. L'elenco seguente include le attestazioni che l'app può interpretare in modo affidabile allo stato attuale.The following list includes the claims that your app currently can reliably interpret. Per informazioni più dettagliate, vedere la specifica di OpenID Connect.You can find more details in the OpenID Connect specification.

Token ID di esempioSample ID token

eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Ik1uQ19WWmNBVGZNNXBPWWlKSE1iYTlnb0VLWSJ9.eyJhdWQiOiI2NzMxZGU3Ni0xNGE2LTQ5YWUtOTdiYy02ZWJhNjkxNDM5MWUiLCJpc3MiOiJodHRwczovL2xvZ2luLm1pY3Jvc29mdG9ubGluZS5jb20vYjk0MTk4MTgtMDlhZi00OWMyLWIwYzMtNjUzYWRjMWYzNzZlL3YyLjAiLCJpYXQiOjE0NTIyODUzMzEsIm5iZiI6MTQ1MjI4NTMzMSwiZXhwIjoxNDUyMjg5MjMxLCJuYW1lIjoiQmFiZSBSdXRoIiwibm9uY2UiOiIxMjM0NSIsIm9pZCI6ImExZGJkZGU4LWU0ZjktNDU3MS1hZDkzLTMwNTllMzc1MGQyMyIsInByZWZlcnJlZF91c2VybmFtZSI6InRoZWdyZWF0YmFtYmlub0BueXkub25taWNyb3NvZnQuY29tIiwic3ViIjoiTUY0Zi1nZ1dNRWppMTJLeW5KVU5RWnBoYVVUdkxjUXVnNWpkRjJubDAxUSIsInRpZCI6ImI5NDE5ODE4LTA5YWYtNDljMi1iMGMzLTY1M2FkYzFmMzc2ZSIsInZlciI6IjIuMCJ9.p_rYdrtJ1oCmgDBggNHB9O38KTnLCMGbMDODdirdmZbmJcTHiZDdtTc-hguu3krhbtOsoYM2HJeZM3Wsbp_YcfSKDY--X_NobMNsxbT7bqZHxDnA2jTMyrmt5v2EKUnEeVtSiJXyO3JWUq9R0dO-m4o9_8jGP6zHtR62zLaotTBYHmgeKpZgTFB9WtUq8DVdyMn_HSvQEfz-LWqckbcTwM_9RNKoGRVk38KChVJo4z5LkksYRarDo8QgQ7xEKmYmPvRr_I7gvM2bmlZQds2OeqWLB1NSNbFZqyFOCgYn3bAQ-nEQSKwBaA36jYGPOVG2r2Qv1uKcpSOxzxaQybzYpQ

Suggerimento

A scopo di esercitazione, provare a verificare le attestazioni nel token ID di esempio incollando quest'ultimo in calebb.net.For practice, to inspect the claims in the sample ID token, paste the sample ID token into calebb.net.

Attestazioni nei token IDClaims in ID tokens

NomeName AttestazioneClaim Valore di esempioExample value DescrizioneDescription
audienceaudience aud 6731de76-14a6-49ae-97bc-6eba6914391e Identifica il destinatario del token.Identifies the intended recipient of the token. Nei token ID il destinatario è l'ID applicazione dell'app, assegnato a quest'ultima nel portale di registrazione delle applicazioni di Microsoft.In ID tokens, the audience is your app's Application ID, assigned to your app in the Microsoft Application Registration Portal. L'app deve convalidare questo valore e rifiutare il token, se il valore non corrisponde.Your app should validate this value, and reject the token if the value does not match.
autorità di certificazioneissuer iss https://login.microsoftonline.com/b9419818-09af-49c2-b0c3-653adc1f376e/v2.0 Identifica il servizio token di sicurezza (STS) che costruisce e restituisce il token e il tenant di Azure AD in cui l'utente è stato autenticato.Identifies the security token service (STS) that constructs and returns the token, and the Azure AD tenant in which the user was authenticated. L'app deve convalidare l'attestazione Autorità di certificazione per assicurarsi che il token sia stato fornito dall'endpoint 2.0.Your app should validate the issuer claim to ensure that the token came from the v2.0 endpoint. Deve usare la parte GUID dell'attestazione per limitare il set di tenant che può accedere all'app.It also should use the GUID portion of the claim to restrict the set of tenants that can sign in to the app. Il GUID che indica che l'utente è un utente consumer di un account Microsoft è 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.
ora di emissioneissued at iat 1452285331 Ora in cui il token è stato generato, rappresentata dal valore epoch time.The time at which the token was issued, represented in epoch time.
scadenzaexpiration time exp 1452289231 Ora in cui il token non è più valido, rappresentata dal valore epoch time.The time at which the token becomes invalid, represented in epoch time. L'app deve usare questa attestazione per verificare la validità della durata del token.Your app should use this claim to verify the validity of the token lifetime.
non primanot before nbf 1452285331 L’ora in cui il token diventa valido, rappresentata dal valore epoch time.The time at which the token becomes valid, represented in epoch time. È in genere uguale all’ora di emissione.It is usually the same as the issuance time. L'app deve usare questa attestazione per verificare la validità della durata del token.Your app should use this claim to verify the validity of the token lifetime.
versionversion ver 2.0 Versione del token ID, come definito da Azure AD.The version of the ID token, as defined by Azure AD. Per l'endpoint 2.0 il valore è 2.0.For the v2.0 endpoint, the value is 2.0.
ID tenanttenant ID tid b9419818-09af-49c2-b0c3-653adc1f376e Valore GUID che rappresenta il tenant di Azure AD da cui proviene l'utente.A GUID that represents the Azure AD tenant that the user is from. Per gli account aziendali e dell'istituto di istruzione, il GUID è l'ID tenant non modificabile dell'organizzazione a cui appartiene l'utente.For work and school accounts, the GUID is the immutable tenant ID of the organization that the user belongs to. Per gli account personali il valore è 9188040d-6c67-4c5b-b112-36a304b66dad.For personal accounts, the value is 9188040d-6c67-4c5b-b112-36a304b66dad. Per ricevere questa attestazione, è necessario l'ambito profile .The profile scope is required in order to receive this claim.
hash del codicecode hash c_hash SGCPtt01wxwfgnYZy2VJtQ L'hash del codice è incluso in un token ID solo quando quest'ultimo viene generato con un codice di autorizzazione di OAuth 2.0.The code hash is included in ID tokens only when the ID token is issued with an OAuth 2.0 authorization code. Può essere usato per convalidare l'autenticità di un codice di autorizzazione.It can be used to validate the authenticity of an authorization code. Per informazioni dettagliate su come eseguire la convalida, vedere la specifica di OpenID Connect.For details about performing this validation, see the OpenID Connect specification.
hash del token di accessoaccess token hash at_hash SGCPtt01wxwfgnYZy2VJtQ L'hash del token di accesso è incluso in un token ID solo quando quest'ultimo viene generato con un token di accesso di OAuth 2.0.The access token hash is included in ID tokens only when the ID token is issued with an OAuth 2.0 access token. Può essere usato per convalidare l'autenticità di un token di accesso.It can be used to validate the authenticity of an access token. Per informazioni dettagliate su come eseguire la convalida, vedere la specifica di OpenID Connect.For details about performing this validation, see the OpenID Connect specification.
noncenonce nonce 12345 L'attestazione Nonce è una strategia per ridurre gli attacchi di riproduzione del token.The nonce is a strategy for mitigating token replay attacks. L'app può specificare un'attestazione Nonce in una richiesta di autorizzazione usando il parametro di query nonce .Your app can specify a nonce in an authorization request by using the nonce query parameter. Il valore specificato nella richiesta viene generato nell'attestazione nonce del token ID, senza essere modificato.The value you provide in the request is emitted in the ID token's nonce claim, unmodified. L'app può verificare il valore rispetto al valore specificato nella richiesta che associa la sessione dell'app a un token ID specifico.Your app can verify the value against the value it specified on the request, which associates the app's session with a specific ID token. L'app deve eseguire la convalida durante il processo di convalida del token ID.Your app should perform this validation during the ID token validation process.
namename name Babe Ruth Questa attestazione fornisce un valore leggibile che identifica l'oggetto del token.The name claim provides a human-readable value that identifies the subject of the token. Il valore potrebbe non essere univoco, è modificabile e può essere usato solo per scopi di visualizzazione.The value is not guaranteed to be unique, it is mutable, and it's designed to be used only for display purposes. Per ricevere questa attestazione, è necessario l'ambito profile .The profile scope is required in order to receive this claim.
emailemail email thegreatbambino@nyy.onmicrosoft.com Indirizzo di posta elettronica primario associato all'account utente, se presente.The primary email address associated with the user account, if one exists. Il valore è modificabile e può variare nel tempo.Its value is mutable and might change over time. Per ricevere questa attestazione, è necessario l'ambito email .The email scope is required in order to receive this claim.
nome utente preferitopreferred username preferred_username thegreatbambino@nyy.onmicrosoft.com Nome utente primario che rappresenta l'utente nell'endpoint 2.0.The primary username that represents the user in the v2.0 endpoint. Potrebbe trattarsi di un indirizzo di posta elettronica, di un numero di telefono o di un nome utente generico senza un formato specificato.It could be an email address, phone number, or a generic username without a specified format. Il valore è modificabile e può variare nel tempo.Its value is mutable and might change over time. Poiché è mutevole, questo valore non deve essere usato per prendere decisioni in merito alle autorizzazioni.Since it is mutable, this value must not be used to make authorization decisions. Per ricevere questa attestazione, è necessario l'ambito profile .The profile scope is required in order to receive this claim.
subjectsubject sub MF4f-ggWMEji12KynJUNQZphaUTvLcQug5jdF2nl01Q Entità su cui il token asserisce informazioni, ad esempio l'utente di un'app.The principal about which the token asserts information, such as the user of an app. Questo valore non è modificabile e non può essere riassegnato o riutilizzato.This value is immutable and cannot be reassigned or reused. Può essere usato per eseguire controlli di autorizzazione in modo sicuro, ad esempio quando il token viene usato per accedere a una risorsa oppure come chiave nelle tabelle di database.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. Dato che il soggetto è sempre presente nei token generati da Azure AD, è consigliabile usare questo valore in un sistema di autorizzazione di uso generico.Because the subject is always present in the tokens that Azure AD issues, we recommend using this value in a general-purpose authorization system. L'oggetto è tuttavia un identificatore pairwise univoco per un ID di applicazione specifico.The subject is, however, a pairwise identifier - it is unique to a particular application ID. Se quindi un singolo utente accede a due app diverse usando due ID client differenti, queste app riceveranno due valori differenti per l'attestazione dell'oggetto.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. Questa condizione può non essere appropriata a seconda dei requisiti a livello di architettura e di privacy.This may or may not be desired depending on your architecture and privacy requirements.
ID oggettoobject ID oid a1dbdde8-e4f9-4571-ad93-3059e3750d23 Identificatore non modificabile per un oggetto nel sistema di identità Microsoft, in questo caso, un account utente.The immutable identifier for an object in the Microsoft identity system, in this case, a user account. Può essere usato anche per eseguire i controlli di autorizzazioni in modo sicuro e come chiave nelle tabelle di database.It can also be used to perform authorization checks safely and as a key in database tables. Questo ID identifica in modo univoco l'utente nelle applicazioni; due applicazioni differenti che consentono l'accesso dello stesso utente riceveranno lo stesso valore nell'attestazione oid.This ID uniquely identifies the user across applications - two different applications signing in the same user will receive the same value in the oid claim. Ciò significa che può essere usato quando si eseguono query in Microsoft Online Services, ad esempio Microsoft Graph.This means that it can be used when making queries to Microsoft online services, such as the Microsoft Graph. Microsoft Graph restituirà l'ID come proprietà id per un determinato account utente.The Microsoft Graph will return this ID as the id property for a given user account. Poiché oid consente a più app di correlare utenti, per ricevere questa attestazione è necessario l'ambito profile.Because the oid allows multiple apps to correlate users, the profile scope is required in order to receive this claim. Si noti che se un singolo utente è presente in più tenant, l'utente conterrà un ID oggetto diverso in ogni tenant; vengono considerati account diversi, anche se l'utente accede a ogni account con le stesse credenziali.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.

Token di accessoAccess tokens

Attualmente, i token di accesso generati dall'endpoint 2.0 possono essere utilizzati solo dai servizi Microsoft.Currently, access tokens issued by the v2.0 endpoint can be consumed only by Microsoft Services. Le app non devono eseguire la convalida o l'ispezione dei token di accesso per gli scenari attualmente supportati.Your apps shouldn't need to perform any validation or inspection of access tokens for any of the currently supported scenarios. I token di accesso possono essere considerati completamente opachi.You can treat access tokens as completely opaque. Si tratta semplicemente di stringhe che l'app può passare a Microsoft nelle richieste HTTP.They are just strings that your app can pass to Microsoft in HTTP requests.

In una fase successiva, l'endpoint 2.0 introdurrà la possibilità per l'app di ricevere i token di accesso da altri client.In the near future, the v2.0 endpoint will introduce the ability for your app to receive access tokens from other clients. A quel punto, il contenuto di questo articolo di riferimento verrà aggiornato con le informazioni necessarie perché l'app possa eseguire la convalida del token di accesso e altre operazioni simili.At that time, the information in this reference topic will be updated with the information that you need for your app to perform access token validation and other similar tasks.

Quando si richiede un token di accesso dall'endpoint 2.0, quest'ultimo restituisce anche alcuni metadati relativi al token di accesso che l'app deve usare.When you request an access token from the v2.0 endpoint, the v2.0 endpoint also returns metadata about the access token for your app to use. Queste informazioni includono l'ora di scadenza del token di accesso e gli ambiti per i quali è valido.This information includes the expiry time of the access token and the scopes for which it is valid. L'app usa i metadati per eseguire operazioni di memorizzazione intelligente dei token di accesso nella cache senza la necessità di analizzare il token di accesso stesso.Your app uses this metadata to perform intelligent caching of access tokens without having to parse open the access token itself.

Token di aggiornamentoRefresh tokens

I token di aggiornamento sono token di sicurezza che l'app può usare per ottenere nuovi token di accesso in un flusso di OAuth 2.0.Refresh tokens are security tokens that your app can use to get new access tokens in an OAuth 2.0 flow. Consentono all'app di ottenere l'accesso a lungo termine alle risorse per conto dell'utente senza richiedere l'interazione con l'utente.Your app can use refresh tokens to achieve long-term access to resources on behalf of a user without requiring interaction with the user.

Si tratta di token a più risorse,Refresh tokens are multi-resource. ossia un token di aggiornamento ricevuto durante una richiesta di token per una risorsa può essere riscattato per i token di accesso a una risorsa completamente diversa.A refresh token received during a token request for one resource can be redeemed for access tokens to a completely different resource.

Per ricevere un aggiornamento in una risposta del token, l'app deve richiedere e ottenere l'ambito offline_acesss.To receive a refresh in a token response, your app must request and be granted the offline_acesss scope. Per altre informazioni sull'ambito offline_access, vedere l'articolo relativo a consenso e ambiti.To learn more about the offline_access scope, see the consent and scopes article.

I token di aggiornamento sono e saranno sempre completamente opachi per l'app.Refresh tokens are, and always will be, completely opaque to your app. Vengono generati dall'endpoint 2.0 di Azure AD e possono essere controllati e interpretati solo dall'endpoint 2.0.They are issued by the Azure AD v2.0 endpoint and can only be inspected and interpreted by the v2.0 endpoint. Hanno una durata elevata, ma l'app non deve essere scritta aspettandosi che un token di aggiornamento duri per un periodo indefinito.They are long-lived, but your app should not be written to expect that a refresh token will last for any period of time. I token di aggiornamento possono essere annullati in qualsiasi momento per vari motivi.Refresh tokens can be invalidated at any moment for various reasons. L'unico modo per l'app di sapere se un token di aggiornamento è valido è tentare di riscattarlo mediante una richiesta di token all'endpoint 2.0.The only way for your app to know if a refresh token is valid is to attempt to redeem it by making a token request to the v2.0 endpoint.

Quando si riscatta un token di aggiornamento per un nuovo token di accesso e l'app ha ottenuto l'ambito offline_access, si riceve un nuovo token di aggiornamento nella risposta del token.When you redeem a refresh token for a new access token (and if your app had been granted the offline_access scope), you receive a new refresh token in the token response. Salvare il token di aggiornamento appena generato per sostituire quello usato nella richiesta.Save the newly issued refresh token, to replace the one you used in the request. In questo modo è possibile prolungare la validità dei token di aggiornamento.This guarantees that your refresh tokens remain valid for as long as possible.

Convalida dei tokenValidating tokens

Attualmente, l'unica convalida dei token che le app devono eseguire è la convalida dei token ID.Currently, the only token validation your apps should need to perform is validating ID tokens. Per convalidare un token ID, l'app deve convalidarne la firma e le attestazioni incluse.To validate an ID token, your app should validate both the ID token's signature and the claims in the ID token.

Microsoft fornisce esempi di codice e librerie che illustrano come gestire in modo semplice la convalida dei token.Microsoft provides libraries and code samples that show you how to easily handle token validation. Le sezioni successive illustrano il processo sottostante.In the next sections, we describe the underlying process. Sono anche disponibili varie librerie open source di terze parti per la convalida dei token JWT.Several third-party open-source libraries also are available for JWT validation. È disponibile almeno una libreria per ogni piattaforma e linguaggio.There's at least one library option for almost every platform and language.

convalidare la firmaValidate the signature

Un token JWT contiene tre segmenti separati dal carattere . .A JWT contains three segments, which are separated by the . character. Il primo segmento è noto come intestazione, il secondo come corpo e il terzo come firma.The first segment is known as the header, the second segment is the body, and the third segment is the signature. Il segmento della firma può essere usato per convalidare l'autenticità del token ID perché venga considerato attendibile dall'app.The signature segment can be used to validate the authenticity of the ID token so that it can be trusted by your app.

I token ID vengono firmati usando algoritmi di crittografia asimmetrica standard del settore, come RSA 256.ID tokens are signed by using industry-standard asymmetric encryption algorithms, such as RSA 256. L'intestazione del token ID contiene informazioni sulla chiave e sul metodo di crittografia usati per firmare il token,The header of the ID token has information about the key and encryption method used to sign the token. ad esempio:For example:

{
  "typ": "JWT",
  "alg": "RS256",
  "kid": "MnC_VZcATfM5pOYiJHMba9goEKY"
}

L'attestazione alg indica l'algoritmo usato per firmare il token.The alg claim indicates the algorithm that was used to sign the token. L'attestazione kid indica la chiave pubblica usata per firmare il token.The kid claim indicates the public key that was used to sign the token.

In qualsiasi momento, l'endpoint 2.0 può firmare un token ID usando una qualsiasi coppia di chiavi pubblica-privata di un set specifico.At any time, the v2.0 endpoint might sign an ID token by using any one of a specific set of public-private key pairs. L'endpoint 2.0 ruota periodicamente il set di chiavi, quindi l'app deve essere scritta in modo da gestire automaticamente le modifiche delle chiavi.The v2.0 endpoint periodically rotates the possible set of keys, so your app should be written to handle those key changes automatically. Una frequenza ragionevole per la ricerca di aggiornamenti per le chiavi pubbliche usate dall'endpoint 2.0 è di circa 24 ore.A reasonable frequency to check for updates to the public keys used by the v2.0 endpoint is every 24 hours.

È possibile acquisire i dati della chiave di firma necessari per convalidare la firma usando il documento di metadati di OpenID Connect disponibile all'indirizzo:You can acquire the signing key data that you need to validate the signature by using the OpenID Connect metadata document located at:

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

Suggerimento

Provare l'URL in un browser.Try the URL in a browser!

Il documento di metadati è un oggetto JSON contenente diverse informazioni utili, ad esempio la posizione dei vari endpoint necessari per l'autenticazione di OpenID Connect.This metadata document is a JSON object that has several useful pieces of information, such as the location of the various endpoints required for OpenID Connect authentication. Il documento include anche un oggetto jwks_uri che fornisce la posizione del set di chiavi pubbliche usate per firmare i token.The document also includes a jwks_uri, which gives the location of the set of public keys used to sign tokens. Il documento JSON in jwks_uri include tutte le informazioni sulla chiave pubblica corrente.The JSON document located at the jwks_uri has all the public key information that is currently in use. L'app può usare l'attestazione kid nell'intestazione del token JWT per selezionare la chiave pubblica del documento usata per firmare un token.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 token. Esegue quindi la convalida della firma usando la chiave pubblica corretta e l'algoritmo indicato.It then performs signature validation by using the correct public key and the indicated algorithm.

La convalida della firma non rientra nelle finalità di questo documento.Performing signature validation is outside the scope of this document. A tale scopo è possibile consultare le varie librerie open source disponibili.Many open-source libraries are available to help you with this.

Convalidare le attestazioniValidate the claims

Quando l'app riceve un token ID all'accesso dell'utente, deve eseguire anche alcuni controlli in base alle attestazioni nel token ID.When your app receives an ID token upon user sign-in, it should also perform a few checks against the claims in the ID token. Sono incluse, ad esempio:These include but are not limited to:

  • Attestazione destinatari: verifica che il token ID fosse destinato all'app.audience claim, to verify that the ID token was intended to be given to your app
  • Attestazioni non prima e scadenza: verificano che il token ID non sia scaduto.not before and expiration time claims, to verify that the ID token has not expired
  • Attestazione autorità di certificazione: verifica che il token sia stato rilasciato all'app dall'endpoint 2.0.issuer claim, to verify that the token was issued to your app by the v2.0 endpoint
  • Attestazione nonce: per ridurre gli attacchi di riproduzione dei token.nonce, as a token replay attack mitigation

Per un elenco completo delle convalide di attestazione che l'app deve eseguire, vedere la specifica di OpenID Connect.For a full list of claim validations that your app should perform, see the OpenID Connect specification.

Per informazioni dettagliate sui valori previsti per tali attestazioni, vedere la sezione Token ID.Details of the expected values for these claims are included in the ID tokens section.

Durata dei tokenToken lifetimes

Le indicazioni sulla durata dei token fornite di seguito sono solo a scopo informativoWe provide the following token lifetimes for your information only. e possono risultare utili per lo sviluppo e il debug delle app.The information might help you as you develop and debug apps. Le app non devono essere scritte in base a una durata specifica prevista come costante.Your apps should not be written to expect any of these lifetimes to remain constant. La durata del token può cambiare in qualsiasi momento.Token lifetimes can and will change at any time.

TokenToken DurataLifetime DescrizioneDescription
Token ID (account aziendale o dell'istituto di istruzione)ID tokens (work or school accounts) 1 ora1 hour I token ID hanno in genere una validità di un'ora.ID tokens typically are valid for 1 hour. L'app Web può usare questa durata per la gestione di una sessione con l'utente (scelta consigliata) oppure è possibile scegliere una durata di sessione completamente diversa.Your web app can use this same lifetime to maintain its own session with the user (recommended), or you can choose a completely different session lifetime. Per ottenere un nuovo token ID, l'app deve eseguire una nuova richiesta di accesso all'endpoint di autorizzazione 2.0.If your app needs to get a new ID token, it needs to make a new sign-in request to the v2.0 authorize endpoint. Se l'utente ha una sessione del browser valida con l'endpoint 2.0, può non essere necessario immettere nuovamente le credenziali.If the user has a valid browser session with the v2.0 endpoint, the user might not be required to enter their credentials again.
Token ID (account personale)ID tokens (personal accounts) 24 ore24 hours I token ID per gli account personali hanno in genere una validità di 24 ore.ID tokens for personal accounts typically are valid for 24 hours. L'app Web può usare questa durata per la gestione di una sessione con l'utente (scelta consigliata) oppure è possibile scegliere una durata di sessione completamente diversa.Your web app can use this same lifetime to maintain its own session with the user (recommended), or you can choose a completely different session lifetime. Per ottenere un nuovo token ID, l'app deve eseguire una nuova richiesta di accesso all'endpoint di autorizzazione 2.0.If your app needs to get a new ID token, it needs to make a new sign-in request to the v2.0 authorize endpoint. Se l'utente ha una sessione del browser valida con l'endpoint 2.0, può non essere necessario immettere nuovamente le credenziali.If the user has a valid browser session with the v2.0 endpoint, the user might not be required to enter their credentials again.
Token di accesso (account aziendale o dell'istituto di istruzione)Access tokens (work or school accounts) 1 ora1 hour Indicati nelle risposte del token come parte dei metadati del token.Indicated in token responses as part of the token metadata.
Token di accesso (account personale)Access tokens (personal accounts) 1 ora1 hour Indicati nelle risposte del token come parte dei metadati del token.Indicated in token responses as part of the token metadata. I token di accesso generati per conto di account personali possono essere configurati con una durata diversa, ma la durata tipica è un'ora.Access tokens that are issued on behalf of personal accounts can be configured for a different lifetime, but 1 hour is typical.
Token di aggiornamento (account aziendale o dell'istituto di istruzione)Refresh tokens (work or school account) Fino a 14 giorniUp to 14 days Un singolo token di aggiornamento è valido per un periodo massimo di 14 giorni.A single refresh token is valid for a maximum of 14 days. Tuttavia, il token di aggiornamento può diventare non valido in qualsiasi momento per diversi motivi, quindi l'app deve continuare a provare a usare un token di aggiornamento fino a quando non si verifica un errore o fino a quando non lo sostituisce con uno nuovo.However, the refresh token might become invalid at any time for various reasons, so your app should continue to try to use a refresh token until it fails, or until your app replaces it with a new refresh token. Inoltre, il token di aggiornamento può diventare non valido dopo 90 giorni dall'immissione delle credenziali da parte dell'utente.A refresh token also becomes invalid if it has been 90 days since the user has entered their credentials.
Token di aggiornamento (account personale)Refresh tokens (personal accounts) Fino a 1 annoUp to 1 year Un singolo token di aggiornamento è valido per un periodo massimo di 1 anno.A single refresh token is valid for a maximum of 1 year. Tuttavia, il token di aggiornamento può diventare non valido in qualsiasi momento per diversi motivi, quindi l'app deve continuare a provare a usare un token di aggiornamento fino a quando non si verifica un errore.However, the refresh token might become invalid at any time for various reasons, so your app should continue to try to use a refresh token until it fails.
Codici di autorizzazione (account aziendale o dell'istituto di istruzione)Authorization codes (work or school accounts) 10 minuti10 minutes I codici di autorizzazione sono intenzionalmente di breve durata e devono essere immediatamente riscattati per i token di accesso e di aggiornamento quando vengono ricevuti.Authorization codes are purposely short-lived, and should be immediately redeemed for access tokens and refresh tokens when the tokens are received.
Codici di autorizzazione (account personale)Authorization codes (personal accounts) 5 minuti5 minutes I codici di autorizzazione sono intenzionalmente di breve durata e devono essere immediatamente riscattati per i token di accesso e di aggiornamento quando vengono ricevuti.Authorization codes are purposely short-lived, and should be immediately redeemed for access tokens and refresh tokens when the tokens are received. I codici di autorizzazione generati per conto degli account personali possono essere usati una sola volta.Authorization codes that are issued on behalf of personal accounts are for one-time use.