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, e descrive come inviare e ricevere messaggi HTTP senza utilizzare une delle nostre librerie open source.This guide is language-independent, and describes how to send and receive HTTP messages without using any of our open-source 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 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.It enables apps to securely acquire access_tokens which can be used to access resources that are secured using 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 Id 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. 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.
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 basata 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.

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 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 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 sta comunicando 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 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 sta comunicando 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 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.

Richiedere un token di accessoRequest an access token

Dopo aver ottenuto un codice di autorizzazione e l'autorizzazione dell'utente, è possibile riscattare il valore code per un access_tokenalla 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/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 2.0 restituirà un token per la risorsa specificata nel primo ambito.If the scopes specified in this request span multiple resource servers, 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.

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 2.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 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. 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 sta comunicando 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 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 2.0 restituirà un token per la risorsa specificata nel primo ambito.If the scopes specified in this request span multiple resource servers, 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 2.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, please see Error codes for token endpoint errors.