Riferimento al token di Azure ADAzure AD token reference

Azure Active Directory (Azure AD) rilascia tipi diversi di token di sicurezza durante l'elaborazione di ogni flusso di autenticazione.Azure Active Directory (Azure AD) emits several types of security tokens in the processing of each authentication flow. Questo documento descrive il formato, le caratteristiche di sicurezza e i contenuti di ogni tipo di token.This document describes the format, security characteristics, and contents of each type of token.

Tipi di tokenTypes of tokens

Azure AD supporta il protocollo di autorizzazione OAuth 2.0, che usa sia token di accesso che token di aggiornamento.Azure AD supports the OAuth 2.0 authorization protocol, which makes use of both access_tokens and refresh_tokens. L'endpoint supporta inoltre l'autenticazione e l'accesso tramite OpenID Connect, che introduce un terzo tipo di token: il token ID.It also supports authentication and sign-in via OpenID Connect, which 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. In questo senso, per "portatore" si intende qualsiasi parte che sia in grado di presentare il token.In this sense, the “bearer” is any party that can present the token. Per ricevere un token di connessione è richiesta l'autenticazione con Azure AD ed è necessario seguire una procedura per proteggere il token onde evitare l'intercettazione da parte di soggetti non autorizzati.Though authentication with Azure AD is required in order to receive a bearer token, steps must be taken to secure the token, to prevent interception by an unintended party. Dal momento che i token di connessione non hanno meccanismi integrati per prevenire l'uso non autorizzato, devono essere trasportati su un canale protetto, ad esempio Transport Layer Security (HTTPS).Because bearer tokens do not have a built-in mechanism to prevent unauthorized parties from using them, they must be transported in a secure channel such as transport layer security (HTTPS). Se un token di connessione viene trasmesso senza essere protetto, un utente malintenzionato potrebbe usare un attacco "man in the middle" per acquisire il token e ottenere accesso non autorizzato a una risorsa protetta.If a bearer token is transmitted in the clear, a man-in the middle attack can be used to acquire the token and gain 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 transmits and stores bearer tokens in a secure manner. Per altre considerazioni sulla sicurezza dei token di connessione, vedere la sezione 5 della specifica RFC 6750.For more security considerations on bearer tokens, see RFC 6750 Section 5.

Molti dei token rilasciati da Azure AD vengono implementati come token JSON Web o JWT.Many of the tokens issued by Azure AD are implemented as JSON Web Tokens, or JWTs. Un token JWT è un modo compatto e indipendente dall'URL di trasferimento delle informazioni tra due parti.A JWT is a compact, URL-safe means of transferring information between two parties. Le informazioni contenute nei token JWT sono note come "attestazioni" o asserzioni di informazioni sulla connessione e sull'oggetto del token.The information contained in JWTs are known as "claims", or assertions of information about the bearer and subject of the token. Le attestazioni nei token JWT sono oggetti JSON codificati e serializzati per la trasmissione.The claims in JWTs are JSON objects encoded and serialized for transmission. Dato che i token JWT rilasciati da Azure AD sono firmati, ma non crittografati, è possibile esaminarne facilmente i contenuti per il debug.Since the JWTs issued by Azure AD are signed, but not encrypted, you can easily inspect the contents of a JWT for debugging purposes. Sono disponibili diversi strumenti per questa operazione, ad esempio jwt.ms.There are several tools available for doing so, such as jwt.ms. Per altre informazioni sui token JWT, fare riferimento alla specifica di JWT.For more information on JWTs, you can refer to 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.Id_tokens are a form of sign-in security token that your app receives when performing authentication using OpenID Connect. Vengono rappresentati come JWT e contengono attestazioni che è possibile usare per l'accesso dell'utente all'app.They are represented as JWTs, and contain claims that you can use for signing the user into your app. È possibile usare le attestazioni in un token ID in base alle proprie esigenze. In genere, vengono usate per la visualizzazione di informazioni sull'account o per prendere decisioni relative al controllo di accesso in un'app.You can use the claims in an id_token as you see fit - commonly they are used for displaying account information or making access control decisions in an app.

Attualmente i token ID sono firmati, ma non crittografati.Id_tokens are signed, but not encrypted at this time. 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. Le attestazioni convalidate da un'app variano a seconda dei requisiti dello scenario, ma esistono alcune convalide di attestazione comuni che l'app deve eseguire in ogni scenario.The claims validated by an app vary depending on scenario requirements, but there are some common claim validations that your app must perform in every scenario.

Vedere la sezione seguente per informazioni su attestazioni ed esempio di token ID.See the following section for information on id_tokens claims, as well as a sample id_token. Si noti che le attestazioni nei token ID non vengono restituite in un ordine particolare.Note that the claims in id_tokens are not returned in any particular order. Inoltre, nei token ID è possibile introdurre nuove attestazioni in qualsiasi momento. L'app non deve interrompersi quando vengono introdotte nuove attestazioni.In addition, new claims can be introduced into id_tokens at any point in time - your app should not break as new claims are introduced. L'elenco seguente include le attestazioni che l'app può interpretare in modo affidabile al momento della stesura di questo articolo.The following list includes the claims that your app can reliably interpret at the time of this writing. Se necessario, sono presenti informazioni più dettagliate nella specifica di OpenID Connect.If necessary, even more detail can be found in the OpenID Connect specification.

Token ID di esempioSample id_token

eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctODkwYS0yNzRhNzJhNzMwOWUiLCJpc3MiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC83ZmU4MTQ0Ny1kYTU3LTQzODUtYmVjYi02ZGU1N2YyMTQ3N2UvIiwiaWF0IjoxMzg4NDQwODYzLCJuYmYiOjEzODg0NDA4NjMsImV4cCI6MTM4ODQ0NDc2MywidmVyIjoiMS4wIiwidGlkIjoiN2ZlODE0NDctZGE1Ny00Mzg1LWJlY2ItNmRlNTdmMjE0NzdlIiwib2lkIjoiNjgzODlhZTItNjJmYS00YjE4LTkxZmUtNTNkZDEwOWQ3NGY1IiwidXBuIjoiZnJhbmttQGNvbnRvc28uY29tIiwidW5pcXVlX25hbWUiOiJmcmFua21AY29udG9zby5jb20iLCJzdWIiOiJKV3ZZZENXUGhobHBTMVpzZjd5WVV4U2hVd3RVbTV5elBtd18talgzZkhZIiwiZmFtaWx5X25hbWUiOiJNaWxsZXIiLCJnaXZlbl9uYW1lIjoiRnJhbmsifQ.

Suggerimento

A scopo di esercitazione, provare a verificare le attestazioni nel token ID di esempio incollandole in jwt.ms.For practice, try inspecting the claims in the sample id_token by pasting it into jwt.ms.

Attestazioni nei token IDClaims in id_tokens

Attestazione JWTJWT Claim NomeName DescrizioneDescription
appid ID applicazioneApplication ID Identifica l'applicazione che usa il token per l'accesso a una risorsa.Identifies the application that is using the token to access a resource. L'applicazione può fungere per conto proprio o per conto dell'utente.The application can act as itself or on behalf of a user. L'ID dell'applicazione in genere rappresenta un oggetto applicazione, ma può anche rappresentare un oggetto di entità servizio in Azure AD.The application ID typically represents an application object, but it can also represent a service principal object in Azure AD.

Valore token JWT di esempio:Example JWT Value:
"appid":"15CB020F-3984-482A-864D-1D92265E8268"
aud DestinatariAudience Destinatario previsto per il token.The intended recipient of the token. L'applicazione che riceve il token deve verificare che il valore del gruppo di destinatari sia corretto e rifiuta tutti i token destinati a un gruppo di destinatari diverso.The application that receives the token must verify that the audience value is correct and reject any tokens intended for a different audience.

Valore SAML di esempio:Example SAML Value:
<AudienceRestriction>
<Audience>
https://contoso.com
</Audience>
</AudienceRestriction>

Valore token JWT di esempio:Example JWT Value:
"aud":"https://contoso.com"
appidacr Riferimento alla classe contesto di autenticazione applicazioneApplication Authentication Context Class Reference Indica la modalità di autenticazione del client.Indicates how the client was authenticated. Per un client pubblico, il valore è 0.For a public client, the value is 0. Se vengono usati l'ID client e il segreto client, il valore è 1.If client ID and client secret are used, the value is 1.

Valore token JWT di esempio:Example JWT Value:
"appidacr": "0"
acr Riferimento alla classe contesto di autenticazioneAuthentication Context Class Reference Indica la modalità di autenticazione del soggetto, invece del client, nell'attestazione di riferimento alla classe contesto di autenticazione dell'applicazione.Indicates how the subject was authenticated, as opposed to the client in the Application Authentication Context Class Reference claim. Il valore "0" indica che l'autenticazione dell'utente finale non soddisfa i requisiti ISO/IEC 29115.A value of "0" indicates the end-user authentication did not meet the requirements of ISO/IEC 29115.

Valore token JWT di esempio:Example JWT Value:
"acr": "0"
Istante di autenticazioneAuthentication Instant Registra la data e l'ora in cui è avvenuta l'autenticazione.Records the date and time when authentication occurred.

Valore SAML di esempio:Example SAML Value:
<AuthnStatement AuthnInstant="2011-12-29T05:35:22.000Z">
amr Metodo di autenticazioneAuthentication Method Identifica la modalità di autenticazione dell'oggetto del token.Identifies how the subject of the token was authenticated.

Valore SAML di esempio:Example SAML Value:
<AuthnContextClassRef>
http://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationmethod/password
</AuthnContextClassRef>

Valore token JWT di esempio: “amr”: ["pwd"]Example JWT Value: “amr”: ["pwd"]
given_name NomeFirst Name Fornisce il nome o il nome "specificato" dell'utente, come impostato nell'oggetto utente di Azure AD.Provides the first or "given" name of the user, as set on the Azure AD user object.

Valore SAML di esempio:Example SAML Value:
<Attribute Name=”http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname”>
<AttributeValue>Frank<AttributeValue>

Valore token JWT di esempio:Example JWT Value:
"given_name": "Frank"
groups GruppiGroups Fornisce gli ID oggetto che rappresentano le appartenenze ai gruppi del soggetto.Provides object IDs that represent the subject's group memberships. Questi valori sono univoci (vedere ID oggetto) e possono essere usati in modo sicuro per la gestione dell'accesso, ad esempio l'attivazione dell'autorizzazione per accedere a una risorsa.These values are unique (see Object ID) and can be safely used for managing access, such as enforcing authorization to access a resource. I gruppi inclusi nella relativa attestazione sono configurati in base all'applicazione, tramite la proprietà "groupMembershipClaims" del manifesto dell'applicazione.The groups included in the groups claim are configured on a per-application basis, through the "groupMembershipClaims" property of the application manifest. Un valore null escluderà tutti i gruppi, un valore "SecurityGroup" includerà solo le appartenenze al gruppo di sicurezza di Active Directory e un valore "All" includerà sia i gruppi di sicurezza che le liste di distribuzione di Office 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 Office 365 Distribution Lists.

