Autorizzare l'accesso ad applicazioni Web di Azure Active Directory mediante il flusso di concessione di OAuth 2.0Authorize access to Azure Active Directory web applications using the OAuth 2.0 code grant flow

Azure Active Directory (Azure AD) usa OAuth 2.0 per consentire di autorizzare l'accesso ad applicazioni Web e API Web nel proprio tenant di Azure AD.Azure Active Directory (Azure AD) uses OAuth 2.0 to enable you to authorize access to web applications and web APIs in your Azure AD tenant. Questa guida descrive la procedura, indipendente dal linguaggio, per inviare e ricevere messaggi HTTP senza usare nessuna delle librerie open source di Microsoft.This guide is language independent, and describes how to send and receive HTTP messages without using any of our open-source libraries.

Il flusso del codice di autorizzazione di OAuth 2.0 è descritto nella sezione 4.1 della specifica di OAuth 2.0.The OAuth 2.0 authorization code flow is described in section 4.1 of the OAuth 2.0 specification. Viene usato per eseguire l'autenticazione e l'autorizzazione nella maggior parte dei tipi di app, tra cui app Web e app native.It is used to perform authentication and authorization in most application types, including web apps and natively installed apps.

Registrare l'applicazione nel tenant di Active DirectoryRegister your application with your AD tenant

Prima di tutto è necessario registrare l'applicazione nel tenant di Azure Active Directory (Azure AD).First, you need to register your application with your Azure Active Directory (Azure AD) tenant. Verrà fornito un ID per l'applicazione, abilitandola per ricevere token.This will give you an Application ID for your application, as well as enable it to receive tokens.

  • Accedere al portale di Azure.Sign in to the Azure portal.
  • Scegliere il tenant di Azure AD facendo clic sull'account nell'angolo superiore destro della pagina.Choose your Azure AD tenant by clicking on your account in the top right corner of the page.
  • Nel riquadro di spostamento a sinistra fare clic su Azure Active Directory.In the left hand navigation pane, click on Azure Active Directory.
  • Fare clic su Registrazioni per l'app e scegliere Registrazione nuova applicazione.Click on App Registrations and click on New application registration.
  • Seguire le istruzioni e creare una nuova applicazione.Follow the prompts and create a new application. Per questa esercitazione non è rilevante che si tratti di un'applicazione Web o un'applicazione nativa, ma per esempi specifici per le applicazioni Web o native, consultare le guide introduttive.It doesn't matter if it is a web application or a native application for this tutorial, but if you'd like specific examples for web applications or native applications, check out our quickstarts.
    • Per le applicazioni Web fornire l'URL accesso, ovvero l'URL di base dell'app con cui gli utenti possono accedere, ad esempio http://localhost:12345.For Web Applications, provide the Sign-On URL, which is the base URL of your app, where users can sign in e.g http://localhost:12345.
    • Per le applicazioni native fornire un URI di reindirizzamento, che Azure AD userà per restituire le risposte dei token.For Native Applications provide a Redirect URI, which Azure AD will use to return token responses. Immettere un valore specifico per l'applicazione in uso, ad esempio http://MyFirstAADAppEnter a value specific to your application, .e.g http://MyFirstAADApp
  • Dopo avere completato la registrazione, Azure AD assegnerà all'applicazione un identificatore client univoco, l'ID applicazione.Once you've completed registration, Azure AD will assign your application a unique client identifier, the Application ID. Poiché questo valore sarà necessario nelle sezioni successive, copiarlo dalla pagina dell'applicazione.You need this value in the next sections, so copy it from the application page.
  • Per individuare l'applicazione nel portale di Azure, fare clic su Registrazioni per l'app, quindi fare clic su Visualizza tutte le applicazioni.To find your application in the Azure portal, click App registrations, and then click View all applications.

Flusso di autorizzazione di OAuth 2.0OAuth 2.0 authorization flow

A livello generale, l'intero flusso di autenticazione per un'applicazione ha un aspetto analogo al seguente:At a high level, the entire authorization flow for an application looks a bit like this:

Flusso del codice di autenticazione di OAuth

Richiedere un codice di autorizzazioneRequest an authorization code

Il flusso del codice di autorizzazione ha inizio con il client che indirizza l'utente all'endpoint /authorize .The authorization code flow begins with the client directing the user to the /authorize endpoint. In questa richiesta, il client indica le autorizzazioni che deve acquisire dall'utente.In this request, the client indicates the permissions it needs to acquire from the user. È possibile ottenere l'endpoint di autorizzazione di OAuth 2.0 per il tenant selezionando Registrazioni per l'app > Endpoint nel portale di Azure.You can get the OAuth 2.0 authorization endpoint for your tenant by selecting App registrations > Endpoints in the Azure portal.

// Line breaks for legibility only

https://login.microsoftonline.com/{tenant}/oauth2/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&response_type=code
&redirect_uri=http%3A%2F%2Flocalhost%3A%12345
&response_mode=query
&resource=https%3A%2F%2Fservice.contoso.com%2F
&state=12345
ParametroParameter DESCRIZIONEDescription
tenanttenant Obbligatoriarequired Il valore {tenant} del percorso della richiesta può essere usato per controllare chi può accedere all'applicazione.The {tenant} value in the path of the request can be used to control who can sign into the application. I valori consentiti sono gli identificatori dei tenant, ad esempio 8eaef023-2b34-4da1-9baa-8bc8c9d6a490, contoso.onmicrosoft.com o common per i token indipendenti dai tenantThe allowed values are tenant identifiers, for example, 8eaef023-2b34-4da1-9baa-8bc8c9d6a490 or contoso.onmicrosoft.com or common for tenant-independent tokens
client_idclient_id Obbligatoriarequired ID applicazione assegnato all'app quando è stata registrata in Azure AD.The Application ID assigned to your app when you registered it with Azure AD. ed è reperibile nel portale di Azure.You can find this in the Azure Portal. Fare clic su Azure Active Directory nella barra laterale dei servizi, fare clic su Registrazioni per l'app e scegliere l'applicazione.Click Azure Active Directory in the services sidebar, click App registrations, and choose the application.
response_typeresponse_type Obbligatoriarequired Deve includere code per il flusso del codice di autorizzazione.Must include code for the authorization code flow.
redirect_uriredirect_uri Consigliatorecommended URI di reindirizzamento dell'app dove le risposte di autenticazione possono essere inviate e ricevute dall'app.The redirect_uri of your app, where authentication responses can be sent and received by your app. Deve corrispondere esattamente a uno degli URI di reindirizzamento registrati nel portale, ad eccezione del fatto che deve essere codificato come URL.It must exactly match one of the redirect_uris you registered in the portal, except it must be url encoded. Per le app native e le app per dispositivi mobili è necessario usare il valore predefinito urn:ietf:wg:oauth:2.0:oob.For native & mobile apps, you should use the default value of urn:ietf:wg:oauth:2.0:oob.
response_moderesponse_mode Consigliatorecommended Specifica il metodo da usare per restituire il token risultante all'app.Specifies the method that should be used to send the resulting token back to your app. Può essere query o form_post.Can be query or form_post. query fornisce il codice come parametro della stringa di query nell'URI di reindirizzamento mentre form_post esegue un'operazione POST che contiene il codice per l'URI di reindirizzamento.query provides the code as a query string parameter on your redirect URI, while form_post executes a POST containing the code to your redirect URI.
statestate Consigliatorecommended Valore incluso nella richiesta che viene restituito nella risposta del token.A value included in the request that is also returned in the token response. Per evitare gli attacchi di richiesta intersito falsa, viene in genere usato un valore univoco generato casualmente.A randomly generated unique value is typically used for preventing cross-site request forgery attacks. Lo stato viene inoltre usato per codificare le informazioni sullo stato dell'utente nell'app prima dell'esecuzione della richiesta di autenticazione, ad esempio la pagina o la vista in cui si trovava.The state is also used to encode information about the user's state in the app before the authentication request occurred, such as the page or view they were on.
resourceresource Consigliatorecommended L'URI dell'ID dell'app dell'API Web di destinazione (risorsa protetta).The App ID URI of the target web API (secured resource). Per trovare l'URI dell'ID dell'app, nel portale di Azure fare clic su Azure Active Directory, fare clic su Registrazioni per l'app, aprire la pagina Impostazioni dell'applicazione e quindi su Proprietà.To find the App ID URI, in the Azure Portal, click Azure Active Directory, click Application registrations, open the application's Settings page, then click Properties. Può anche essere una risorsa esterna, ad esempio https://graph.microsoft.com.It may also be an external resource like https://graph.microsoft.com. Questo è necessario in una delle richieste di token o di autorizzazione.This is required in one of either the authorization or token requests. Per ottenere un numero inferiore di richieste di autenticazione, inserirlo nella richiesta di autorizzazione per assicurarsi che il consenso sia ricevuto dall'utente.To ensure fewer authentication prompts place it in the authorization request to ensure consent is received from the user.
scopescope Ignorataignored Per Azure AD versione 1 gli ambiti devono essere configurati in modo statico nel portale di Azure, in Impostazioni per le applicazioni, Autorizzazioni obbligatorie.For v1 Azure AD apps, scopes must be statically configured in the Azure Portal under the applications Settings, Required Permissions.
promptprompt Facoltativooptional Indica il tipo di interazione obbligatoria dell'utente.Indicate the type of user interaction that is required.

