Flusso del codice di autorizzazione OAuth 2.0 e Microsoft Identity Platform

Il tipo di concessione del codice di autorizzazione OAuth 2.0 o il flusso del codice di autenticazione consente a un'applicazione client di ottenere l'accesso autorizzato a risorse protette come le API Web. Il flusso del codice di autenticazione richiede un agente utente che supporta il reindirizzamento dal server di autorizzazione (il Microsoft Identity Platform) all'applicazione. Ad esempio, un'applicazione Web browser, desktop o per dispositivi mobili gestita da un utente per accedere all'app e accedere ai dati.

Questo articolo descrive i dettagli del protocollo di basso livello in genere necessari solo quando si creano manualmente ed eseguono richieste HTTP non elaborate per eseguire il flusso, che non è consigliabile. Usare invece una libreria di autenticazione Microsoft predefinita e supportata per ottenere token di sicurezza e chiamare API Web protette nelle app.

Applicazioni che supportano il flusso del codice di autenticazione

Usare il flusso del codice di autenticazione associato a Proof Key for Code Exchange (PKCE) e OpenID Connect (OIDC) per ottenere token di accesso e token ID in questi tipi di app:

Dettagli del protocollo

Il flusso del codice di autorizzazione di OAuth 2.0 è descritto nella sezione 4.1 della specifica di OAuth 2.0. Le app che usano il flusso del codice di autorizzazione OAuth 2.0 acquisiscono un oggetto access_token da includere nelle richieste alle risorse protette dal Microsoft Identity Platform (in genere le API). Le app possono anche richiedere nuovi ID e token di accesso per le entità autenticate in precedenza usando un meccanismo di aggiornamento.

Suggerimento

Provare a eseguire la richiesta in Postman
Provare a eseguire questa richiesta e altro ancora in Postman. Non dimenticare di sostituire token e ID.

Questo diagramma mostra una visualizzazione generale del flusso di autenticazione:

Diagramma che mostra il flusso del codice di autorizzazione OAuth. L'app nativa e il web A P interagiscono usando i token, come descritto in questo articolo.

URI di reindirizzamento per app a pagina singola

Gli URI di reindirizzamento per le applicazioni a livello di servizio che usano il flusso del codice di autenticazione richiedono una configurazione speciale.

Il spa tipo di reindirizzamento è compatibile con le versioni precedenti con il flusso implicito. Le app che attualmente usano il flusso implicito per ottenere i token possono passare al spa tipo di URI di reindirizzamento senza problemi e continuare a usare il flusso implicito.

Se si tenta di usare il flusso del codice di autorizzazione senza configurare CORS per l'URI di reindirizzamento, verrà visualizzato questo errore nella console:

access to XMLHttpRequest at 'https://login.microsoftonline.com/common/v2.0/oauth2/token' from origin 'yourApp.com' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.

In tal caso, visitare la registrazione dell'app e aggiornare l'URI di reindirizzamento per l'app per l'uso del spa tipo.

Le applicazioni non possono usare un spa URI di reindirizzamento con flussi non SPA, ad esempio applicazioni native o flussi di credenziali client. Per garantire la sicurezza e le procedure consigliate, il Microsoft Identity Platform restituisce un errore se si tenta di usare un spa URI di reindirizzamento senza intestazioneOrigin. Analogamente, il Microsoft Identity Platform impedisce anche l'uso delle credenziali client in tutti i flussi in presenza di un'intestazioneOrigin, per assicurarsi che i segreti non vengano usati dal browser.

Richiedere un codice di autorizzazione

Il flusso del codice di autorizzazione ha inizio con il client che indirizza l'utente all'endpoint /authorize . In questa richiesta, il client richiede le autorizzazioni openid, offline_accesse https://graph.microsoft.com/mail.read all'utente.

Alcune autorizzazioni sono limitate dall'amministratore, ad esempio la scrittura di dati nella directory di un'organizzazione tramite Directory.ReadWrite.All. Se l'applicazione richiede l'accesso a una di queste autorizzazioni da un utente dell'organizzazione, l'utente riceve un messaggio di errore che indica che non è autorizzato a fornire il consenso alle autorizzazioni dell'applicazione. Per richiedere l'accesso agli ambiti con restrizioni di amministratore, è necessario richiederli direttamente da un amministratore globale. Per altre informazioni, vedere autorizzazioni con restrizioni di Amministrazione.

