Protocolli della versione 2.0: flusso del codice di autorizzazione di OAuth 2.0v2.0 Protocols - OAuth 2.0 Authorization Code Flow

La concessione del codice di autorizzazione OAuth 2.0 può essere utilizzata nelle app che vengono installate su un dispositivo per ottenere l'accesso alle risorse protette, come l'API web.The OAuth 2.0 authorization code grant can be used in apps that are installed on a device to gain access to protected resources, such as web APIs. Usando l'implementazione di OAuth 2.0 definita in Modello app 2.0, è possibile aggiungere i criteri e l'API di accesso alle applicazioni desktop e mobili.Using the app model v2.0 's implementation of OAuth 2.0, you can add sign in and API access to your mobile and desktop apps. Questa guida, indipendente dal linguaggio, descrive come inviare e ricevere messaggi HTTP senza usare una delle librerie di autenticazione open source di Azure.This guide is language-independent, and describes how to send and receive HTTP messages without using any of the Azure open-source authentication libraries.

Nota

Non tutti gli scenari e le funzionalità di Azure Active Directory sono supportati dall'endpoint 2.0.Not all Azure Active Directory scenarios & features are supported by the v2.0 endpoint. Per determinare se è necessario usare l'endpoint v2.0, leggere le informazioni sulle limitazioni v2.0.To determine if you should use the v2.0 endpoint, read about v2.0 limitations.

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 the majority of app types, including web apps and natively installed apps. Tale flusso consente alle app di acquisire in modo sicuro i token di accesso che possono essere usati per accedere alle risorse protette tramite endpoint v2.0.The flow enables apps to securely acquire access_tokens that can be used to access resources secured by the v2.0 endpoint.

Diagramma di protocolloProtocol diagram

In generale, l'intero flusso di autenticazione per un'applicazione nativa/mobile ha un aspetto analogo al seguente:At a high level, the entire authentication flow for a native/mobile 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:

// Line breaks for legibility only

https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&response_type=code
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=query
&scope=openid%20offline_access%20https%3A%2F%2Fgraph.microsoft.com%2Fmail.read
&state=12345

Suggerimento