I valori validi sono:Valid values are:

login: all'utente deve essere chiesto di ripetere l'autenticazione.login: The user should be prompted to reauthenticate.

select_account: all'utente viene richiesto di selezionare un account, interrompendo l’accesso single sign on.select_account: The user is prompted to select an account, interrupting single sign on. L'utente può selezionare un account esistente connesso, immettere le proprie credenziali per un account memorizzato o scegliere di usare un account completamente diverso.The user may select an existing signed-in account, enter their credentials for a remembered account, or choose to use a different account altogether.

consent: il consenso dell'utente è stato concesso, ma deve essere aggiornato.consent: User consent has been granted, but needs to be updated. All'utente deve essere chiesto di indicare il consenso.The user should be prompted to consent.

admin_consent: a un amministratore deve essere chiesto di indicare il consenso per conto di tutti gli utenti dell'organizzazioneadmin_consent: An administrator should be prompted to consent on behalf of all users in their organization

login_hintlogin_hint Facoltativooptional Consente di pre-compilare il campo nome utente/indirizzo di posta elettronica dell'utente nella pagina di accesso, se già si conosce il nome utente.Can be used to pre-fill the username/email address field of the sign-in page for the user, if you know their username ahead of time. Le app usano spesso questo parametro durante la riautenticazione, dopo aver estratto il nome utente da un accesso precedente tramite l'attestazione preferred_username.Often apps use this parameter during reauthentication, having already extracted the username from a previous sign-in using the preferred_username claim.
domain_hintdomain_hint Facoltativooptional Offre un suggerimento relativo al tenant o al dominio che l'utente deve usare per accedere.Provides a hint about the tenant or domain that the user should use to sign in. Il valore di domain_hint è un dominio registrato per il tenant.The value of the domain_hint is a registered domain for the tenant. Se il tenant è federato a una directory locale, AAD reindirizza al server federativo tenant specificato.If the tenant is federated to an on-premises directory, AAD redirects to the specified tenant federation server.
code_challenge_methodcode_challenge_method Facoltativooptional Metodo usato per codificare code_verifier per il parametro code_challenge.The method used to encode the code_verifier for the code_challenge parameter. Può essere uno di plain o S256.Can be one of plain or S256. Se escluso, code_challenge viene considerato testo non crittografato se code_challenge è incluso.If excluded, code_challenge is assumed to be plaintext if code_challenge is included. Azure Active Directory versione 1.0 supporta sia plain che S256.Azure AAD v1.0 supports both plain and S256. Per altre informazioni, vedere il PKCE RFC.For more information, see the PKCE RFC.
code_challengecode_challenge Facoltativooptional Utilizzato per proteggere i privilegi concessi sui codici di autorizzazione tramite la chiave di prova per Code Exchange (PKCE) da un client nativo o pubblico.Used to secure authorization code grants via Proof Key for Code Exchange (PKCE) from a native or public client. Obbligatorio con code_challenge_method incluso.Required if code_challenge_method is included. Per altre informazioni, vedere il PKCE RFC.For more information, see the PKCE RFC.

Nota

Se l'utente fa parte di un'organizzazione, un amministratore dell'organizzazione può acconsentire o rifiutare per conto dell'utente oppure permettere all'utente di dare il consenso.If the user is part of an organization, an administrator of the organization can consent or decline on the user's behalf, or permit the user to consent. L'utente ha la possibilità di dare il consenso solo se l'amministratore lo permette.The user is given the option to consent only when the administrator permits it.

A questo punto all'utente verrà chiesto di immettere le credenziali e dare il consenso per le autorizzazioni richieste dall'app nel portale di Azure.At this point, the user is asked to enter their credentials and consent to the permissions requested by the app in the Azure Portal. Dopo che l'utente ha eseguito l'autenticazione e concesso il consenso, Azure AD invia una risposta all'app all'indirizzo redirect_uri della richiesta con il codice.Once the user authenticates and grants consent, Azure AD sends a response to your app at the redirect_uri address in your request with the code.

Risposta con esito positivoSuccessful response

Una risposta con esito positivo può avere un aspetto simile al seguente:A successful response could look like this:

GET  HTTP/1.1 302 Found
Location: http://localhost:12345/?code= AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrqqf_ZT_p5uEAEJJ_nZ3UmphWygRNy2C3jJ239gV_DBnZ2syeg95Ki-374WHUP-i3yIhv5i-7KU2CEoPXwURQp6IVYMw-DjAOzn7C3JCu5wpngXmbZKtJdWmiBzHpcO2aICJPu1KvJrDLDP20chJBXzVYJtkfjviLNNW7l7Y3ydcHDsBRKZc3GuMQanmcghXPyoDg41g8XbwPudVh7uCmUponBQpIhbuffFP_tbV8SNzsPoFz9CLpBCZagJVXeqWoYMPe2dSsPiLO9Alf_YIe5zpi-zY4C3aLw5g9at35eZTfNd0gBRpR5ojkMIcZZ6IgAA&session_state=7B29111D-C220-4263-99AB-6F6E135D75EF&state=D79E5777-702E-4260-9A62-37F75FF22CCE
ParametroParameter DESCRIZIONEDescription
admin_consentadmin_consent Il valore è True se un amministratore ha acconsentito a una richiesta di consenso.The value is True if an administrator consented to a consent request prompt.
codecode Codice di autorizzazione richiesto dall'applicazione.The authorization code that the application requested. L'applicazione può usare il codice di autorizzazione per richiedere un token di accesso per la risorsa di destinazione.The application can use the authorization code to request an access token for the target resource.
session_statesession_state Valore univoco che identifica la sessione utente corrente.A unique value that identifies the current user session. Questo valore è un GUID, ma deve essere trattato come un valore opaco passato senza alcun controllo.This value is a GUID, but should be treated as an opaque value that is passed without examination.
statestate Se un parametro di stato è incluso nella richiesta, lo stesso valore viene visualizzato nella risposta.If a state parameter is included in the request, the same value should appear in the response. È consigliabile che l'applicazione verifichi che i valori dello stato nella richiesta e nella risposta siano identici, prima di usare la risposta.It's a good practice for the application to verify that the state values in the request and response are identical before using the response. Ciò consente di rilevare gli attacchi di richiesta intersito falsa (CSRF) contro il client.This helps to detect Cross-Site Request Forgery (CSRF) attacks against the client.

Risposta di erroreError response

Le risposte di errore possono essere inviate anche a redirect_uri , in modo che l'applicazione possa gestirle adeguatamente.Error responses may also be sent to the redirect_uri so that the application can handle them appropriately.