Se non specificato diversamente, non sono presenti valori predefiniti per i parametri facoltativi. Esiste tuttavia un comportamento predefinito per una richiesta che omette parametri facoltativi. Il comportamento predefinito consiste nell'accedere all'unico utente corrente, visualizzare la selezione account se sono presenti più utenti o visualizzare la pagina di accesso se non sono presenti utenti connessi.

// 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=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read
&state=12345
&code_challenge=YTFjNjI1OWYzMzA3MTI4ZDY2Njg5M2RkNmVjNDE5YmEyZGRhOGYyM2IzNjdmZWFhMTQ1ODg3NDcxY2Nl
&code_challenge_method=S256

Suggerimento

Selezionare il collegamento seguente per eseguire questa richiesta. Dopo l'accesso, il browser deve essere reindirizzato a http://localhost/myapp/ con un code nella barra degli indirizzi. https://login.microsoftonline.com/common/oauth2/v2.0/authorize...

Parametro Obbligatoria/facoltativa Descrizione
tenant obbligatorio Il valore {tenant} del percorso della richiesta può essere usato per controllare chi può accedere all'applicazione. I valori validi sono common, organizations, consumerse identificatori tenant. Per gli scenari guest in cui si firma un utente da un tenant a un altro tenant, è necessario specificare l'identificatore del tenant per l'accesso al tenant della risorsa. Per altre informazioni, vedere Endpoint.
client_id obbligatorio L'ID dell'applicazione (client) assegnato all'app dall'esperienzaPortale di Azure - Registrazioni app.
response_type obbligatorio Deve includere code per il flusso del codice di autorizzazione. Può anche includere id_token o token se si usa il flusso ibrido.
redirect_uri necessarie Parametro redirect_uri dell'app, dove possono essere inviate e ricevute dall'app le risposte di autenticazione. Deve corrispondere esattamente a uno degli URI di reindirizzamento registrati nel portale, ad eccezione del fatto che deve essere codificato con URL. Per le app native e per dispositivi mobili, usare uno dei valori consigliati: https://login.microsoftonline.com/common/oauth2/nativeclient per le app che usano browser incorporati o http://localhost per le app che usano browser di sistema.
scope obbligatorio Elenco separato da spazi di ambiti a cui si vuole che l'utente dia il consenso. Per la /authorize parte della richiesta, questo parametro può coprire più risorse. Questo valore consente all'app di ottenere il consenso per più API Web da chiamare.
response_mode Consigliato Specifica il modo in cui Identity Platform deve restituire il token richiesto all'app.

Valori supportati:

- query: impostazione predefinita quando si richiede un token di accesso. Fornisce il codice come parametro della stringa di query nell'URI di reindirizzamento. Il query parametro non è supportato quando si richiede un token ID usando il flusso implicito.
- fragment: impostazione predefinita quando si richiede un token ID usando il flusso implicito. Supportato anche se si richiede solo un codice.
- form_post: esegue un POST contenente il codice all'URI di reindirizzamento. Supportato quando si richiede un codice.

state Consigliato Valore incluso nella richiesta che viene restituito nella risposta del token. Può trattarsi di una stringa di qualsiasi contenuto. Per evitare gli attacchi di richiesta intersito falsa, viene in genere usato un valore univoco generato casualmente. Il valore può anche codificare informazioni sullo stato dell'utente nell'app prima che si verifichi la richiesta di autenticazione. Ad esempio, potrebbe codificare la pagina o la visualizzazione in cui si trovavano.
prompt facoltative Indica il tipo di interazione utente richiesto. I valori validi sono login, none, consent e select_account.

- prompt=login impone all'utente di immettere le proprie credenziali per tale richiesta, negando l'accesso Single Sign-On.
- prompt=none è l'opposto. Garantisce che l'utente non venga visualizzato alcun prompt interattivo. Se la richiesta non può essere completata automaticamente tramite Single Sign-On, il Microsoft Identity Platform restituisce un interaction_required errore.
- prompt=consent attiva la finestra di dialogo di consenso OAuth dopo l'accesso dell'utente, chiedendo all'utente di concedere le autorizzazioni all'app.
- prompt=select_account interrompe l'accesso Single Sign-On fornendo un'esperienza di selezione dell'account che elenca tutti gli account nella sessione o qualsiasi account memorizzato o un'opzione per scegliere di usare completamente un account diverso.
login_hint facoltative È possibile usare questo parametro per precompilare il campo nome utente e indirizzo di posta elettronica della pagina di accesso per l'utente. Le app possono usare questo parametro durante la riautenticazione, dopo aver già estratto l'attestazione login_hintfacoltativa da un accesso precedente.
domain_hint facoltative Se inclusa, l'app ignora il processo di individuazione basato sulla posta elettronica che l'utente passa attraverso la pagina di accesso, causando un'esperienza utente leggermente più semplificata. Ad esempio, inviarli al provider di identità federato. Le app possono usare questo parametro durante la riautenticazione, estraendo da tid un accesso precedente.
code_challenge consigliato / obbligatorio Usato per proteggere le concessioni del codice di autorizzazione usando Proof Key for Code Exchange (PKCE). Obbligatorio con code_challenge_method incluso. Per altre informazioni, vedere il PKCE RFC. Questo parametro è ora consigliato per tutti i tipi di applicazioni, sia client pubblici che riservati e richiesti dal Microsoft Identity Platform per le app a pagina singola usando il flusso di codice di autorizzazione.
code_challenge_method consigliato / obbligatorio Metodo usato per codificare code_verifier per il parametro code_challenge. Deve essere S256, ma la specifica consente l'uso di plain se il client non può supportare SHA256.