Fare clic sul collegamento seguente per eseguire questa richiesta.Click the link below to execute this request! Dopo l'accesso, il browser deve essere reindirizzato a https://localhost/myapp/ con un code nella barra degli indirizzi.After signing in, your browser should be redirected to https://localhost/myapp/ with a code in the address bar. https://login.microsoftonline.com/common/oauth2/v2.0/authorize...https://login.microsoftonline.com/common/oauth2/v2.0/authorize...

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 common, organizations, consumers e gli identificatori del tenant.The allowed values are common, organizations, consumers, and tenant identifiers. Per altre informazioni, vedere le nozioni di base sul protocollo.For more detail, see protocol basics.
client_idclient_id Obbligatoriarequired ID applicazione che il portale di registrazione (apps.dev.microsoft.com) ha assegnato all'app.The Application D that the registration portal (apps.dev.microsoft.com) assigned your app.
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 https://login.microsoftonline.com/common/oauth2/nativeclient.For native & mobile apps, you should use the default value of https://login.microsoftonline.com/common/oauth2/nativeclient.
scopescope Obbligatoriarequired Elenco separato da spazi di ambiti a cui si vuole che l'utente dia il consenso.A space-separated list of scopes that you want the user to consent to.
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.
statestate Consigliatorecommended Valore incluso nella richiesta che verrà restituito anche nella risposta del token.A value included in the request that will also be returned in the token response. Può trattarsi di una stringa di qualsiasi contenuto.It can be a string of any content that you wish. 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. Questo valore può essere usato anche 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 value can also encode information about the user's state in the app before the authentication request occurred, such as the page or view they were on.
promptprompt Facoltativooptional Indica il tipo di interazione obbligatoria dell'utente.Indicates the type of user interaction that is required. Gli unici valori validi al momento sono "login", "none" e "consent".The only valid values at this time are 'login', 'none', and 'consent'. prompt=login forza l'utente a immettere le sue credenziali alla richiesta, negando l'accesso Single Sign-On.prompt=login will force the user to enter their credentials on that request, negating single-sign on. prompt=none è l'opposto: garantisce che all'utente non venga presentata alcuna richiesta interattiva.prompt=none is the opposite - it will ensure that the user is not presented with any interactive prompt whatsoever. Se la richiesta non può essere completata automaticamente tramite Single-Sign-On, l'endpoint 2.0 restituirà un errore.If the request cannot be completed silently via single-sign on, the v2.0 endpoint will return an error. prompt=consent attiverà la finestra di dialogo di consenso di OAuth dopo l'accesso dell'utente, che chiede all'utente di concedere le autorizzazioni all'app.prompt=consent will trigger the OAuth consent dialog after the user signs in, asking the user to grant permissions to the app.
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 will use this parameter during re-authentication, having already extracted the username from a previous sign-in using the preferred_username claim.
domain_hintdomain_hint Facoltativooptional Può essere uno di consumers o organizations.Can be one of consumers or organizations. Se incluso, non verrà eseguito il processo di individuazione basato sulla posta elettronica a cui viene sottoposto l'utente nella pagina di accesso della versione 2.0. Questo comporta un'esperienza utente leggermente semplificata.If included, it will skip the email-based discovery process that user goes through on the v2.0 sign-in page, leading to a slightly more streamlined user experience. Le app usano spesso questo parametro durante la riautenticazione, estraendo tid da un accesso precedente.Often apps will use this parameter during re-authentication, by extracting the tid from a previous sign-in. Se il valore dell'attestazione tid è 9188040d-6c67-4c5b-b112-36a304b66dad, usare domain_hint=consumers.If the tid claim value is 9188040d-6c67-4c5b-b112-36a304b66dad, you should use domain_hint=consumers. In caso contrario, usare domain_hint=organizations.Otherwise, use domain_hint=organizations.
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 v2.0 supporta sia plain che S256.Azure AAD v2.0 supports both plain and S256. Per altre informazioni, vedere il PKCE RFC.For more information, see the PKCE RFC.
code_challengecode_challenge Facoltativooptional Usato per proteggere i privilegi concessi sui codici di autorizzazione tramite la chiave di prova per Code Exchange (PKCE) da un client nativo.Used to secure authorization code grants via Proof Key for Code Exchange (PKCE) from a native 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.

A questo punto, all'utente viene chiesto di immettere le credenziali e completare l'autenticazione.At this point, the user will be asked to enter their credentials and complete the authentication. L'endpoint 2.0 assicura anche che l'utente abbia fornito il consenso per le autorizzazioni indicate nel parametro di query scope .The v2.0 endpoint will also ensure that the user has consented to the permissions indicated in the scope query parameter. Se l'utente non ha acconsentito a nessuna di queste autorizzazioni, l'endpoint chiederà all'utente di fornire il consenso per le autorizzazioni obbligatorie.If the user has not consented to any of those permissions, it will ask the user to consent to the required permissions. Questo articolo contiene informazioni dettagliate su autorizzazioni, consenso e app multi-tenant.Details of permissions, consent, and multi-tenant apps are provided here.

Dopo che l'utente viene autenticato e fornisce il consenso, l'endpoint 2.0 restituisce una risposta all'app nell'URI redirect_uri, usando il metodo specificato nel parametro response_mode.Once the user authenticates and grants consent, the v2.0 endpoint will return a response to your app at the indicated redirect_uri, using the method specified in the response_mode parameter.

Risposta con esito positivoSuccessful response

Una risposta con esito positivo che usa response_mode=query ha un aspetto simile al seguente:A successful response using response_mode=query looks like:

GET https://login.microsoftonline.com/common/oauth2/nativeclient?
code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&state=12345
ParametroParameter DESCRIZIONEDescription
codecode Codice di autorizzazione richiesto dall'app.The authorization_code that the app requested. L'app può usare il codice di autorizzazione per richiedere un token di accesso per la risorsa di destinazione.The app can use the authorization code to request an access token for the target resource. I codici di autorizzazione hanno una durata molto breve, in genere scadono dopo circa 10 minuti.Authorization_codes are very short lived, typically they expire after about 10 minutes.
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. L'app deve verificare che i valori dello stato nella richiesta e nella risposta siano identici.The app should verify that the state values in the request and response are identical.