GET http://localhost:12345/?
error=access_denied
&error_description=the+user+canceled+the+authentication
ParametroParameter DESCRIZIONEDescription
errorerror Valore del codice di errore definito nella sezione 5.2 del framework di autorizzazione di OAuth 2.0.An error code value defined in Section 5.2 of the OAuth 2.0 Authorization Framework. La tabella successiva descrive i codici errore restituiti da Azure AD.The next table describes the error codes that Azure AD returns.
error_descriptionerror_description Descrizione più dettagliata dell'errore.A more detailed description of the error. Questo messaggio non vuole essere semplice da usare.This message is not intended to be end-user friendly.
statestate Il valore di state è un valore non riutilizzato generato casualmente che viene inviato nella richiesta e restituito nella risposta per impedire attacchi di tipo richiesta intersito falsa.The state value is a randomly generated non-reused value that is sent in the request and returned in the response to prevent cross-site request forgery (CSRF) attacks.

Codici per gli errori dell'endpoint di autorizzazioneError codes for authorization endpoint errors

La tabella seguente descrive i diversi codici errore che possono essere restituiti nel parametro error della risposta di errore.The following table describes the various error codes that can be returned in the error parameter of the error response.

Codice di erroreError Code DESCRIZIONEDescription Azione clientClient Action
invalid_requestinvalid_request Errore del protocollo, ad esempio un parametro obbligatorio mancante.Protocol error, such as a missing required parameter. Correggere e inviare di nuovo la richiesta.Fix and resubmit the request. Si tratta di un errore di sviluppo rilevato in genere durante il test iniziale.This is a development error, and is typically caught during initial testing.
unauthorized_clientunauthorized_client All'applicazione client non è consentito richiedere un codice di autorizzazione.The client application is not permitted to request an authorization code. Si verifica in genere quando l'applicazione client non è registrata in Azure AD o non è stata aggiunta al tenant di Azure AD dell'utente.This usually occurs when the client application is not registered in Azure AD or is not added to the user's Azure AD tenant. L'applicazione può chiedere all'utente di installare l'applicazione e di aggiungerla ad Azure AD.The application can prompt the user with instruction for installing the application and adding it to Azure AD.
access_deniedaccess_denied Consenso negato dal proprietario della risorsaResource owner denied consent L'applicazione client può notificare all'utente che non può proseguire a meno che l'utente non acconsenta.The client application can notify the user that it cannot proceed unless the user consents.
unsupported_response_typeunsupported_response_type Il server di autorizzazione non supporta il tipo di risposta nella richiesta.The authorization server does not support the response type in the request. Correggere e inviare di nuovo la richiesta.Fix and resubmit the request. Si tratta di un errore di sviluppo rilevato in genere durante il test iniziale.This is a development error, and is typically caught during initial testing.
server_errorserver_error Errore imprevisto rilevato dal server.The server encountered an unexpected error. ripetere la richiesta.Retry the request. Questi errori possono dipendere da condizioni temporanee.These errors can result from temporary conditions. L'applicazione client può comunicare all'utente che la risposta è stata ritardata a causa di un errore temporaneo.The client application might explain to the user that its response is delayed due to a temporary error.
temporarily_unavailabletemporarily_unavailable Il server è temporaneamente troppo occupato per gestire la richiesta.The server is temporarily too busy to handle the request. ripetere la richiesta.Retry the request. L'applicazione client può comunicare all'utente che la risposta è stata ritardata a causa di una condizione temporanea.The client application might explain to the user that its response is delayed due to a temporary condition.
invalid_resourceinvalid_resource La risorsa di destinazione non è valida perché non esiste, Azure AD non riesce a trovarla o non è attualmente configurata.The target resource is invalid because it does not exist, Azure AD cannot find it, or it is not correctly configured. Indica che la risorsa, se presente, non è stata configurata nel tenant.This indicates the resource, if it exists, has not been configured in the tenant. L'applicazione può chiedere all'utente di installare l'applicazione e di aggiungerla ad Azure AD.The application can prompt the user with instruction for installing the application and adding it to Azure AD.

Usare un codice di autorizzazione per richiedere un token di accessoUse the authorization code to request an access token

Dopo aver acquisito un codice di autorizzazione e aver ottenuto l'autorizzazione dall'utente, è possibile riscattare il codice per un token di accesso per la risorsa desiderata inviando una richiesta POST all'endpoint /token :Now that you've acquired an authorization code and have been granted permission by the user, you can redeem the code for an access token to the desired resource, by sending a POST request to the /token endpoint:

// Line breaks for legibility only

POST /{tenant}/oauth2/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code
&client_id=2d4d11a2-f814-46a7-890a-274a72a7309e
&code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrqqf_ZT_p5uEAEJJ_nZ3UmphWygRNy2C3jJ239gV_DBnZ2syeg95Ki-374WHUP-i3yIhv5i-7KU2CEoPXwURQp6IVYMw-DjAOzn7C3JCu5wpngXmbZKtJdWmiBzHpcO2aICJPu1KvJrDLDP20chJBXzVYJtkfjviLNNW7l7Y3ydcHDsBRKZc3GuMQanmcghXPyoDg41g8XbwPudVh7uCmUponBQpIhbuffFP_tbV8SNzsPoFz9CLpBCZagJVXeqWoYMPe2dSsPiLO9Alf_YIe5zpi-zY4C3aLw5g9at35eZTfNd0gBRpR5ojkMIcZZ6IgAA
&redirect_uri=https%3A%2F%2Flocalhost%3A12345
&resource=https%3A%2F%2Fservice.contoso.com%2F
&client_secret=p@ssw0rd

//NOTE: client_secret only required for web apps
ParametroParameter DESCRIZIONEDescription
tenanttenant Obbligatoriarequired Il valore {tenant} del percorso della richiesta può essere usato per controllare chi può accedere all'applicazione.The {tenant} value in the path of the request can be used to control who can sign into the application. I valori consentiti sono gli identificatori dei tenant, ad esempio 8eaef023-2b34-4da1-9baa-8bc8c9d6a490, contoso.onmicrosoft.com o common per i token indipendenti dai tenantThe allowed values are tenant identifiers, for example, 8eaef023-2b34-4da1-9baa-8bc8c9d6a490 or contoso.onmicrosoft.com or common for tenant-independent tokens
client_idclient_id Obbligatoriarequired ID applicazione assegnato all'app quando è stata registrata in Azure AD.The Application Id assigned to your app when you registered it with Azure AD. Questo è reperibile nel portale di Azure.You can find this in the Azure portal. L'ID applicazione è visualizzato nelle impostazioni della registrazione dell'app.The Application Id is displayed in the settings of the app registration.
grant_typegrant_type Obbligatoriarequired Deve essere authorization_code per il flusso del codice di autorizzazione.Must be authorization_code for the authorization code flow.
codecode Obbligatoriarequired Il valore authorization_code acquisito nella sezione precedenteThe authorization_code that you acquired in the previous section
redirect_uriredirect_uri Obbligatoriarequired Lo stesso valore redirect_uri utilizzato per acquisire authorization_code.The same redirect_uri value that was used to acquire the authorization_code.
client_secretclient_secret richiesto per le app Web, non consentito per i client pubblicirequired for web apps, not allowed for public clients Il segreto dell'applicazione creato nel portale di Azure per l'app in Chiavi.The application secret that you created in the Azure Portal for your app under Keys. Non può essere usato in un'app nativa (client pubblico), perché client_secret non può essere archiviato in modo affidabile nei dispositivi.It cannot be used in a native app (public client), because client_secrets cannot be reliably stored on devices. È obbligatorio per le app Web e le API Web (tutti i client riservati) che possono archiviare client_secret in modo sicuro sul lato server.It is required for web apps and web APIs (all confidential clients), which have the ability to store the client_secret securely on the server side.
resourceresource Consigliatorecommended L'URI dell'ID dell'app dell'API Web di destinazione (risorsa protetta).The App ID URI of the target web API (secured resource). Per trovare l'URI dell'ID dell'app, nel portale di Azure fare clic su Azure Active Directory, fare clic su Registrazioni per l'app, aprire la pagina Impostazioni dell'applicazione e quindi su Proprietà.To find the App ID URI, in the Azure Portal, click Azure Active Directory, click Application registrations, open the application's Settings page, then click Properties. Può anche essere una risorsa esterna, ad esempio https://graph.microsoft.com.It may also be an external resource like https://graph.microsoft.com. Questo è necessario in una delle richieste di token o di autorizzazione.This is required in one of either the authorization or token requests. Per ottenere un numero inferiore di richieste di autenticazione, inserirlo nella richiesta di autorizzazione per assicurarsi che il consenso sia ricevuto dall'utente.To ensure fewer authentication prompts place it in the authorization request to ensure consent is received from the user. Se sono presenti sia nella richiesta di autorizzazione sia nella richiesta di token, i parametri della risorsa devono corrispondere.If in both the authorization request and the token request, the resource` parameters must match.
code_verifiercode_verifier Facoltativooptional Stesso code_verifier usato per ottenere il codice di autorizzazione.The same code_verifier that was used to obtain the authorization_code. Obbligatorio se nella richiesta di concessione del codice di autorizzazione è stato usato PKCE.Required if PKCE was used in the authorization code grant request. Per altre informazioni, vedere il PKCE RFCFor more information, see the PKCE RFC