Valore SAML di esempio:Example SAML Value:
<Attribute Name="http://schemas.microsoft.com/ws/2008/06/identity/claims/groups">
<AttributeValue>07dd8a60-bf6d-4e17-8844-230b77145381</AttributeValue>

Valore token JWT di esempio:Example JWT Value:
“groups”: ["0e129f5b-6b0a-4944-982d-f776045632af", … ]
idp Provider di identitàIdentity Provider Registra il provider di identità che ha autenticato l'oggetto del token.Records the identity provider that authenticated the subject of the token. Questo valore è identico al valore dell'attestazione Autorità di certificazione, a meno che l'account utente non sia in un tenant diverso rispetto all'autorità di certificazione.This value is identical to the value of the Issuer claim unless the user account is in a different tenant than the issuer.

Valore SAML di esempio:Example SAML Value:
<Attribute Name=” http://schemas.microsoft.com/identity/claims/identityprovider”>
<AttributeValue>https://sts.windows.net/cbb1a5ac-f33b-45fa-9bf5-f37db0fed422/<AttributeValue>

Valore token JWT di esempio:Example JWT Value:
"idp":”https://sts.windows.net/cbb1a5ac-f33b-45fa-9bf5-f37db0fed422/”
iat IssuedAtIssuedAt Archivia l'ora in cui è stato rilasciato il token.Stores the time at which the token was issued. Viene spesso usata per misurare la validità del token.It is often used to measure token freshness.

Valore SAML di esempio:Example SAML Value:
<Assertion ID="_d5ec7a9b-8d8f-4b44-8c94-9812612142be" IssueInstant="2014-01-06T20:20:23.085Z" Version="2.0" xmlns="urn:oasis:names:tc:SAML:2.0:assertion">

Valore token JWT di esempio:Example JWT Value:
"iat": 1390234181
iss IssuerIssuer Identifica il servizio token di sicurezza (STS) che costruisce e restituisce il token.Identifies the security token service (STS) that constructs and returns the token. Nel token restituito da Azure AD l'autorità di certificazione è sts.windows.net.In the tokens that Azure AD returns, the issuer is sts.windows.net. Il GUID del valore di attestazione dell'autorità di certificazione è l'ID tenant della directory di Azure AD.The GUID in the Issuer claim value is the tenant ID of the Azure AD directory. L'ID tenant è un identificatore non modificabile e affidabile della directory.The tenant ID is an immutable and reliable identifier of the directory.

Valore SAML di esempio:Example SAML Value:
<Issuer>https://sts.windows.net/cbb1a5ac-f33b-45fa-9bf5-f37db0fed422/</Issuer>

Valore token JWT di esempio:Example JWT Value:
"iss":”https://sts.windows.net/cbb1a5ac-f33b-45fa-9bf5-f37db0fed422/”
family_name CognomeLast Name Fornisce il cognome dell'utente, come definito nell'oggetto utente di Azure AD.Provides the last name, surname, or family name of the user as defined in the Azure AD user object.

Valore SAML di esempio:Example SAML Value:
<Attribute Name=” http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname”>
<AttributeValue>Miller<AttributeValue>

Valore token JWT di esempio:Example JWT Value:
"family_name": "Miller"
unique_name NomeName Fornisce un valore leggibile che identifica l'oggetto del token.Provides a human readable value that identifies the subject of the token. Questo valore potrebbe non essere univoco all'interno di un tenant e può essere usato solo per scopi di visualizzazione.This value is not guaranteed to be unique within a tenant and is designed to be used only for display purposes.

Valore SAML di esempio:Example SAML Value:
<Attribute Name=”http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name”>
<AttributeValue>frankm@contoso.com<AttributeValue>

Valore token JWT di esempio:Example JWT Value:
"unique_name": "frankm@contoso.com"
oid ID oggettoObject ID Contiene un identificatore univoco di un oggetto in Azure AD.Contains a unique identifier of an object in Azure AD. Questo valore non è modificabile e non può essere riassegnato o riutilizzato.This value is immutable and cannot be reassigned or reused. Usare l'ID oggetto per identificare un oggetto nelle query ad Azure AD.Use the object ID to identify an object in queries to Azure AD.

Valore SAML di esempio:Example SAML Value:
<Attribute Name="http://schemas.microsoft.com/identity/claims/objectidentifier">
<AttributeValue>528b2ac2-aa9c-45e1-88d4-959b53bc7dd0<AttributeValue>

Valore token JWT di esempio:Example JWT Value:
"oid":"528b2ac2-aa9c-45e1-88d4-959b53bc7dd0"
roles RuoliRoles Rappresenta tutti i ruoli applicazione concessi al soggetto sia direttamente che indirettamente tramite l'appartenenza a gruppi e può essere usata per imporre il controllo degli accessi in base al ruolo.Represents all application roles that the subject has been granted both directly and indirectly through group membership and can be used to enforce role-based access control. I ruoli applicazione sono definiti in base all'applicazione, tramite la proprietà appRoles del manifesto dell'applicazione.Application roles are defined on a per-application basis, through the appRoles property of the application manifest. La proprietà value di ogni ruolo applicazione è il valore visualizzato nell'attestazione Ruoli.The value property of each application role is the value that appears in the roles claim.