Risposta di erroreError response

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

GET https://login.microsoftonline.com/common/oauth2/nativeclient?
error=access_denied
&error_description=the+user+canceled+the+authentication
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.

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 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. Questo errore 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 error 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 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 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. Questo errore indica che la risorsa, se presente, non è stata configurata nel tenant.This error 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.

Richiedere un token di accessoRequest an access token

Dopo avere ottenuto un codice di autorizzazione e l'autorizzazione dell'utente, è possibile riscattare il valore code per un access_token per la risorsa desiderata.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. A tale scopo, inviare una richiesta POST all'endpoint /token:Do this by sending a POST request to the /token endpoint:

// Line breaks for legibility only

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

client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read
&code=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq3n8b2JRLk4OxVXr...
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&grant_type=authorization_code
&client_secret=JqQX2PNo9bpM0uEihUPzyrh    // NOTE: Only required for web apps

Suggerimento

Provare a eseguire la richiesta in Postman.Try executing this request in Postman! Non dimenticare di sostituire code. Eseguire in Postman(Don't forget to replace the code) Run in Postman

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 common, organizations, consumers e gli identificatori del tenant.The allowed values are common, organizations, consumers, and tenant identifiers. Per altre informazioni, vedere le nozioni di base sul protocollo.For more detail, see protocol basics.
client_idclient_id Obbligatoriarequired ID applicazione che il portale di registrazione (apps.dev.microsoft.com) ha assegnato all'app.The Application ID that the registration portal (apps.dev.microsoft.com) assigned your app.
grant_typegrant_type Obbligatoriarequired Deve essere authorization_code per il flusso del codice di autorizzazione.Must be authorization_code for the authorization code flow.
scopescope Obbligatoriarequired Elenco di ambiti separati da spazi.A space-separated list of scopes. Gli ambiti richiesti in questa sezione devono essere equivalenti agli ambiti richiesti nella prima sezione o un sottoinsieme di questi ultimi.The scopes requested in this leg must be equivalent to or a subset of the scopes requested in the first leg. Se gli ambiti specificati in questa richiesta si estendono su più server di risorse, l'endpoint v2.0 restituirà un token per la risorsa specificata nel primo ambito.If the scopes specified in this request span multiple resource server, then the v2.0 endpoint will return a token for the resource specified in the first scope. Per una spiegazione più dettagliata degli ambiti, fare riferimento all'argomento relativo ad autorizzazioni, consenso e ambiti.For a more detailed explanation of scopes, refer to permissions, consent, and scopes.
codecode Obbligatoriarequired Codice di autorizzazione acquisito durante la prima sezione del flusso.The authorization_code that you acquired in the first leg of the flow.
redirect_uriredirect_uri Obbligatoriarequired Stesso valore redirect_uri usato per acquisire il codice di autorizzazione.The same redirect_uri value that was used to acquire the authorization_code.
client_secretclient_secret Obbligatorio per app Webrequired for web apps Segreto dell'applicazione creato per l'app nel portale di registrazione delle app.The application secret that you created in the app registration portal for your app. È consigliabile non usarlo in un'app nativa, perché i segreti client non possono essere archiviati in modo affidabile nei dispositivi.It should not be used in a native app, because client_secrets cannot be reliably stored on devices. Il segreto è obbligatorio per le app Web e le API Web che possono archiviare in modo sicuro il segreto client sul lato server.It is required for web apps and web APIs, which have the ability to store the client_secret securely on the server side.
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

Risposta con esito positivoSuccessful response

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

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
    "token_type": "Bearer",
    "expires_in": 3599,
    "scope": "https%3A%2F%2Fgraph.microsoft.com%2Fmail.read",
    "refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
    "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctOD...",
}
ParametroParameter DESCRIZIONEDescription
access_tokenaccess_token Token di accesso richiesto.The requested access token. 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
expires_inexpires_in Validità del token di accesso (espressa in secondi).How long the access token is valid (in seconds).
scopescope Ambiti per i quali il token di accesso è valido.The scopes that the access_token is valid for.
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 acquire additional access tokens after the current access token expires. I token di aggiornamento hanno una 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. Per informazioni dettagliate, consultare l'argomento Anteprima Azure AD B2C: Riferimento al Token.For more detail, refer to the v2.0 token reference.
Nota: viene fornito solo è stato richiesto l'ambito offline_access.Note: Only provided if offline_access scope was requested.
id_tokenid_token Token JWT (Token Web JSON) non firmato.An unsigned JSON Web Token (JWT). L'app può eseguire la decodifica base64Url dei 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. Per altre informazioni sui token ID, vedere le informazioni di riferimento sui token dell'endpoint v2.0.For more information about id_tokens, see the v2.0 endpoint token reference.
Nota: viene fornito solo è stato richiesto l'ambito openid.Note: Only provided if openid scope was requested.