Per trovare l'URI dell'ID dell'app, nel portale di Azure fare clic su Azure Active Directory, fare clic su Registrazioni per l'app, aprire la pagina Impostazioni dell'applicazione e quindi su Proprietà.To find the App ID URI, in the Azure Portal, click Azure Active Directory, click Application registrations, open the application's Settings page, then click Properties.

Risposta con esito positivoSuccessful response

Azure AD restituisce un token di accesso in caso di risposta corretta.Azure AD returns an access token upon a successful response. Per ridurre al minimo le chiamate di rete dall'applicazione client e la latenza associata, l'applicazione client deve memorizzare i token di accesso nella cache per la durata del token specificata nella risposta OAuth 2.0.To minimize network calls from the client application and their associated latency, the client application should cache access tokens for the token lifetime that is specified in the OAuth 2.0 response. Per determinare la durata del token, usare i valori dei parametri expires_in o expires_on.To determine the token lifetime, use either the expires_in or expires_on parameter values.

Se una risorsa API Web restituisce un codice di errore invalid_token , ciò può indicare che la risorsa ha determinato che il token è scaduto.If a web API resource returns an invalid_token error code, this might indicate that the resource has determined that the token is expired. Se l'ora del client e l'ora della risorsa sono diverse ("sfasamento dell'ora"), la risorsa potrebbe considerare il token scaduto prima che venga cancellato dalla cache del client.If the client and resource clock times are different (known as a "time skew"), the resource might consider the token to be expired before the token is cleared from the client cache. In questo caso, cancellare il token dalla cache anche se si trova ancora nella durata calcolata.If this occurs, clear the token from the cache, even if it is still within its calculated lifetime.

Una risposta con esito positivo può avere un aspetto simile al seguente:A successful response could look like this:

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1THdqcHdBSk9NOW4tQSJ9.eyJhdWQiOiJodHRwczovL3NlcnZpY2UuY29udG9zby5jb20vIiwiaXNzIjoiaHR0cHM6Ly9zdHMud2luZG93cy5uZXQvN2ZlODE0NDctZGE1Ny00Mzg1LWJlY2ItNmRlNTdmMjE0NzdlLyIsImlhdCI6MTM4ODQ0MDg2MywibmJmIjoxMzg4NDQwODYzLCJleHAiOjEzODg0NDQ3NjMsInZlciI6IjEuMCIsInRpZCI6IjdmZTgxNDQ3LWRhNTctNDM4NS1iZWNiLTZkZTU3ZjIxNDc3ZSIsIm9pZCI6IjY4Mzg5YWUyLTYyZmEtNGIxOC05MWZlLTUzZGQxMDlkNzRmNSIsInVwbiI6ImZyYW5rbUBjb250b3NvLmNvbSIsInVuaXF1ZV9uYW1lIjoiZnJhbmttQGNvbnRvc28uY29tIiwic3ViIjoiZGVOcUlqOUlPRTlQV0pXYkhzZnRYdDJFYWJQVmwwQ2o4UUFtZWZSTFY5OCIsImZhbWlseV9uYW1lIjoiTWlsbGVyIiwiZ2l2ZW5fbmFtZSI6IkZyYW5rIiwiYXBwaWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctODkwYS0yNzRhNzJhNzMwOWUiLCJhcHBpZGFjciI6IjAiLCJzY3AiOiJ1c2VyX2ltcGVyc29uYXRpb24iLCJhY3IiOiIxIn0.JZw8jC0gptZxVC-7l5sFkdnJgP3_tRjeQEPgUn28XctVe3QqmheLZw7QVZDPCyGycDWBaqy7FLpSekET_BftDkewRhyHk9FW_KeEz0ch2c3i08NGNDbr6XYGVayNuSesYk5Aw_p3ICRlUV1bqEwk-Jkzs9EEkQg4hbefqJS6yS1HoV_2EsEhpd_wCQpxK89WPs3hLYZETRJtG5kvCCEOvSHXmDE6eTHGTnEgsIk--UlPe275Dvou4gEAwLofhLDQbMSjnlV5VLsjimNBVcSRFShoxmQwBJR_b2011Y5IuD6St5zPnzruBbZYkGNurQK63TJPWmRd3mbJsGM0mf3CUQ",
  "token_type": "Bearer",
  "expires_in": "3600",
  "expires_on": "1388444763",
  "resource": "https://service.contoso.com/",
  "refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4rTfgV29ghDOHRc2B-C_hHeJaJICqjZ3mY2b_YNqmf9SoAylD1PycGCB90xzZeEDg6oBzOIPfYsbDWNf621pKo2Q3GGTHYlmNfwoc-OlrxK69hkha2CF12azM_NYhgO668yfcUl4VBbiSHZyd1NVZG5QTIOcbObu3qnLutbpadZGAxqjIbMkQ2bQS09fTrjMBtDE3D6kSMIodpCecoANon9b0LATkpitimVCrl-NyfN3oyG4ZCWu18M9-vEou4Sq-1oMDzExgAf61noxzkNiaTecM-Ve5cq6wHqYQjfV9DOz4lbceuYCAA",
  "scope": "https%3A%2F%2Fgraph.microsoft.com%2Fmail.read",
  "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctODkwYS0yNzRhNzJhNzMwOWUiLCJpc3MiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC83ZmU4MTQ0Ny1kYTU3LTQzODUtYmVjYi02ZGU1N2YyMTQ3N2UvIiwiaWF0IjoxMzg4NDQwODYzLCJuYmYiOjEzODg0NDA4NjMsImV4cCI6MTM4ODQ0NDc2MywidmVyIjoiMS4wIiwidGlkIjoiN2ZlODE0NDctZGE1Ny00Mzg1LWJlY2ItNmRlNTdmMjE0NzdlIiwib2lkIjoiNjgzODlhZTItNjJmYS00YjE4LTkxZmUtNTNkZDEwOWQ3NGY1IiwidXBuIjoiZnJhbmttQGNvbnRvc28uY29tIiwidW5pcXVlX25hbWUiOiJmcmFua21AY29udG9zby5jb20iLCJzdWIiOiJKV3ZZZENXUGhobHBTMVpzZjd5WVV4U2hVd3RVbTV5elBtd18talgzZkhZIiwiZmFtaWx5X25hbWUiOiJNaWxsZXIiLCJnaXZlbl9uYW1lIjoiRnJhbmsifQ."
}
ParametroParameter DESCRIZIONEDescription
access_tokenaccess_token Il token di accesso richiesto come token JSON Web (JWT) firmato.The requested access token as a signed JSON Web Token (JWT). L'app può usare questo token per l'autenticazione alla risorsa protetta, ad esempio un'API Web.The app can use this token to authenticate to the secured resource, such as a web API.
token_typetoken_type Indica il valore del tipo di token.Indicates the token type value. L'unico tipo supportato da Azure AD è Bearer.The only type that Azure AD supports is Bearer. Per altre informazioni sui token di connessione, vedere OAuth2.0 Authorization Framework: Bearer Token Usage (RFC 6750)For more information about Bearer tokens, see OAuth2.0 Authorization Framework: Bearer Token Usage (RFC 6750)
expires_inexpires_in Validità del token di accesso (espressa in secondi).How long the access token is valid (in seconds).
expires_onexpires_on Scadenza del token di accesso.The time when the access token expires. La data è rappresentata come numero di secondi da 1970-01-01T0:0:0Z UTC fino alla scadenza.The date is represented as the number of seconds from 1970-01-01T0:0:0Z UTC until the expiration time. Questo valore viene usato per determinare la durata dei token memorizzati nella cache.This value is used to determine the lifetime of cached tokens.
resourceresource L'URI ID app dell'API Web (risorsa protetta).The App ID URI of the web API (secured resource).
scopescope Autorizzazioni di rappresentazione concesse all'applicazione client.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.
refresh_tokenrefresh_token Token di aggiornamento di OAuth 2.0.An OAuth 2.0 refresh token. L'app può usare questo token per acquisire token di accesso aggiuntivi dopo la scadenza del token di accesso corrente.The app can use this token to acquire additional access tokens after the current access token expires. I token di aggiornamento hanno durata elevata e possono essere usati per mantenere l'accesso alle risorse per lunghi periodi di tempo.Refresh tokens are long-lived, and can be used to retain access to resources for extended periods of time.
id_tokenid_token Token JWT (Token Web JSON) non firmato.An unsigned JSON Web Token (JWT). L'app può decodificare i segmenti di questo token per richiedere informazioni sull'utente che ha eseguito l'accesso.The app can base64Url decode the segments of this token to request information about the user who signed in. L'app può memorizzare nella cache i valori e visualizzarli, ma non deve basarsi su di essi per eventuali autorizzazioni o limiti di sicurezza.The app can cache the values and display them, but it should not rely on them for any authorization or security boundaries.