Valore SAML di esempio:Example SAML Value:
<Attribute Name="http://schemas.microsoft.com/ws/2008/06/identity/claims/role">
<AttributeValue>Admin</AttributeValue>

Valore token JWT di esempio:Example JWT Value:
“roles”: ["Admin", … ]
scp ScopeScope Indica le autorizzazioni di rappresentazione concesse all'applicazione client.Indicates the impersonation permissions granted to the client application. L'autorizzazione predefinita è user_impersonation.The default permission is user_impersonation. Il proprietario della risorsa protetta può registrare valori aggiuntivi in Azure AD.The owner of the secured resource can register additional values in Azure AD.

Valore token JWT di esempio:Example JWT Value:
"scp": "user_impersonation"
sub SubjectSubject Identifica l'entità su cui il token asserisce informazioni, ad esempio l'utente di un'applicazione.Identifies the principal about which the token asserts information, such as the user of an application. Questo valore non è modificabile e non può essere riassegnato o riutilizzato, è quindi possibile usarlo per eseguire controlli di autorizzazione in modo sicuro.This value is immutable and cannot be reassigned or reused, so it can be used to perform authorization checks safely. Dato che il soggetto è sempre presente nei token rilasciati da Azure AD, è consigliabile l'uso di questo valore in un sistema di autorizzazione per utilizzo generico.Because the subject is always present in the tokens the Azure AD issues, we recommended using this value in a general purpose authorization system.
SubjectConfirmation non è un'attestazione.SubjectConfirmation is not a claim. Descrive la modalità di verifica del soggetto del token.It describes how the subject of the token is verified. Bearer indica che il soggetto viene confermato dal possesso del token.Bearer indicates that the subject is confirmed by their possession of the token.

Valore SAML di esempio:Example SAML Value:
<Subject>
<NameID>S40rgb3XjhFTv6EQTETkEzcgVmToHKRkZUIsJlmLdVc</NameID>
<SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer" />
</Subject>

Valore token JWT di esempio:Example JWT Value:
"sub":"92d0312b-26b9-4887-a338-7b00fb3c5eab"
tid ID tenantTenant ID Identificatore non modificabile e non riutilizzabile che identifica il tenant della directory che ha rilasciato il token.An immutable, non-reusable identifier that identifies the directory tenant that issued the token. È possibile usare questo valore per accedere alle risorse di directory specifiche del tenant in un'applicazione multi-tenant.You can use this value to access tenant-specific directory resources in a multi-tenant application. Ad esempio, è possibile usare questo valore per identificare il tenant in una chiamata all'API Graph.For example, you can use this value to identify the tenant in a call to the Graph API.

Valore SAML di esempio:Example SAML Value:
<Attribute Name=”http://schemas.microsoft.com/identity/claims/tenantid”>
<AttributeValue>cbb1a5ac-f33b-45fa-9bf5-f37db0fed422<AttributeValue>

Valore token JWT di esempio:Example JWT Value:
"tid":"cbb1a5ac-f33b-45fa-9bf5-f37db0fed422"
nbf, expnbf, exp Durata del tokenToken Lifetime Definisce l'intervallo di tempo entro il quale un token è valido.Defines the time interval within which a token is valid. Il servizio che convalida il token deve verificare che la data corrente sia compresa nella durata del token. In caso contrario, deve rifiutare il token.The service that validates the token should verify that the current date is within the token lifetime, else it should reject the token. La tolleranza del servizio è fino a cinque minuti oltre l'intervallo della durata del token per tener conto di eventuali differenze di orario ("mancata sincronizzazione dell'ora") tra Azure AD e il servizio.The service might allow for up to five minutes beyond the token lifetime range to account for any differences in clock time ("time skew") between Azure AD and the service.

Valore SAML di esempio:Example SAML Value:
<Conditions
NotBefore="2013-03-18T21:32:51.261Z"
NotOnOrAfter="2013-03-18T22:32:51.261Z"
>

Valore token JWT di esempio:Example JWT Value:
"nbf":1363289634, "exp":1363293234
upn Nome dell'entità utenteUser Principal Name Archivia il nome utente dell'entità utente.Stores the user name of the user principal.

Valore token JWT di esempio:Example JWT Value:
"upn": frankm@contoso.com
ver VersioneVersion Archivia il numero di versione del token.Stores the version number of the token.

Valore token JWT di esempio:Example JWT Value:
"ver": "1.0"

Token di accessoAccess tokens

Al termine dell'autenticazione, Azure AD restituisce un token di accesso, che può essere usato per accedere alle risorse protette.Upon successful authentication, Azure AD returns an access token, which can be used to access protected resources. Il token di accesso è un token JSON Web (JWT) con codifica Base64 e il suo contenuto può essere controllato eseguendolo tramite un decodificatore.The access token is a base 64 encoded JSON Web Token (JWT) and its contents can be inspected by running it through a decoder.

Se l'app usa i token di accesso solo per ottenere l'accesso alle API, è possibile (e consigliabile) trattare i token di accesso come se fossero completamente opachi, dal momento che sono semplicemente stringhe che l'app può trasmettere alle risorse nelle richieste HTTP.If your app only uses access tokens to get access to APIs, you can (and should) treat access tokens as completely opaque - they are just strings which your app can pass to resources in HTTP requests.