Se escluso, code_challenge viene considerato testo non crittografato se code_challenge è incluso. Il Microsoft Identity Platform supporta sia plain che S256. Per altre informazioni, vedere il PKCE RFC. Questo parametro è necessario per le app a pagina singola usando il flusso del codice di autorizzazione.

A questo punto viene chiesto all'utente di immettere le credenziali e completare l'autenticazione. Il Microsoft Identity Platform garantisce inoltre che l'utente abbia accettato le autorizzazioni indicate nel scope parametro di query. Se l'utente non ha acconsentito a nessuna di queste autorizzazioni, chiede all'utente di concedere il consenso alle autorizzazioni necessarie. Per altre informazioni, vedere Autorizzazioni e consenso nell'Microsoft Identity Platform.

Dopo aver autenticato e concesso il consenso, il Microsoft Identity Platform restituisce una risposta all'app in corrispondenza dell'oggetto indicato redirect_uriusando il metodo specificato nel response_mode parametro .

Risposta di esito positivo

Questo esempio mostra una risposta riuscita usando response_mode=query:

GET http://localhost?
code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&state=12345
Parametro Descrizione
code authorization_code richiesto dall'app. L'app può usare il codice di autorizzazione per richiedere un token di accesso per la risorsa di destinazione. I codici di autorizzazione sono di breve durata. In genere scadono dopo circa 10 minuti.
state Se nella richiesta è incluso un parametro state, lo stesso valore deve essere visualizzato nella risposta. L'app deve verificare che i valori del parametro state siano identici nella richiesta e nella risposta.

È anche possibile ricevere un token ID se si richiede uno e avere la concessione implicita abilitata nella registrazione dell'applicazione. Questo comportamento viene talvolta definito flusso ibrido. Viene usato dai framework come ASP.NET.

Risposta di errore

Le risposte di errore possono essere inviate anche a redirect_uri , in modo che l'app possa gestirle adeguatamente:

GET http://localhost?
error=access_denied
&error_description=the+user+canceled+the+authentication
Parametro Descrizione
error Stringa di codice di errore che può essere usata per classificare i tipi di errori e per reagire agli errori. Questa parte dell'errore viene fornita in modo che l'app possa reagire in modo appropriato all'errore, ma non spiega in profondità perché si è verificato un errore.
error_description Messaggio di errore specifico che consente a uno sviluppatore di identificare la causa di un errore di autenticazione. Questa parte dell'errore contiene la maggior parte delle informazioni utili sul motivo per cui si è verificato l'errore.

Codici per gli errori dell'endpoint di autorizzazione

La tabella seguente descrive i diversi codici errore che possono essere restituiti nel parametro error della risposta di errore.