Risposta di erroreError response

Le risposte di errore hanno un aspetto simile al seguente:Error responses will look like:

{
  "error": "invalid_scope",
  "error_description": "AADSTS70011: The provided value for the input parameter 'scope' is not valid. The scope https://foo.microsoft.com/mail.read is not valid.\r\nTrace ID: 255d1aef-8c98-452f-ac51-23d051240864\r\nCorrelation ID: fb3d2015-bc17-4bb9-bb85-30c5cf1aaaa7\r\nTimestamp: 2016-01-09 02:02:12Z",
  "error_codes": [
    70011
  ],
  "timestamp": "2016-01-09 02:02:12Z",
  "trace_id": "255d1aef-8c98-452f-ac51-23d051240864",
  "correlation_id": "fb3d2015-bc17-4bb9-bb85-30c5cf1aaaa7"
}
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 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 o PKCE non è valido o è scaduto.The authorization code or PKCE code verifier is invalid or has expired. Provare una nuova richiesta per l'endpoint /authorize e verificare che il parametro code_verifier sia corretto.Try a new request to the /authorize endpoint and verify that the code_verifier parameter was correct.
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. Ripetere la richiesta con la stessa risorsa.Retry the request with 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 accessoUse the access token

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:

Suggerimento

Eseguire la richiesta in Postman.Execute this request in Postman! Sostituire prima l'intestazione Authorization. Eseguire in Postman(Replace the Authorization header first) Run in Postman

GET /v1.0/me/messages
Host: https://graph.microsoft.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...

Aggiornare il token di accessoRefresh the access token

I token di accesso hanno breve durata ed è quindi necessario aggiornarli dopo la scadenza per continuare ad accedere alle risorse.Access_tokens are short lived, and you must refresh them after they expire to continue accessing resources. A tale scopo, inviare un'altra richiesta POST all'endpoint /token, specificando il refresh_token anziché il valore code:You can do so by submitting another POST request to the /token endpoint, this time providing the refresh_token instead of the code:

// Line breaks for legibility only

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

client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read
&refresh_token=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq...
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&grant_type=refresh_token
&client_secret=JqQX2PNo9bpM0uEihUPzyrh      // NOTE: Only required for web apps

Suggerimento