Quando si richiede un token di accesso, Azure AD restituisce anche alcuni metadati relativi al token di accesso per l'utilizzo dell'app.When you request an access token, Azure AD also returns some metadata about the access token for your app's consumption. 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. In questo modo l'app può eseguire operazioni di memorizzazione intelligente dei token di accesso senza la necessità di analizzare il token di accesso stesso.This allows your app to perform intelligent caching of access tokens without having to parse open the access token itself.

Se l'app è un'API protetta con Azure AD che prevede token di accesso nelle richieste HTTP, è necessario eseguire la convalida e l'ispezione dei token ricevuti.If your app is an API protected with Azure AD that expects access tokens in HTTP requests, then you should perform validation and inspection of the tokens you receive. L'applicazione deve eseguire la convalida del token di accesso prima di usarlo per accedere alle risorse.Your app should perform validation of the access token before using it to access resources. Per altre informazioni sulla convalida, vedere Convalida dei token.For more information on validation, please see Validating Tokens.
Per informazioni dettagliate su come eseguire questa operazione con .NET, vedere Proteggere un'API Web usando token di connessione di Azure AD.For details on how to do this with .NET, see Protect a Web API using Bearer tokens from Azure AD.

Token di aggiornamentoRefresh tokens

I token di aggiornamento sono token di sicurezza che l'app può usare per acquisire nuovi token di accesso in un flusso di OAuth 2.0.Refresh tokens are security tokens, which your app can use to acquire 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 l'interazione dell'utente.It allows your app to achieve long-term access to resources on behalf of a user without requiring interaction by 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 che fanno riferimento a una risorsa completamente diversa.That is to say that a refresh token received during a token request for one resource can be redeemed for access tokens to a completely different resource. A tale scopo, impostare il parametro resource nella richiesta sulla risorsa di destinazione.To do this, set the resource parameter in the request to the targeted resource.

I token di aggiornamento sono completamente opachi per l'app.Refresh tokens are completely opaque to your app. 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 in time for a variety of reasons. L'unico modo per l'app di sapere se un token di aggiornamento è valido è provare a riscattarlo inviando una richiesta di token all'endpoint di token di Azure AD.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 Azure AD token endpoint.

Quando si riscattano i token di aggiornamento per un nuovo token di accesso, viene visualizzato un nuovo token di aggiornamento nella risposta del token.When you redeem a refresh token for a new access token, you will receive a new refresh token in the token response. È consigliabile salvare il token di aggiornamento appena generato sostituendo quello usato nella richiesta.You should save the newly issued refresh token, replacing the one you used in the request. In questo modo, il token di aggiornamento rimarrà valido più a lungo possibile.This will guarantee that your refresh tokens remain valid for as long as possible.

Convalida dei tokenValidating tokens

Per convalidare un id_token o un access_token, l'app deve convalidarne la firma e le attestazioni.In order to validate an id_token or an access_token, your app should validate both the token's signature and the claims. Per convalidare i token di accesso, l'applicazione deve convalidare anche l'autorità emittente, i destinatari e i token di firma.In order to validate access tokens, your app should also validate the issuer, the audience and the signing tokens. Questi elementi devono essere convalidati in base ai valori contenuti nel documento di individuazione OpenID.These need to be validated against the values in the OpenID discovery document. Ad esempio, la versione indipendente dal tenant del documento si trova in 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. Il middleware di Azure AD dispone di funzionalità incorporate per la convalida dei token di accesso ed è possibile cercare tra gli esempi per trovarne uno nel linguaggio di interesse.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. Per altre informazioni sulla convalida esplicita di un token JWT, vedere l'esempio di convalida JWT manuale.For more information on how to explicitly validate a JWT token, please see the manual JWT validation sample.

Sono disponibili librerie ed esempi di codice che illustrano come gestire facilmente la convalida dei token. Le informazioni seguenti vengono fornite a titolo esemplificativo per chi vuole comprenderne il processo sottostante.We provide libraries and code samples that show how to easily handle token validation - the below information is simply provided for those who wish to understand the underlying process. Sono disponibili anche numerose librerie open source di terze parti per la convalida dei token JWT. Esiste almeno un'opzione per ogni piattaforma e linguaggio disponibili.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 out there. Per altre informazioni sulle librerie di autenticazione di Azure AD e per ottenere esempi di codice, vedere Azure Active Directory Authentication Library.For more information about Azure AD authentication libraries and code samples, please see Azure AD authentication libraries.

Convalida della firmaValidating 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 as the body, and the third as the signature. Il segmento di firma può essere usato per convalidare l'autenticità del token, in modo che possa essere considerato attendibile dall'app.The signature segment can be used to validate the authenticity of the token so that it can be trusted by your app.

I token emessi da Azure AD vengono firmati usando algoritmi di crittografia asimmetrica standard del settore, come RSA 256.Tokens issued by Azure AD are signed using industry standard asymmetric encryption algorithms, such as RSA 256. L'intestazione del token JWT contiene informazioni sulla chiave e sul metodo di crittografia usati per firmare il token:The header of the JWT contains information about the key and encryption method used to sign the token:

{
  "typ": "JWT",
  "alg": "RS256",
  "x5t": "kriMPdmBvx68skT8-mPAB3BseeA"
}

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