Codice di errore Descrizione Azione client
invalid_request Errore del protocollo, ad esempio un parametro obbligatorio mancante. Correggere e inviare di nuovo la richiesta. Questo errore è un errore di sviluppo in genere rilevato durante il test iniziale.
unauthorized_client All'applicazione client non è consentito richiedere un codice di autorizzazione. 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. L'applicazione può chiedere all'utente di installare l'applicazione e di aggiungerla ad Azure AD.
access_denied Consenso negato dal proprietario della risorsa L'applicazione client può notificare all'utente che non può continuare a meno che l'utente non consensi.
unsupported_response_type Il server di autorizzazione non supporta il tipo di risposta nella richiesta. Correggere e inviare di nuovo la richiesta. Questo errore è un errore di sviluppo in genere rilevato durante il test iniziale. Nel flusso ibrido questo errore segnala che è necessario abilitare l'impostazione di concessione implicita del token ID nella registrazione dell'app client.
server_error Errore imprevisto rilevato dal server. ripetere la richiesta. Questi errori possono dipendere da condizioni temporanee. L'applicazione client potrebbe spiegare all'utente che la risposta viene ritardata a un errore temporaneo.
temporarily_unavailable Il server è temporaneamente troppo occupato per gestire la richiesta. ripetere la richiesta. L'applicazione client può comunicare all'utente che la risposta è stata ritardata a causa di una condizione temporanea.
invalid_resource La risorsa di destinazione non è valida perché non esiste, Azure AD non riesce a trovarla o non è attualmente configurata. Questo errore indica la risorsa, se esistente, non è stata configurata nel tenant. L'applicazione può chiedere all'utente di installare l'applicazione e di aggiungerla ad Azure AD.
login_required Troppi o nessun utente trovato. Il client ha richiesto l'autenticazione invisibile all'utente (prompt=none), ma non è stato possibile trovare un singolo utente. Questo errore può significare che nella sessione sono presenti più utenti attivi o nessun utente. Questo errore tiene conto del tenant scelto. Ad esempio, se sono attivi due account Azure AD e un account Microsoft e consumers viene scelto, l'autenticazione invisibile all'utente funziona.
interaction_required La richiesta richiede l'interazione dell'utente. È necessario un altro passaggio di autenticazione o il consenso. Ripetere la richiesta senza prompt=none.

Richiedere un token ID o un flusso ibrido

Per informazioni su chi l'utente è prima di riscattare un codice di autorizzazione, è comune che le applicazioni richiedano anche un token ID quando richiedono il codice di autorizzazione. Questo approccio viene chiamato flusso ibrido perché combina la concessione implicita con il flusso del codice di autorizzazione.

Il flusso ibrido viene comunemente usato nelle app Web per eseguire il rendering di una pagina per un utente senza bloccare il riscatto del codice, in particolare in ASP.NET. Sia le app a pagina singola che le app Web tradizionali possono trarre vantaggio dalla riduzione della latenza in questo modello.

Il flusso ibrido è lo stesso del flusso del codice di autorizzazione descritto in precedenza, ma con tre aggiunte. Tutte queste aggiunte sono necessarie per richiedere un token ID: nuovi ambiti, un nuovo response_type e un nuovo nonce parametro di query.

// Line breaks for legibility only

https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&response_type=code%20id_token
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=fragment
&scope=openid%20offline_access%20https%3A%2F%2Fgraph.microsoft.com%2Fuser.read
&state=12345
&nonce=abcde
&code_challenge=YTFjNjI1OWYzMzA3MTI4ZDY2Njg5M2RkNmVjNDE5YmEyZGRhOGYyM2IzNjdmZWFhMTQ1ODg3NDcxY2Nl
&code_challenge_method=S256
Parametro aggiornato Obbligatoria/facoltativa Descrizione
response_type obbligatorio L'aggiunta di id_token indica al server che l'applicazione vuole un token ID nella risposta dall'endpoint /authorize .
scope necessario Per i token ID, questo parametro deve essere aggiornato per includere gli ambiti del token ID: openid e facoltativamente profile e email.
nonce necessario Valore incluso nella richiesta, generata dall'app, che verrà incluso nel id_token risultante come attestazione. L'app può quindi verificare questo valore per l'attenuazione degli attacchi di riproduzione del token. Il valore è in genere una stringa casuale univoca che può essere usata per identificare l'origine della richiesta.
response_mode Consigliato Specifica il metodo da usare per restituire il token risultante all'app. Il valore predefinito è query solo per un codice di autorizzazione, ma fragment se la richiesta include un id_tokenresponse_type valore specificato nella specifica OpenID. È consigliabile usare form_postle app, soprattutto quando si usa http://localhost come URI di reindirizzamento.

L'uso di fragment come modalità di risposta causa problemi per le app Web che leggeno il codice dal reindirizzamento. I browser non passano il frammento al server Web. In queste situazioni, le app devono usare la form_post modalità di risposta per assicurarsi che tutti i dati vengano inviati al server.

Risposta di esito positivo

Questo esempio mostra una risposta riuscita usando response_mode=fragment:

GET https://login.microsoftonline.com/common/oauth2/nativeclient#
code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&id_token=eYj...
&state=12345
Parametro Descrizione
code Codice di autorizzazione richiesto dall'app. L'app può usare il codice di autorizzazione per richiedere un token di accesso per la risorsa di destinazione. I codici di autorizzazione sono di breve durata, in genere scaduti dopo circa 10 minuti.
id_token Token ID per l'utente, rilasciato usando la concessione implicita. Contiene un'attestazione speciale c_hash che rappresenta l'hash dell'oggetto code nella stessa richiesta.
state Se nella richiesta è incluso un parametro state, lo stesso valore deve essere visualizzato nella risposta. L'app deve verificare che i valori del parametro state siano identici nella richiesta e nella risposta.