Provare a eseguire la richiesta in Postman.Try executing this request in Postman! Non dimenticare di sostituire refresh_token. Eseguire in Postman(Don't forget to replace the refresh_token) Run in Postman

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 common, organizations, consumers e gli identificatori del tenant.The allowed values are common, organizations, consumers, and tenant identifiers. Per altre informazioni, vedere le nozioni di base sul protocollo.For more detail, see protocol basics.
client_idclient_id Obbligatoriarequired ID applicazione che il portale di registrazione (apps.dev.microsoft.com) ha assegnato all'app.The Application ID that the registration portal (apps.dev.microsoft.com) assigned your app.
grant_typegrant_type Obbligatoriarequired Deve essere refresh_token per questa sezione del flusso del codice di autorizzazione.Must be refresh_token for this leg of the authorization code flow.
scopescope Obbligatoriarequired Elenco di ambiti separati da spazi.A space-separated list of scopes. Gli ambiti richiesti in questa sezione devono essere equivalenti agli ambiti richiesti nella sezione di richiesta del codice di autorizzazione originale o un sottoinsieme di questi ultimi.The scopes requested in this leg must be equivalent to or a subset of the scopes requested in the original authorization_code request leg. Se gli ambiti specificati in questa richiesta si estendono su più server di risorse, l'endpoint v2.0 restituirà un token per la risorsa specificata nel primo ambito.If the scopes specified in this request span multiple resource server, then the v2.0 endpoint will return a token for the resource specified in the first scope. Per una spiegazione più dettagliata degli ambiti, fare riferimento all'argomento relativo ad autorizzazioni, consenso e ambiti.For a more detailed explanation of scopes, refer to permissions, consent, and scopes.
refresh_tokenrefresh_token Obbligatoriarequired Token di aggiornamento acquisito durante la seconda sezione del flusso.The refresh_token that you acquired in the second leg of the flow.
redirect_uriredirect_uri Obbligatoriarequired Stesso valore redirect_uri usato per acquisire il codice di autorizzazione.The same redirect_uri value that was used to acquire the authorization_code.
client_secretclient_secret Obbligatorio per app Webrequired for web apps Segreto dell'applicazione creato per l'app nel portale di registrazione delle app.The application secret that you created in the app registration portal for your app. È consigliabile non usarlo in un'app nativa, perché i segreti client non possono essere archiviati in modo affidabile nei dispositivi.It should not be used in a native app, because client_secrets cannot be reliably stored on devices. Il segreto è obbligatorio per le app Web e le API Web che possono archiviare in modo sicuro il segreto client sul lato server.It is required for web apps and web APIs, which have the ability to store the client_secret securely on the server side.

Risposta con esito positivoSuccessful response

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

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
    "token_type": "Bearer",
    "expires_in": 3599,
    "scope": "https%3A%2F%2Fgraph.microsoft.com%2Fmail.read",
    "refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
    "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctOD...",
}
ParametroParameter DESCRIZIONEDescription
access_tokenaccess_token Token di accesso richiesto.The requested access token. 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
expires_inexpires_in Validità del token di accesso (espressa in secondi).How long the access token is valid (in seconds).
scopescope Ambiti per i quali il token di accesso è valido.The scopes that the access_token is valid for.
refresh_tokenrefresh_token Nuovo token di aggiornamento di OAuth 2.0.A new OAuth 2.0 refresh token. È necessario sostituire il token di aggiornamento precedente con quello appena acquisito, per garantire che i token di aggiornamento rimangano validi il più a lungo possibile.You should replace the old refresh token with this newly acquired refresh token to ensure your refresh tokens remain valid for as long as possible.
Nota: viene fornito solo è stato richiesto l'ambito offline_access.Note: Only provided if offline_access scope was requested.
id_tokenid_token Token JWT (Token Web JSON) non firmato.An unsigned JSON Web Token (JWT). L'app può eseguire la decodifica base64Url dei 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. Per altre informazioni sui token ID, vedere le informazioni di riferimento sui token dell'endpoint v2.0.For more information about id_tokens, see the v2.0 endpoint token reference.
Nota: viene fornito solo è stato richiesto l'ambito openid.Note: Only provided if openid scope was requested.

Risposta di erroreError response

{
  "error": "invalid_scope",
  "error_description": "AADSTS70011: The provided value for the input parameter 'scope' is not valid. The scope https://foo.microsoft.com/mail.read is not valid.\r\nTrace ID: 255d1aef-8c98-452f-ac51-23d051240864\r\nCorrelation ID: fb3d2015-bc17-4bb9-bb85-30c5cf1aaaa7\r\nTimestamp: 2016-01-09 02:02:12Z",
  "error_codes": [
    70011
  ],
  "timestamp": "2016-01-09 02:02:12Z",
  "trace_id": "255d1aef-8c98-452f-ac51-23d051240864",
  "correlation_id": "fb3d2015-bc17-4bb9-bb85-30c5cf1aaaa7"
}
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.