In qualsiasi momento, Azure AD può firmare un token ID usando un determinato set di coppie di chiavi pubbliche/private.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. Azure AD ruota il set di chiavi su base periodica, quindi l'app deve essere scritta in modo da gestire automaticamente le modifiche delle chiavi.Azure AD rotates the possible set of keys on a periodic basis, 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 da Azure AD è di circa 24 ore.A reasonable frequency to check for updates to the public keys used by Azure AD is every 24 hours.

È possibile acquisire i dati della chiave per la firma necessari per convalidare la firma usando il documento dei metadati OpenID Connect disponibile all'indirizzo: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/.well-known/openid-configuration

Suggerimento

Provare questo URL in un browser.Try this URL in a browser!

Il documento dei metadati è un oggetto JSON contenente diverse informazioni utili, ad esempio la posizione dei vari endpoint necessari per eseguire l'autenticazione di OpenID Connect.This metadata document is a JSON object containing several useful pieces of information, such as the location of the various endpoints required for performing OpenID Connect authentication.

Include inoltre un oggetto jwks_uriche fornisce la posizione del set di chiavi pubbliche usate per firmare i token.It also includes a jwks_uri, which gives the location of the set of public keys used to sign tokens. Il documento JSON disponibile in jwks_uri contiene tutte le informazioni sulla chiave pubblica usata in un determinato momento.The JSON document located at the jwks_uri contains all of the public key information in use at that particular moment in time. L'app può usare l'attestazione kid nell'intestazione JWT per selezionare quale chiave pubblica è stata usata in questo documento per firmare un determinato 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 particular token. Può quindi eseguire la convalida della firma usando la chiave pubblica corretta e l'algoritmo indicato.It can then perform signature validation using the correct public key and the indicated algorithm.

L'esecuzione della convalida della firma non rientra nell'ambito di questo documento, sono tuttavia disponibili numerose librerie open source che contengono informazioni per eseguire questa operazione.Performing signature validation is outside the scope of this document - there are many open source libraries available for helping you do so if necessary.

Convalida delle attestazioniValidating the claims

Quando l'applicazione riceve un token (id_token all'accesso dell'utente o un token di accesso come token di connessione nella richiesta HTTP) è necessario eseguire anche alcuni controlli nelle attestazioni nel token.When your app receives a token (either an id_token upon user sign-in, or an access token as a bearer token in the HTTP request) it should also perform a few checks against the claims in the token. Sono incluse, ad esempio:These include but are not limited to:

  • Attestazione Audience: per verificare che il token fosse destinato all'app.The Audience claim - to verify that the token was intended to be given to your app.
  • Attestazioni Not Before e Expiration Time: per verificare che il token non sia scaduto.The Not Before and Expiration Time claims - to verify that the token has not expired.
  • Attestazione Issuer : per verificare che il token sia stato effettivamente rilasciato all'app da Azure AD.The Issuer claim - to verify that the token was indeed issued to your app by Azure AD.
  • Attestazione Nonce:per mitigare attacchi di riproduzione del token.The Nonce - to mitigate a token replay attack.
  • E altro ancora...and more...

Per un elenco completo delle convalide di attestazione che l'app deve eseguire per i token ID, vedere le specifiche di OpenID Connect.For a full list of claim validations your app should perform for ID Tokens, refer to the OpenID Connect specification. Per informazioni dettagliate sui valori previsti per tali attestazioni, vedere la sezione Token ID precedente.Details of the expected values for these claims are included in the preceding id_token section section.

Token di esempioSample Tokens

Questa sezione consente di visualizzare esempi di token SAML e JWT restituiti da Azure AD.This section displays samples of SAML and JWT tokens that Azure AD returns. Questi esempi consentono di vedere le attestazioni nel contesto.These samples let you see the claims in context.

Token SAMLSAML Token

Questo è un esempio di un tipico token SAML.This is a sample of a typical SAML token.