Attestazioni nei token JWTJWT Token Claims

Il token JWT nel valore del parametro id_token può essere decodificato nelle attestazioni seguenti:The JWT token in the value of the id_token parameter can be decoded into the following claims:

{
 "typ": "JWT",
 "alg": "none"
}.
{
 "aud": "2d4d11a2-f814-46a7-890a-274a72a7309e",
 "iss": "https://sts.windows.net/7fe81447-da57-4385-becb-6de57f21477e/",
 "iat": 1388440863,
 "nbf": 1388440863,
 "exp": 1388444763,
 "ver": "1.0",
 "tid": "7fe81447-da57-4385-becb-6de57f21477e",
 "oid": "68389ae2-62fa-4b18-91fe-53dd109d74f5",
 "upn": "frank@contoso.com",
 "unique_name": "frank@contoso.com",
 "sub": "JWvYdCWPhhlpS1Zsf7yYUxShUwtUm5yzPmw_-jX3fHY",
 "family_name": "Miller",
 "given_name": "Frank"
}.

Per altre informazioni sui token Web JSON, vedere la bozza della specifica di JWT di IETF.For more information about JSON web tokens, see the JWT IETF draft specification. Per altre informazioni sui tipi di token e sulle attestazioni, vedere Token e tipi di attestazioni supportatiFor more information about the token types and claims, read Supported Token and Claim Types

Il parametro id_token include i tipi di attestazione seguenti:The id_token parameter includes the following claim types:

Tipo di attestazioneClaim type DESCRIZIONEDescription
audaud Destinatari del token.Audience of the token. Quando il token viene rilasciato a un'applicazione client, il destinatario è il client_id del client.When the token is issued to a client application, the audience is the client_id of the client.
expexp Scadenza.Expiration time. Data e ora in cui scade il token.The time when the token expires. Perché il token sia valido, il valore di data/ora corrente deve essere minore o uguale al valore di exp .For the token to be valid, the current date/time must be less than or equal to the exp value. L'ora è rappresentata come numero di secondi dal 1° gennaio 1970 (1970-01-01T0:0:0Z) UTC fino all'ora in cui scade la validità del token.The time is represented as the number of seconds from January 1, 1970 (1970-01-01T0:0:0Z) UTC until the time the token validity expires.
family_namefamily_name Cognome dell'utente.User’s last name or surname. Questo valore può essere visualizzato dall'applicazione.The application can display this value.
given_namegiven_name Nome dell'utente.User’s first name. Questo valore può essere visualizzato dall'applicazione.The application can display this value.
iatiat Data e ora di rilascio.Issued at time. Data e ora in cui il token JWT è stato rilasciato.The time when the JWT was issued. La data e l'ora sono rappresentate come numero di secondi dal 1 gennaio 1970 (1970-01-01T0:0:0Z) UTC fino alla data e all'ora in cui il token è stato rilasciato.The time is represented as the number of seconds from January 1, 1970 (1970-01-01T0:0:0Z) UTC until the time the token was issued.
ississ Identifica l'autorità di certificazione del token.Identifies the token issuer
nbfnbf Inizio validità.Not before time. Data e ora in cui il token diventa valido.The time when the token becomes effective. Perché il token sia valido, il valore di data/ora corrente deve essere maggiore o uguale al valore di nbf.For the token to be valid, the current date/time must be greater than or equal to the Nbf value. La data e l'ora sono rappresentate come numero di secondi dal 1 gennaio 1970 (1970-01-01T0:0:0Z) UTC fino alla data e all'ora in cui il token è stato rilasciato.The time is represented as the number of seconds from January 1, 1970 (1970-01-01T0:0:0Z) UTC until the time the token was issued.
oidoid Identificatore (ID) dell'oggetto utente in Azure AD.Object identifier (ID) of the user object in Azure AD.
subsub Identificatore del soggetto del token.Token subject identifier. È un identificatore permanente e non modificabile dell'utente descritto dal token.This is a persistent and immutable identifier for the user that the token describes. Usare questo valore nella logica di memorizzazione nella cache.Use this value in caching logic.
tidtid Identificatore (ID) del tenant di Azure AD che ha rilasciato il token.Tenant identifier (ID) of the Azure AD tenant that issued the token.
unique_nameunique_name Identificatore univoco che può essere visualizzato all'utente.A unique identifier for that can be displayed to the user. È in genere il nome dell'entità utente (UPN).This is usually a user principal name (UPN).
upnupn Nome dell'entità utente dell'utente.User principal name of the user.
verver Versione.Version. Versione del token JWT, in genere 1.0.The version of the JWT token, typically 1.0.

Risposta di erroreError response

Gli errori dell'endpoint di rilascio dei token sono codici di errore HTTP perché il client chiama direttamente l'endpoint di rilascio dei token.The token issuance endpoint errors are HTTP error codes, because the client calls the token issuance endpoint directly. Oltre al codice di stato HTTP, l'endpoint di rilascio dei token di Azure AD restituisce anche un documento JSON con gli oggetti che descrivono l'errore.In addition to the HTTP status code, the Azure AD token issuance endpoint also returns a JSON document with objects that describe the error.

Una risposta di errore di esempio può avere un aspetto simile al seguente:A sample error response could look like this:

{
  "error": "invalid_grant",
  "error_description": "AADSTS70002: Error validating credentials. AADSTS70008: The provided authorization code or refresh token is expired. Send a new interactive authorization request for this user and resource.\r\nTrace ID: 3939d04c-d7ba-42bf-9cb7-1e5854cdce9e\r\nCorrelation ID: a8125194-2dc8-4078-90ba-7b6592a7f231\r\nTimestamp: 2016-04-11 18:00:12Z",
  "error_codes": [
    70002,
    70008
  ],
  "timestamp": "2016-04-11 18:00:12Z",
  "trace_id": "3939d04c-d7ba-42bf-9cb7-1e5854cdce9e",
  "correlation_id": "a8125194-2dc8-4078-90ba-7b6592a7f231"
}
ParametroParameter DESCRIZIONEDescription
errorerror Stringa di codice di errore che può essere usata per classificare i tipi di errori che si verificano e correggerli.An error code string that can be used to classify types of errors that occur, and can be used to react to errors.
error_descriptionerror_description Messaggio di errore specifico che consente a uno sviluppatore di identificare la causa principale di un errore di autenticazione.A specific error message that can help a developer identify the root cause of an authentication error.
error_codeserror_codes Elenco dei codici di errore specifici del servizio token di sicurezza utile per la diagnostica.A list of STS-specific error codes that can help in diagnostics.
timestamptimestamp Ora in cui si è verificato l'errore.The time at which the error occurred.
trace_idtrace_id Identificatore univoco per la richiesta utile per la diagnostica.A unique identifier for the request that can help in diagnostics.
correlation_idcorrelation_id Identificatore univoco per la richiesta utile per la diagnostica tra i componenti.A unique identifier for the request that can help in diagnostics across components.

Codici di stato HTTPHTTP status codes

La tabella seguente elenca i codici di stato HTTP restituiti dall'endpoint di rilascio dei token.The following table lists the HTTP status codes that the token issuance endpoint returns. In alcuni casi il codice di errore è sufficiente a descrivere la risposta, ma in caso di errori sarà necessario analizzare il documento JSON associato ed esaminare il codice errore.In some cases, the error code is sufficient to describe the response, but if there are errors, you need to parse the accompanying JSON document and examine its error code.

Codice HTTPHTTP Code DESCRIZIONEDescription
400400 Codice HTTP predefinito.Default HTTP code. Usato nella maggior parte dei casi, è in genere causato da una richiesta in formato non valido.Used in most cases and is typically due to a malformed request. Correggere e inviare di nuovo la richiesta.Fix and resubmit the request.
401401 Autenticazione non riuscita.Authentication failed. Ad esempio, nella richiesta manca il parametro client_secret.For example, the request is missing the client_secret parameter.
403403 Autorizzazione non riuscita.Authorization failed. Ad esempio, l'utente non ha l'autorizzazione per accedere alla risorsa.For example, the user does not have permission to access the resource.
500500 Si è verificato un errore interno nel servizio.An internal error has occurred at the service. ripetere la richiesta.Retry the request.

Codici per gli errori degli endpoint di tokenError codes for token endpoint errors

Codice di erroreError Code DESCRIZIONEDescription Azione clientClient Action
invalid_requestinvalid_request Errore del protocollo, ad esempio un parametro obbligatorio mancante.Protocol error, such as a missing required parameter. Correggere e inviare di nuovo la richiesta.Fix and resubmit the request
invalid_grantinvalid_grant Il codice di autorizzazione non è valido o è scaduto.The authorization code is invalid or has expired. Provare una nuova richiesta all'endpoint /authorizeTry a new request to the /authorize endpoint
unauthorized_clientunauthorized_client Il client autenticato non è autorizzato a usare questo tipo di concessione dell'autorizzazione.The authenticated client is not authorized to use this authorization grant type. Si verifica in genere quando l'applicazione client non è registrata in Azure AD o non è stata aggiunta al tenant di Azure AD dell'utente.This usually occurs when the client application is not registered in Azure AD or is not added to the user's Azure AD tenant. L'applicazione può chiedere all'utente di installare l'applicazione e di aggiungerla ad Azure AD.The application can prompt the user with instruction for installing the application and adding it to Azure AD.
invalid_clientinvalid_client Autenticazione client non riuscita.Client authentication failed. Credenziali del client non valide.The client credentials are not valid. Per risolvere il problema, l'amministratore applicazione aggiorna le credenziali.To fix, the application administrator updates the credentials.
unsupported_grant_typeunsupported_grant_type Il server di autorizzazione non supporta il tipo di concessione dell'autorizzazione.The authorization server does not support the authorization grant type. Modificare il tipo di concessione nella richiesta.Change the grant type in the request. Questo tipo di errore dovrebbe verificarsi solo durante lo sviluppo ed essere rilevato durante il test iniziale.This type of error should occur only during development and be detected during initial testing.
invalid_resourceinvalid_resource La risorsa di destinazione non è valida perché non esiste, Azure AD non riesce a trovarla o non è attualmente configurata.The target resource is invalid because it does not exist, Azure AD cannot find it, or it is not correctly configured. Indica che la risorsa, se presente, non è stata configurata nel tenant.This indicates the resource, if it exists, has not been configured in the tenant. L'applicazione può chiedere all'utente di installare l'applicazione e di aggiungerla ad Azure AD.The application can prompt the user with instruction for installing the application and adding it to Azure AD.
interaction_requiredinteraction_required La richiesta richiede l'interazione dell'utente.The request requires user interaction. Ad esempio, è necessario un passaggio di autenticazione aggiuntivo.For example, an additional authentication step is required. Invece di una richiesta non interattiva, provare di nuovo con una richiesta di autorizzazione interattiva per la stessa risorsa.Instead of a non-interactive request, retry with an interactive authorization request for the same resource.
temporarily_unavailabletemporarily_unavailable Il server è temporaneamente troppo occupato per gestire la richiesta.The server is temporarily too busy to handle the request. ripetere la richiesta.Retry the request. L'applicazione client può comunicare all'utente che la risposta è stata ritardata a causa di una condizione temporanea.The client application might explain to the user that its response is delayed due to a temporary condition.

Usare il token di accesso per accedere alla risorsaUse the access token to access the resource

Dopo aver ottenuto un access_token è possibile usarlo in richieste alle API Web includendolo nell'intestazione Authorization.Now that you've successfully acquired an access_token, you can use the token in requests to Web APIs, by including it in the Authorization header. La specifica RFC 6750 illustra come usare i token di connessione nelle richieste HTTP per accedere a risorse protette.The RFC 6750 specification explains how to use bearer tokens in HTTP requests to access protected resources.

Richiesta di esempioSample request

GET /data HTTP/1.1
Host: service.contoso.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1THdqcHdBSk9NOW4tQSJ9.eyJhdWQiOiJodHRwczovL3NlcnZpY2UuY29udG9zby5jb20vIiwiaXNzIjoiaHR0cHM6Ly9zdHMud2luZG93cy5uZXQvN2ZlODE0NDctZGE1Ny00Mzg1LWJlY2ItNmRlNTdmMjE0NzdlLyIsImlhdCI6MTM4ODQ0MDg2MywibmJmIjoxMzg4NDQwODYzLCJleHAiOjEzODg0NDQ3NjMsInZlciI6IjEuMCIsInRpZCI6IjdmZTgxNDQ3LWRhNTctNDM4NS1iZWNiLTZkZTU3ZjIxNDc3ZSIsIm9pZCI6IjY4Mzg5YWUyLTYyZmEtNGIxOC05MWZlLTUzZGQxMDlkNzRmNSIsInVwbiI6ImZyYW5rbUBjb250b3NvLmNvbSIsInVuaXF1ZV9uYW1lIjoiZnJhbmttQGNvbnRvc28uY29tIiwic3ViIjoiZGVOcUlqOUlPRTlQV0pXYkhzZnRYdDJFYWJQVmwwQ2o4UUFtZWZSTFY5OCIsImZhbWlseV9uYW1lIjoiTWlsbGVyIiwiZ2l2ZW5fbmFtZSI6IkZyYW5rIiwiYXBwaWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctODkwYS0yNzRhNzJhNzMwOWUiLCJhcHBpZGFjciI6IjAiLCJzY3AiOiJ1c2VyX2ltcGVyc29uYXRpb24iLCJhY3IiOiIxIn0.JZw8jC0gptZxVC-7l5sFkdnJgP3_tRjeQEPgUn28XctVe3QqmheLZw7QVZDPCyGycDWBaqy7FLpSekET_BftDkewRhyHk9FW_KeEz0ch2c3i08NGNDbr6XYGVayNuSesYk5Aw_p3ICRlUV1bqEwk-Jkzs9EEkQg4hbefqJS6yS1HoV_2EsEhpd_wCQpxK89WPs3hLYZETRJtG5kvCCEOvSHXmDE6eTHGTnEgsIk--UlPe275Dvou4gEAwLofhLDQbMSjnlV5VLsjimNBVcSRFShoxmQwBJR_b2011Y5IuD6St5zPnzruBbZYkGNurQK63TJPWmRd3mbJsGM0mf3CUQ