Riscattare un codice per un token di accesso

Tutti i client riservati hanno la possibilità di usare i segreti client o le credenziali del certificato. I segreti condivisi simmetrici vengono generati dal Microsoft Identity Platform. Le credenziali del certificato sono chiavi asimmetriche caricate dallo sviluppatore. Per altre informazioni, vedere Microsoft Identity Platform credenziali del certificato di autenticazione dell'applicazione.

Per una migliore sicurezza, è consigliabile usare le credenziali del certificato. I client pubblici, che includono applicazioni native e app a pagina singola, non devono usare segreti o certificati quando si riscatta un codice di autorizzazione. Assicurarsi sempre che gli URI di reindirizzamento includano il tipo di applicazione e siano univoci.

Richiedere un token di accesso con un client_secret

Dopo aver acquisito un oggetto authorization_code e aver ottenuto l'autorizzazione dall'utente, è possibile riscattare l'oggetto code per una access_token risorsa. code Riscattare inviando una POST richiesta all'endpoint/token:

// 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
&code_verifier=ThisIsntRandomButItNeedsToBe43CharactersLong 
&client_secret=JqQX2PNo9bpM0uEihUPzyrh    // NOTE: Only required for web apps. This secret needs to be URL-Encoded.
Parametro Obbligatoria/facoltativa Descrizione
tenant obbligatorio Il valore {tenant} del percorso della richiesta può essere usato per controllare chi può accedere all'applicazione. I valori validi sono common, organizations, consumerse identificatori tenant. Per altre informazioni, vedere Endpoint.
client_id necessario ID applicazione (client) assegnato all'app dall'portale di Azure: Registrazioni app pagina.
scope facoltative Elenco di ambiti separato da spazi. Gli ambiti devono appartenere tutti a una singola risorsa, insieme agli ambiti OIDC (profile, openid, email). Per altre informazioni, vedere Autorizzazioni e consenso nel Microsoft Identity Platform. Questo parametro è un'estensione Microsoft al flusso del codice di autorizzazione, destinata a consentire alle app di dichiarare la risorsa per cui vuole il token durante il riscatto del token.
code necessarie authorization_code acquisito nella prima parte del flusso.
redirect_uri necessarie Lo stesso valore redirect_uri usato per acquisire authorization_code.
grant_type obbligatorio Deve essere authorization_code per il flusso del codice di autorizzazione.
code_verifier Consigliato Lo stesso code_verifier usato per ottenere il valore authorization_code. Obbligatorio se è stato usato PKCE nella richiesta di concessione del codice di autorizzazione. Per altre informazioni, vedere il PKCE RFC.
client_secret obbligatorio per app Web riservate Segreto dell'applicazione creato per l'app nel portale di registrazione delle app. Non usare il segreto dell'applicazione in un'app nativa o in un'app a pagina singola perché un client_secret oggetto non può essere archiviato in modo affidabile nei dispositivi o nelle pagine Web. È necessario per le app Web e le API Web, che possono archiviare in client_secret modo sicuro sul lato server. Analogamente a tutti i parametri, il segreto client deve essere codificato con URL prima di essere inviato. Questo passaggio viene in genere eseguito dall'SDK. Per altre informazioni sulla codifica URI, vedere la specifica della sintassi generica dell'URI. È supportato anche il modello di autenticazione di base per fornire le credenziali nell'intestazione Autorizzazione, per RFC 6749 .

Richiedere un token di accesso con credenziali del certificato