<?xml version="1.0" encoding="UTF-8"?>
<t:RequestSecurityTokenResponse xmlns:t="http://schemas.xmlsoap.org/ws/2005/02/trust">
  <t:Lifetime>
    <wsu:Created xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">2014-12-24T05:15:47.060Z</wsu:Created>
    <wsu:Expires xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">2014-12-24T06:15:47.060Z</wsu:Expires>
  </t:Lifetime>
  <wsp:AppliesTo xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy">
    <EndpointReference xmlns="http://www.w3.org/2005/08/addressing">
      <Address>https://contoso.onmicrosoft.com/MyWebApp</Address>
    </EndpointReference>
  </wsp:AppliesTo>
  <t:RequestedSecurityToken>
    <Assertion xmlns="urn:oasis:names:tc:SAML:2.0:assertion" ID="_3ef08993-846b-41de-99df-b7f3ff77671b" IssueInstant="2014-12-24T05:20:47.060Z" Version="2.0">
      <Issuer>https://sts.windows.net/b9411234-09af-49c2-b0c3-653adc1f376e/</Issuer>
      <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        <ds:SignedInfo>
          <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
          <ds:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256" />
          <ds:Reference URI="#_3ef08993-846b-41de-99df-b7f3ff77671b">
            <ds:Transforms>
              <ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature" />
              <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
            </ds:Transforms>
            <ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256" />
            <ds:DigestValue>cV1J580U1pD24hEyGuAxrbtgROVyghCqI32UkER/nDY=</ds:DigestValue>
          </ds:Reference>
        </ds:SignedInfo>
        <ds:SignatureValue>j+zPf6mti8Rq4Kyw2NU2nnu0pbJU1z5bR/zDaKaO7FCTdmjUzAvIVfF8pspVR6CbzcYM3HOAmLhuWmBkAAk6qQUBmKsw+XlmF/pB/ivJFdgZSLrtlBs1P/WBV3t04x6fRW4FcIDzh8KhctzJZfS5wGCfYw95er7WJxJi0nU41d7j5HRDidBoXgP755jQu2ZER7wOYZr6ff+ha+/Aj3UMw+8ZtC+WCJC3yyENHDAnp2RfgdElJal68enn668fk8pBDjKDGzbNBO6qBgFPaBT65YvE/tkEmrUxdWkmUKv3y7JWzUYNMD9oUlut93UTyTAIGOs5fvP9ZfK2vNeMVJW7Xg==</ds:SignatureValue>
        <KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
          <X509Data>
            <X509Certificate>MIIDPjCCAabcAwIBAgIQsRiM0jheFZhKk49YD0SK1TAJBgUrDgMCHQUAMC0xKzApBgNVBAMTImFjY291bnRzLmFjY2Vzc2NvbnRyb2wud2luZG93cy5uZXQwHhcNMTQwMTAxMDcwMDAwWhcNMTYwMTAxMDcwMDAwWjAtMSswKQYDVQQDEyJhY2NvdW50cy5hY2Nlc3Njb250cm9sLndpbmRvd3MubmV0MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAkSCWg6q9iYxvJE2NIhSyOiKvqoWCO2GFipgH0sTSAs5FalHQosk9ZNTztX0ywS/AHsBeQPqYygfYVJL6/EgzVuwRk5txr9e3n1uml94fLyq/AXbwo9yAduf4dCHTP8CWR1dnDR+Qnz/4PYlWVEuuHHONOw/blbfdMjhY+C/BYM2E3pRxbohBb3x//CfueV7ddz2LYiH3wjz0QS/7kjPiNCsXcNyKQEOTkbHFi3mu0u13SQwNddhcynd/GTgWN8A+6SN1r4hzpjFKFLbZnBt77ACSiYx+IHK4Mp+NaVEi5wQtSsjQtI++XsokxRDqYLwus1I1SihgbV/STTg5enufuwIDAQABo2IwYDBeBgNVHQEEVzBVgBDLebM6bK3BjWGqIBrBNFeNoS8wLTErMCkGA1UEAxMiYWNjb3VudHMuYWNjZXNzY29udHJvbC53aW5kb3dzLm5ldIIQsRiM0jheFZhKk49YD0SK1TAJBgUrDgMCHQUAA4IBAQCJ4JApryF77EKC4zF5bUaBLQHQ1PNtA1uMDbdNVGKCmSp8M65b8h0NwlIjGGGy/unK8P6jWFdm5IlZ0YPTOgzcRZguXDPj7ajyvlVEQ2K2ICvTYiRQqrOhEhZMSSZsTKXFVwNfW6ADDkN3bvVOVbtpty+nBY5UqnI7xbcoHLZ4wYD251uj5+lo13YLnsVrmQ16NCBYq2nQFNPuNJw6t3XUbwBHXpF46aLT1/eGf/7Xx6iy8yPJX4DyrpFTutDz882RWofGEO5t4Cw+zZg70dJ/hH/ODYRMorfXEW+8uKmXMKmX2wyxMKvfiPbTy5LmAU8Jvjs2tLg4rOBcXWLAIarZ</X509Certificate>
          </X509Data>
        </KeyInfo>
      </ds:Signature>
      <Subject>
        <NameID Format="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent">m_H3naDei2LNxUmEcWd0BZlNi_jVET1pMLR6iQSuYmo</NameID>
        <SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer" />
      </Subject>
      <Conditions NotBefore="2014-12-24T05:15:47.060Z" NotOnOrAfter="2014-12-24T06:15:47.060Z">
        <AudienceRestriction>
          <Audience>https://contoso.onmicrosoft.com/MyWebApp</Audience>
        </AudienceRestriction>
      </Conditions>
      <AttributeStatement>
        <Attribute Name="http://schemas.microsoft.com/identity/claims/objectidentifier">
          <AttributeValue>a1addde8-e4f9-4571-ad93-3059e3750d23</AttributeValue>
        </Attribute>
        <Attribute Name="http://schemas.microsoft.com/identity/claims/tenantid">
          <AttributeValue>b9411234-09af-49c2-b0c3-653adc1f376e</AttributeValue>
        </Attribute>
        <Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name">
          <AttributeValue>sample.admin@contoso.onmicrosoft.com</AttributeValue>
        </Attribute>
        <Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname">
          <AttributeValue>Admin</AttributeValue>
        </Attribute>
        <Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname">
          <AttributeValue>Sample</AttributeValue>
        </Attribute>
        <Attribute Name="http://schemas.microsoft.com/ws/2008/06/identity/claims/groups">
          <AttributeValue>5581e43f-6096-41d4-8ffa-04e560bab39d</AttributeValue>
          <AttributeValue>07dd8a89-bf6d-4e81-8844-230b77145381</AttributeValue>
          <AttributeValue>0e129f4g-6b0a-4944-982d-f776000632af</AttributeValue>
          <AttributeValue>3ee07328-52ef-4739-a89b-109708c22fb5</AttributeValue>
          <AttributeValue>329k14b3-1851-4b94-947f-9a4dacb595f4</AttributeValue>
          <AttributeValue>6e32c650-9b0a-4491-b429-6c60d2ca9a42</AttributeValue>
          <AttributeValue>f3a169a7-9a58-4e8f-9d47-b70029v07424</AttributeValue>
          <AttributeValue>8e2c86b2-b1ad-476d-9574-544d155aa6ff</AttributeValue>
          <AttributeValue>1bf80264-ff24-4866-b22c-6212e5b9a847</AttributeValue>
          <AttributeValue>4075f9c3-072d-4c32-b542-03e6bc678f3e</AttributeValue>
          <AttributeValue>76f80527-f2cd-46f4-8c52-8jvd8bc749b1</AttributeValue>
          <AttributeValue>0ba31460-44d0-42b5-b90c-47b3fcc48e35</AttributeValue>
          <AttributeValue>edd41703-8652-4948-94a7-2d917bba7667</AttributeValue>
        </Attribute>
        <Attribute Name="http://schemas.microsoft.com/identity/claims/identityprovider">
          <AttributeValue>https://sts.windows.net/b9411234-09af-49c2-b0c3-653adc1f376e/</AttributeValue>
        </Attribute>
      </AttributeStatement>
      <AuthnStatement AuthnInstant="2014-12-23T18:51:11.000Z">
        <AuthnContext>
          <AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:Password</AuthnContextClassRef>
        </AuthnContext>
      </AuthnStatement>
    </Assertion>
  </t:RequestedSecurityToken>
  <t:RequestedAttachedReference>
    <SecurityTokenReference xmlns="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:d3p1="http://docs.oasis-open.org/wss/oasis-wss-wssecurity-secext-1.1.xsd" d3p1:TokenType="http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV2.0">
      <KeyIdentifier ValueType="http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLID">_3ef08993-846b-41de-99df-b7f3ff77671b</KeyIdentifier>
    </SecurityTokenReference>
  </t:RequestedAttachedReference>
  <t:RequestedUnattachedReference>
    <SecurityTokenReference xmlns="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:d3p1="http://docs.oasis-open.org/wss/oasis-wss-wssecurity-secext-1.1.xsd" d3p1:TokenType="http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV2.0">
      <KeyIdentifier ValueType="http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLID">_3ef08993-846b-41de-99df-b7f3ff77671b</KeyIdentifier>
    </SecurityTokenReference>
  </t:RequestedUnattachedReference>
  <t:TokenType>http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV2.0</t:TokenType>
  <t:RequestType>http://schemas.xmlsoap.org/ws/2005/02/trust/Issue</t:RequestType>
  <t:KeyType>http://schemas.xmlsoap.org/ws/2005/05/identity/NoProofKey</t:KeyType>