Risposta di erroreError Response

Le risorse protette che implementano RFC 6750 rilasciano codici di stato HTTP.Secured resources that implement RFC 6750 issue HTTP status codes. Se la richiesta non include le credenziali di autenticazione o è priva del token, la risposta include un'intestazione WWW-Authenticate .If the request does not include authentication credentials or is missing the token, the response includes an WWW-Authenticate header. Quando una richiesta non riesce, il server delle risorse risponde con un codice di stato HTTP e un codice di errore.When a request fails, the resource server responds with the HTTP status code and an error code.

L'esempio seguente illustra una risposta non riuscita quando la richiesta del client non include il token di connessione:The following is an example of an unsuccessful response when the client request does not include the bearer token:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer authorization_uri="https://login.microsoftonline.com/contoso.com/oauth2/authorize",  error="invalid_token",  error_description="The access token is missing.",

Parametri dell'erroreError parameters

ParametroParameter DESCRIZIONEDescription
authorization_uriauthorization_uri URI (endpoint fisico) del server di autorizzazione.The URI (physical endpoint) of the authorization server. Questo valore viene usato anche come chiave di ricerca per ottenere altre informazioni sul server da un endpoint di individuazione.This value is also used as a lookup key to get more information about the server from a discovery endpoint.

Il client deve convalidare l'attendibilità del server di autorizzazione.The client must validate that the authorization server is trusted. Quando la risorsa è protetta da Azure AD, è sufficiente verificare che l'URL inizi con https://login.microsoftonline.com o un altro nome host supportato da Azure AD.When the resource is protected by Azure AD, it is sufficient to verify that the URL begins with https://login.microsoftonline.com or another hostname that Azure AD supports. Una risorsa specifica del tenant deve sempre restituire un URI di autorizzazione specifico del tenant.A tenant-specific resource should always return a tenant-specific authorization URI.

errorerror Valore del codice di errore definito nella sezione 5.2 del framework di autorizzazione di OAuth 2.0.An error code value defined in Section 5.2 of the OAuth 2.0 Authorization Framework.
error_descriptionerror_description Descrizione più dettagliata dell'errore.A more detailed description of the error. Questo messaggio non vuole essere semplice da usare.This message is not intended to be end-user friendly.
resource_idresource_id Restituisce l'identificatore univoco della risorsa.Returns the unique identifier of the resource. L'applicazione client può usare questo identificatore come valore del parametro resource quando richiede un token per la risorsa.The client application can use this identifier as the value of the resource parameter when it requests a token for the resource.

È importante per l'applicazione client verificare questo valore, in caso contrario un servizio dannoso potrebbe riuscire ad attuare un attacco di tipo elevazione dei privilegiIt is important for the client application to verify this value, otherwise a malicious service might be able to induce an elevation-of-privileges attack

La strategia consigliata per prevenire un attacco consiste nel verificare che resource_id corrisponda alla base dell'URL dell'API Web a cui si accede.The recommended strategy for preventing an attack is to verify that the resource_id matches the base of the web API URL that being accessed. Ad esempio, se si accede ad https://service.contoso.com/data, resource_id può essere htttps://service.contoso.com/.For example, if https://service.contoso.com/data is being accessed, the resource_id can be htttps://service.contoso.com/. L'applicazione client deve rifiutare un resource_id che non inizia con l'URL di base a meno che non esista un modo alternativo affidabile per verificare l'ID.The client application must reject a resource_id that does not begin with the base URL unless there is a reliable alternate way to verify the id.

Codici errore dello schema di connessioneBearer scheme error codes

La specifica RFC 6750 definisce gli errori seguenti per le risorse che usano l'intestazione WWW-Authenticate e lo schema di connessione nella risposta.The RFC 6750 specification defines the following errors for resources that use the WWW-Authenticate header and Bearer scheme in the response.

Codice di stato HTTPHTTP Status Code Codice di erroreError Code DESCRIZIONEDescription Azione clientClient Action
400400 invalid_requestinvalid_request Richiesta non ben formata.The request is not well-formed. Ad esempio, potrebbe mancare un parametro o essere usato lo stesso parametro due volte.For example, it might be missing a parameter or using the same parameter twice. Correggere l'errore e ripetere la richiesta.Fix the error and retry the request. Questo tipo di errore dovrebbe verificarsi solo durante lo sviluppo ed essere rilevato nel test iniziale.This type of error should occur only during development and be detected in initial testing.
401401 invalid_tokeninvalid_token Il token di accesso è mancante, non valido o è stato revocato.The access token is missing, invalid, or is revoked. Il valore del parametro error_description fornisce dettagli aggiuntivi.The value of the error_description parameter provides additional detail. Richiedere un nuovo token al server di autorizzazione.Request a new token from the authorization server. Se il nuovo token ha esito negativo, si è verificato un errore imprevisto.If the new token fails, an unexpected error has occurred. Inviare un messaggio di errore all'utente e riprovare dopo alcuni ritardi casuali.Send an error message to the user and retry after random delays.
403403 insufficient_scopeinsufficient_scope Il token di accesso non contiene le autorizzazioni di rappresentazione necessarie per accedere alla risorsa.The access token does not contain the impersonation permissions required to access the resource. Inviare una nuova richiesta di autorizzazione all'endpoint di autorizzazione.Send a new authorization request to the authorization endpoint. Se la risposta contiene il parametro scope, usare il valore di scope nella richiesta alla risorsa.If the response contains the scope parameter, use the scope value in the request to the resource.
403403 insufficient_accessinsufficient_access Il soggetto del token non ha le autorizzazioni necessarie per accedere alla risorsa.The subject of the token does not have the permissions that are required to access the resource. Chiedere all'utente di usare un account diverso o di richiedere le autorizzazioni alla risorsa specificata.Prompt the user to use a different account or to request permissions to the specified resource.

Aggiornamento dei token di accessoRefreshing the access tokens

I token di accesso hanno breve durata ed è necessario aggiornarli dopo la scadenza per continuare ad accedere alle risorse.Access Tokens are short-lived and must be refreshed after they expire to continue accessing resources. È possibile aggiornare access_token inviando un'altra richiesta POST all'endpoint /token e specificando refresh_token anziché il valore code.You can refresh the access_token by submitting another POST request to the /token endpoint, but this time providing the refresh_token instead of the code.

I token di aggiornamento non hanno una durata specificata.Refresh tokens do not have specified lifetimes. La durata dei token di aggiornamento è in genere relativamente lunga.Typically, the lifetimes of refresh tokens are relatively long. In alcuni casi, tuttavia, i token di aggiornamento scadono, vengono revocati o non hanno privilegi sufficienti per l'azione desiderata.However, in some cases, refresh tokens expire, are revoked, or lack sufficient privileges for the desired action. L'applicazione deve prevedere e gestire correttamente gli errori restituiti dall'endpoint di rilascio del token.Your application needs to expect and handle errors returned by the token issuance endpoint correctly.

Quando si riceve una risposta con un errore relativo al token di aggiornamento, rimuovere il token di aggiornamento corrente e richiedere un nuovo codice di autorizzazione o un nuovo token di accesso.When you receive a response with a refresh token error, discard the current refresh token and request a new authorization code or access token. In particolare, se si usa un token di aggiornamento nel flusso di concessione del codice di autorizzazione e si riceve una risposta con i codici di errore interaction_required o invalid_grant, rimuovere il token di aggiornamento e richiedere un nuovo codice di autorizzazione.In particular, when using a refresh token in the Authorization Code Grant flow, if you receive a response with the interaction_required or invalid_grant error codes, discard the refresh token and request a new authorization code.