POST /{tenant}/oauth2/v2.0/token HTTP/1.1               // Line breaks for clarity
Host: 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
&code_verifier=ThisIsntRandomButItNeedsToBe43CharactersLong
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNScUtqRlBuZDdSRnd2d1pJMCJ9.eyJ{a lot of characters here}M8U3bSUKKJDEg
Parametro Obbligatoria/facoltativa Descrizione
tenant obbligatorio Il valore {tenant} del percorso della richiesta può essere usato per controllare chi può accedere all'applicazione. I valori validi sono common, organizations, consumerse identificatori tenant. Per altri dettagli, vedere Endpoint.
client_id necessario ID applicazione (client) assegnato all'app dall'portale di Azure: Registrazioni app pagina.
scope facoltative Elenco di ambiti separato da spazi. Gli ambiti devono appartenere tutti a una singola risorsa, insieme agli ambiti OIDC (profile, openid, email). Per altre informazioni, vedere Autorizzazioni, consenso e ambiti. Questo parametro è un'estensione Microsoft al flusso del codice di autorizzazione. Questa estensione consente alle app di dichiarare la risorsa per cui vuole il token durante il riscatto del token.
code necessarie authorization_code acquisito nella prima parte del flusso.
redirect_uri necessarie Lo stesso valore redirect_uri usato per acquisire authorization_code.
grant_type obbligatorio Deve essere authorization_code per il flusso del codice di autorizzazione.
code_verifier Consigliato code_verifier Stessa classe utilizzata per ottenere l'oggetto authorization_code. Obbligatorio se nella richiesta di concessione del codice di autorizzazione è stato usato PKCE. Per altre informazioni, vedere il PKCE RFC.
client_assertion_type obbligatorio per app Web riservate Il valore deve essere impostato su urn:ietf:params:oauth:client-assertion-type:jwt-bearer per usare una credenziale del certificato.
client_assertion obbligatorio per app Web riservate Un'asserzione, ovvero un token WEB JSON (JWT), che è necessario creare e firmare con il certificato registrato come credenziali per l'applicazione. Leggere l'articolo relativo alle credenziali basate su certificato per informazioni sulla registrazione del certificato e il formato dell'asserzione.

I parametri sono uguali alla richiesta dal segreto condiviso, ad eccezione del fatto che il client_secret parametro viene sostituito da due parametri: a client_assertion_type e client_assertion.

Risposta di esito positivo

Questo esempio mostra una risposta di token riuscita:

{
    "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...",
}
Parametro Descrizione
access_token Token di accesso richiesto. L'app può usare questo token per eseguire l'autenticazione nella risorsa protetta, ad esempio un'API Web.
token_type Indica il valore del tipo di token. L'unico tipo supportato da Azure AD è Bearer.
expires_in Per quanto tempo il token di accesso è valido, in secondi.
scope Ambiti per cui è access_token valido. Facoltativa. Questo parametro non è standard e, se omesso, il token è per gli ambiti richiesti nella parte iniziale del flusso.
refresh_token Token di aggiornamento di OAuth 2.0. L'app può usare questo token per acquisire altri token di accesso dopo la scadenza del token di accesso corrente. I token di aggiornamento sono di lunga durata. Possono mantenere l'accesso alle risorse per periodi prolungati. Per altri dettagli sull'aggiornamento di un token di accesso, vedere Aggiornare il token di accesso più avanti in questo articolo.
Nota: viene fornito solo se è stato richiesto l'ambito offline_access.
id_token Token Web JSON. L'app può decodificare i segmenti di questo token per richiedere informazioni sull'utente che ha eseguito l'accesso. L'app può memorizzare nella cache i valori e visualizzarli e i client riservati possono usare questo token per l'autorizzazione. Per altre informazioni sugli oggetti id_token, vedere id_token reference.
Nota: viene fornito solo se è stato richiesto l'ambito openid.

Risposta di errore

Questo esempio è una risposta di errore:

{
  "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"
}
Parametro Descrizione
error Stringa di codice di errore che può essere usata per classificare i tipi di errori e per reagire agli errori.
error_description Messaggio di errore specifico che consente a uno sviluppatore di identificare la causa di un errore di autenticazione.
error_codes Elenco dei codici di errore specifici del servizio token di sicurezza utile per la diagnostica.
timestamp Ora in cui si è verificato l'errore.
trace_id Identificatore univoco per la richiesta utile per la diagnostica.
correlation_id Identificatore univoco per la richiesta utile per la diagnostica tra i componenti.

Codici per gli errori degli endpoint di token