</t:RequestSecurityTokenResponse>

Token JWT: rappresentazione dell'utenteJWT Token - User Impersonation

Questo è un esempio di un tipico token JSON Web (JWT) usato in un flusso di concessione del codice di autorizzazione.This is a sample of a typical JSON web token (JWT) used in an authorization code grant flow. Oltre alle attestazioni, il token include un numero di versione ver e appidacr, il riferimento alla classe contesto di autenticazione, che indica la modalità di autenticazione client.In addition to claims, the token includes a version number in ver and appidacr, the authentication context class reference, which indicates how the client was authenticated. Per un client pubblico, il valore è 0.For a public client, the value is 0. Se vengono usati l'ID client o il segreto client, il valore è 1.If a client ID or client secret was used, the value is 1.

{
 typ: "JWT",
 alg: "RS256",
 x5t: "kriMPdmBvx68skT8-mPAB3BseeA"
}.
{
 aud: "https://contoso.onmicrosoft.com/scratchservice",
 iss: "https://sts.windows.net/b9411234-09af-49c2-b0c3-653adc1f376e/",
 iat: 1416968588,
 nbf: 1416968588,
 exp: 1416972488,
 ver: "1.0",
 tid: "b9411234-09af-49c2-b0c3-653adc1f376e",
 amr: [
  "pwd"
 ],
 roles: [
  "Admin"
 ],
 oid: "6526e123-0ff9-4fec-ae64-a8d5a77cf287",
 upn: "sample.user@contoso.onmicrosoft.com",
 unique_name: "sample.user@contoso.onmicrosoft.com",
 sub: "yf8C5e_VRkR1egGxJSDt5_olDFay6L5ilBA81hZhQEI",
 family_name: "User",
 given_name: "Sample",
 groups: [
  "0e129f6b-6b0a-4944-982d-f776000632af",
  "323b13b3-1851-4b94-947f-9a4dacb595f4",
  "6e32c250-9b0a-4491-b429-6c60d2ca9a42",
  "f3a161a7-9a58-4e8f-9d47-b70022a07424",
  "8d4c81b2-b1ad-476d-9574-544d155aa6ff",
  "1bf80164-ff24-4866-b19c-6212e5b9a847",
  "76f80127-f2cd-46f4-8c52-8edd8bc749b1",
  "0ba27160-44d0-42b5-b90c-47b3fcc48e35"
 ],
 appid: "b075ddef-0efa-123b-997b-de1337c29185",
 appidacr: "1",
 scp: "user_impersonation",
 acr: "1"
}.