Una richiesta di esempio all'endpoint specifico del tenant (è possibile usare anche l'endpoint common) per ottenere un nuovo token di accesso usando un token di aggiornamento si presenta come segue:A sample request to the tenant-specific endpoint (you can also use the common endpoint) to get a new access token using a refresh token looks like this:

// Line breaks for legibility only

POST /{tenant}/oauth2/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&refresh_token=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq...
&grant_type=refresh_token
&resource=https%3A%2F%2Fservice.contoso.com%2F
&client_secret=JqQX2PNo9bpM0uEihUPzyrh    // NOTE: Only required for web apps

Risposta con esito positivoSuccessful response

Una risposta token con esito positivo ha un aspetto simile al seguente:A successful token response will look like:

{
  "token_type": "Bearer",
  "expires_in": "3600",
  "expires_on": "1460404526",
  "resource": "https://service.contoso.com/",
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1THdqcHdBSk9NOW4tQSJ9.eyJhdWQiOiJodHRwczovL3NlcnZpY2UuY29udG9zby5jb20vIiwiaXNzIjoiaHR0cHM6Ly9zdHMud2luZG93cy5uZXQvN2ZlODE0NDctZGE1Ny00Mzg1LWJlY2ItNmRlNTdmMjE0NzdlLyIsImlhdCI6MTM4ODQ0MDg2MywibmJmIjoxMzg4NDQwODYzLCJleHAiOjEzODg0NDQ3NjMsInZlciI6IjEuMCIsInRpZCI6IjdmZTgxNDQ3LWRhNTctNDM4NS1iZWNiLTZkZTU3ZjIxNDc3ZSIsIm9pZCI6IjY4Mzg5YWUyLTYyZmEtNGIxOC05MWZlLTUzZGQxMDlkNzRmNSIsInVwbiI6ImZyYW5rbUBjb250b3NvLmNvbSIsInVuaXF1ZV9uYW1lIjoiZnJhbmttQGNvbnRvc28uY29tIiwic3ViIjoiZGVOcUlqOUlPRTlQV0pXYkhzZnRYdDJFYWJQVmwwQ2o4UUFtZWZSTFY5OCIsImZhbWlseV9uYW1lIjoiTWlsbGVyIiwiZ2l2ZW5fbmFtZSI6IkZyYW5rIiwiYXBwaWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctODkwYS0yNzRhNzJhNzMwOWUiLCJhcHBpZGFjciI6IjAiLCJzY3AiOiJ1c2VyX2ltcGVyc29uYXRpb24iLCJhY3IiOiIxIn0.JZw8jC0gptZxVC-7l5sFkdnJgP3_tRjeQEPgUn28XctVe3QqmheLZw7QVZDPCyGycDWBaqy7FLpSekET_BftDkewRhyHk9FW_KeEz0ch2c3i08NGNDbr6XYGVayNuSesYk5Aw_p3ICRlUV1bqEwk-Jkzs9EEkQg4hbefqJS6yS1HoV_2EsEhpd_wCQpxK89WPs3hLYZETRJtG5kvCCEOvSHXmDE6eTHGTnEgsIk--UlPe275Dvou4gEAwLofhLDQbMSjnlV5VLsjimNBVcSRFShoxmQwBJR_b2011Y5IuD6St5zPnzruBbZYkGNurQK63TJPWmRd3mbJsGM0mf3CUQ",
  "refresh_token": "AwABAAAAv YNqmf9SoAylD1PycGCB90xzZeEDg6oBzOIPfYsbDWNf621pKo2Q3GGTHYlmNfwoc-OlrxK69hkha2CF12azM_NYhgO668yfcUl4VBbiSHZyd1NVZG5QTIOcbObu3qnLutbpadZGAxqjIbMkQ2bQS09fTrjMBtDE3D6kSMIodpCecoANon9b0LATkpitimVCrl PM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4rTfgV29ghDOHRc2B-C_hHeJaJICqjZ3mY2b_YNqmf9SoAylD1PycGCB90xzZeEDg6oBzOIPfYsbDWNf621pKo2Q3GGTHYlmNfwoc-OlrxK69hkha2CF12azM_NYhgO668yfmVCrl-NyfN3oyG4ZCWu18M9-vEou4Sq-1oMDzExgAf61noxzkNiaTecM-Ve5cq6wHqYQjfV9DOz4lbceuYCAA"
}
ParametroParameter DESCRIZIONEDescription
token_typetoken_type Tipo di token.The token type. L'unico valore supportato è bearer.The only supported value is bearer.
expires_inexpires_in Durata residua del token, in secondi.The remaining lifetime of the token in seconds. Un valore tipico è 3600 (un'ora).A typical value is 3600 (one hour).
expires_onexpires_on Data e ora in cui scadrà il token.The date and time on which the token expires. La data è rappresentata come numero di secondi da 1970-01-01T0:0:0Z UTC fino alla scadenza.The date is represented as the number of seconds from 1970-01-01T0:0:0Z UTC until the expiration time.
resourceresource Identifica la risorsa protetta a cui il token di accesso consente di accedere.Identifies the secured resource that the access token can be used to access.
scopescope Autorizzazioni di rappresentazione concesse all'applicazione client nativa.Impersonation permissions granted to the native client application. L'autorizzazione predefinita è user_impersonation.The default permission is user_impersonation. Il proprietario della risorsa di destinazione può registrare valori alternativi in Azure AD.The owner of the target resource can register alternate values in Azure AD.
access_tokenaccess_token Nuovo token di accesso che è stato richiesto.The new access token that was requested.
refresh_tokenrefresh_token Nuovo refresh_token OAuth 2.0 che può essere usato per richiedere nuovi token di accesso alla scadenza del token di questa risposta.A new OAuth 2.0 refresh_token that can be used to request new access tokens when the one in this response expires.

Risposta di erroreError response

Una risposta di errore di esempio può avere un aspetto simile al seguente:A sample error response could look like this:

{
  "error": "invalid_resource",
  "error_description": "AADSTS50001: The application named https://foo.microsoft.com/mail.read was not found in the tenant named 295e01fc-0c56-4ac3-ac57-5d0ed568f872. This can happen if the application has not been installed by the administrator of the tenant or consented to by any user in the tenant. You might have sent your authentication request to the wrong tenant.\r\nTrace ID: ef1f89f6-a14f-49de-9868-61bd4072f0a9\r\nCorrelation ID: b6908274-2c58-4e91-aea9-1f6b9c99347c\r\nTimestamp: 2016-04-11 18:59:01Z",
  "error_codes": [
    50001
  ],
  "timestamp": "2016-04-11 18:59:01Z",
  "trace_id": "ef1f89f6-a14f-49de-9868-61bd4072f0a9",
  "correlation_id": "b6908274-2c58-4e91-aea9-1f6b9c99347c"
}
ParametroParameter DESCRIZIONEDescription
errorerror Stringa di codice di errore che può essere usata per classificare i tipi di errori che si verificano e correggerli.An error code string that can be used to classify types of errors that occur, and can be used to react to errors.
error_descriptionerror_description Messaggio di errore specifico che consente a uno sviluppatore di identificare la causa principale di un errore di autenticazione.A specific error message that can help a developer identify the root cause of an authentication error.
error_codeserror_codes Elenco dei codici di errore specifici del servizio token di sicurezza utile per la diagnostica.A list of STS-specific error codes that can help in diagnostics.
timestamptimestamp Ora in cui si è verificato l'errore.The time at which the error occurred.
trace_idtrace_id Identificatore univoco per la richiesta utile per la diagnostica.A unique identifier for the request that can help in diagnostics.
correlation_idcorrelation_id Identificatore univoco per la richiesta utile per la diagnostica tra i componenti.A unique identifier for the request that can help in diagnostics across components.

Per una descrizione dei codici di errore e l'azione consigliata per il client, vedere Codici per gli errori degli endpoint di token.For a description of the error codes and the recommended client action, see Error codes for token endpoint errors.