Codice di errore Descrizione Azione client
invalid_request Errore del protocollo, ad esempio un parametro obbligatorio mancante. Correggere la richiesta o la registrazione dell'app e inviare di nuovo la richiesta.
invalid_grant Il codice di autorizzazione o PKCE non è valido o è scaduto. Provare una nuova richiesta all'endpoint /authorize e verificare che il code_verifier parametro sia corretto.
unauthorized_client Il client autenticato non è autorizzato a usare questo tipo di concessione dell'autorizzazione. 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. L'applicazione può chiedere all'utente di installare l'applicazione e di aggiungerla ad Azure AD.
invalid_client Autenticazione client non riuscita. Credenziali del client non valide. Per risolvere il problema, l'amministratore applicazione aggiorna le credenziali.
unsupported_grant_type Il server di autorizzazione non supporta il tipo di concessione di autorizzazione. Modificare il tipo di concessione nella richiesta. Questo tipo di errore dovrebbe verificarsi solo durante lo sviluppo ed essere rilevato durante il test iniziale.
invalid_resource La risorsa di destinazione non è valida perché non esiste, Azure AD non riesce a trovarlo o non è configurato correttamente. Questo codice indica che la risorsa, se esistente, non è stata configurata nel tenant. L'applicazione può chiedere all'utente di installare l'applicazione e di aggiungerla ad Azure AD.
interaction_required Non standard, in quanto la specifica OIDC chiama questo codice solo nell'endpoint /authorize . La richiesta richiede l'interazione dell'utente. Ad esempio, è necessario un altro passaggio di autenticazione. Ripetere la /authorize richiesta con gli stessi ambiti.
temporarily_unavailable Il server è temporaneamente troppo occupato per gestire la richiesta. Ripetere la richiesta dopo un piccolo ritardo. L'applicazione client può comunicare all'utente che la risposta è stata ritardata a causa di una condizione temporanea.
consent_required La richiesta richiede il consenso dell'utente. Questo errore non è standard. In genere viene restituito solo nell'endpoint /authorize in base alle specifiche OIDC. Restituito quando è stato usato un scope parametro nel flusso di riscatto del codice che l'app client non dispone dell'autorizzazione per richiedere. Il client deve inviare di nuovo l'utente all'endpoint /authorize con l'ambito corretto per attivare il consenso.
invalid_scope L'ambito richiesto dall'app non è valido. Aggiornare il valore del scope parametro nella richiesta di autenticazione a un valore valido.

Nota

Le app a pagina singola possono ricevere un errore invalid_request che indica che il riscatto del token tra le origini è consentito solo per il tipo di client "Applicazione a pagina singola". Ciò indica che l'URI di reindirizzamento usato per richiedere il token non è stato contrassegnato come URI di reindirizzamento spa. Esaminare i passaggi di registrazione dell'applicazione su come abilitare questo flusso.

Usare il token di accesso

Dopo aver ottenuto un access_token è possibile usarlo in richieste alle API Web includendolo nell'intestazione Authorization:

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

Aggiornare il token di accesso

I token di accesso sono di breve durata. Aggiornarli dopo la scadenza per continuare ad accedere alle risorse. A tale scopo, inviare un'altra richiesta POST all'endpoint /token, Specificare invece refresh_token di code. I token di aggiornamento sono validi per tutte le autorizzazioni per cui il client ha già ricevuto il consenso. Ad esempio, un token di aggiornamento emesso in una richiesta per scope=mail.read può essere usato per richiedere un nuovo token di accesso per scope=api://contoso.com/api/UseResource.

I token di aggiornamento per le app Web e le app native non hanno durate specificate. In genere, la durata dei token di aggiornamento è relativamente lunga. In alcuni casi, tuttavia, i token di aggiornamento scadono, vengono revocati o non dispongono di privilegi sufficienti per l'azione. L'applicazione deve prevedere e gestire gli errori restituiti dall'endpoint di rilascio del token. Le app a pagina singola ottengono un token con una durata di 24 ore, che richiede una nuova autenticazione ogni giorno. Questa azione può essere eseguita automaticamente in un iframe quando i cookie di terze parti sono abilitati. Deve essere eseguita in un frame di primo livello, sia lo spostamento completo della pagina o una finestra popup, nei browser senza cookie di terze parti, ad esempio Safari.

I token di aggiornamento non vengono revocati quando vengono usati per acquisire nuovi token di accesso. Si prevede di eliminare il token di aggiornamento precedente. La specifica OAuth 2.0 indica: "Il server di autorizzazione PUÒ eseguire un nuovo token di aggiornamento, nel qual caso il client DEVE rimuovere il token di aggiornamento precedente e sostituirlo con un nuovo token di aggiornamento. Il server di autorizzazione può revocare il token di aggiornamento precedente dopo aver eseguito un nuovo token di aggiornamento per il client".

Importante

Per i token di aggiornamento inviati a un URI di reindirizzamento registrato come spa, il token di aggiornamento scade dopo 24 ore. I token di aggiornamento aggiuntivi acquisiti usando il token di aggiornamento iniziale comportano tale scadenza, quindi le app devono essere preparate per eseguire di nuovo il flusso del codice di autorizzazione usando un'autenticazione interattiva per ottenere un nuovo token di aggiornamento ogni 24 ore. Gli utenti non devono immettere le proprie credenziali e in genere non vedono nemmeno alcuna esperienza utente, solo un ricaricamento dell'applicazione. Il browser deve visitare la pagina di accesso in un frame di primo livello per visualizzare la sessione di accesso. Ciò è dovuto alle funzionalità di privacy nei browser che bloccano i cookie di terze parti.

// 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=535fb089-9ff3-47b6-9bfb-4f1264799865
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read
&refresh_token=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq...
&grant_type=refresh_token
&client_secret=sampleCredentia1s    // NOTE: Only required for web apps. This secret needs to be URL-Encoded
Parametro Tipo Descrizione
tenant obbligatorio Il valore {tenant} del percorso della richiesta può essere usato per controllare chi può accedere all'applicazione. I valori validi sono common, organizations, consumerse identificatori tenant. Per altre informazioni, vedere Endpoint.
client_id obbligatorio L'ID dell'applicazione (client) assegnato all'app dall'esperienzaPortale di Azure - Registrazioni app.
grant_type obbligatorio Deve essere refresh_token per questa sezione del flusso del codice di autorizzazione.
scope facoltative Elenco di ambiti separato da spazi. Gli ambiti richiesti in questa gamba devono essere equivalenti a o a un sottoinsieme degli ambiti richiesti nella fase di richiesta originale authorization_code . Se gli ambiti specificati in questa richiesta si estendono su più server di risorse, il Microsoft Identity Platform restituisce un token per la risorsa specificata nel primo ambito. Per altre informazioni, vedere Autorizzazioni e consenso nel Microsoft Identity Platform.
refresh_token necessario Oggetto refresh_token acquisito nella seconda gamba del flusso.
client_secret obbligatorio per le app Web Segreto dell'applicazione creato nel portale di registrazione dell'app. Non deve essere usato in un'app nativa, perché un client_secret oggetto non può essere archiviato in modo affidabile nei dispositivi. È necessario per le app Web e le API Web, che possono archiviare in client_secret modo sicuro sul lato server. Questo segreto deve essere codificato con URL. Per altre informazioni, vedere la specifica della sintassi generica URI.

Risposta con esito positivo

Questo esempio mostra una risposta di token riuscita:

{
    "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...",
}
Parametro Descrizione
access_token Token di accesso richiesto. L'app può usare questo token per eseguire l'autenticazione nella risorsa protetta, ad esempio un'API Web.
token_type Indica il valore del tipo di token. L'unico tipo supportato da Azure AD è Bearer.
expires_in Per quanto tempo il token di accesso è valido, in secondi.
scope Ambiti per cui è access_token valido.
refresh_token Nuovo token di aggiornamento di OAuth 2.0. Sostituire il token di aggiornamento precedente con questo token di aggiornamento appena acquisito per assicurarsi che i token di aggiornamento rimangano validi per il più tempo possibile.
Nota: viene fornito solo se è stato richiesto l'ambito offline_access.
id_token Token Web JSON non firmato. L'app può decodificare i segmenti di questo token per richiedere informazioni sull'utente che ha eseguito l'accesso. L'app può memorizzare nella cache i valori e visualizzarli, ma non deve basarsi su di essi per i limiti di autorizzazione o di sicurezza. Per altre informazioni su id_token, vedere i token ID Microsoft Identity Platform.
Nota: viene fornito solo se è stato richiesto l'ambito openid.

Avviso

Non tentare di convalidare o leggere i token per qualsiasi API di cui non si è proprietari, inclusi i token in questo esempio, nel codice. I token per Microsoft servizi possono usare un formato speciale che non verrà convalidato come token JWT e potrebbe anche essere crittografato per gli utenti consumer (account Microsoft). Durante la lettura dei token è uno strumento utile per il debug e l'apprendimento, non assumere dipendenze da questo nel codice o presupporre specifiche sui token che non sono per un'API che si controlla.

Risposta di errore

{
  "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"
}
Parametro Descrizione
error Stringa di codice di errore che può essere usata per classificare i tipi di errori e per reagire agli errori.
error_description Messaggio di errore specifico che consente a uno sviluppatore di identificare la causa principale di un errore di autenticazione.
error_codes Elenco dei codici di errore specifici del servizio token di sicurezza utile per la diagnostica.
timestamp Ora in cui si è verificato l'errore.
trace_id Identificatore univoco per la richiesta utile per la diagnostica.
correlation_id Identificatore univoco per la richiesta utile per la diagnostica tra i componenti.

Per una descrizione dei codici di errore e l'azione consigliata per il client, vedere Codici per gli errori degli endpoint di token.

Passaggi successivi