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 di 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 (Microsoft Identity Platform) all'applicazione. Ad esempio, un Web browser, un'applicazione 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 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 predefinita e supportata da Microsoft 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:
- Applicazione Web a pagina singola
- Applicazione Web standard (basata su server)
- App desktop e per dispositivi mobili
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 da 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.
Questo diagramma mostra una visualizzazione generale del flusso di autenticazione:
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.
- Aggiungere un URI di reindirizzamento che supporta il flusso del codice di autenticazione con PKCE e la condivisione di risorse tra le origini (CORS): seguire la procedura descritta in URI di reindirizzamento: MSAL.js 2.0 con il flusso del codice di autenticazione.
- Aggiornare un URI di reindirizzamento: impostare l'URI di
typereindirizzamento suspausando l'editor del manifesto dell'applicazione nell'interfaccia di amministrazione di Microsoft Entra.
Il spa tipo di reindirizzamento è compatibile con le versioni precedenti del flusso implicito. Le app che usano attualmente 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. Nonostante questa compatibilità con le versioni precedenti, è consigliabile usare il flusso del codice di autenticazione con PKCE per le applicazioni a pagina singola.
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 in modo che usi il 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, Microsoft Identity Platform restituisce un errore se si tenta di usare un spa URI di reindirizzamento senza intestazione Origin . Analogamente, Microsoft Identity Platform impedisce anche l'uso di credenziali client in tutti i flussi in presenza di un'intestazione Origin , 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 di esempio il client richiede le openidautorizzazioni , offline_accesse https://graph.microsoft.com/mail.read dall'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 amministratore.
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=00001111-aaaa-2222-bbbb-3333cccc4444
&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
| 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 in 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 applicazione (client) che l'esperienza Interfaccia di amministrazione di Microsoft Entra: Registrazioni app ha assegnato all'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 |
Obbligatorio | 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 nell'interfaccia di amministrazione di Microsoft Entra, ad eccezione del fatto che deve essere codificato come 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 che si vuole 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 sull'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 nell'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 desiderato. 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 erano presenti. |
prompt |
facoltative | Indica il tipo di interazione utente richiesto. I valori validi sono login, none, consent e select_account.- prompt=login forza l'utente a immettere le sue credenziali alla 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, Microsoft Identity Platform restituisce un interaction_required errore.- prompt=consent attiva la finestra di dialogo di consenso di OAuth dopo l'accesso dell'utente, che chiede 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 pre-compilare 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_hint facoltativa da un accesso precedente. |
domain_hint |
facoltative | Se inclusa, l'app ignora il processo di individuazione basato sulla posta elettronica che l'utente passa nella pagina di accesso, con 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 di codice di autorizzazione usando la chiave di prova per Lo scambio di codice (PKCE). Obbligatorio con code_challenge_method incluso. Per altre informazioni, vedere il PKCE RFC. Questo parametro è ora consigliato per tutti i tipi di applicazione, sia i client pubblici che riservati e richiesti da Microsoft Identity Platform per le app a pagina singola usando il flusso del 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. Microsoft Identity Platform supporta sia plain che S256. Per altre informazioni, vedere il PKCE RFC. Questo parametro è obbligatorio 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. Microsoft Identity Platform garantisce inoltre che l'utente abbia acconsentito alle autorizzazioni indicate nel scope parametro di query. Se l'utente non ha acconsentito ad alcuna di queste autorizzazioni, chiede all'utente di fornire il consenso alle autorizzazioni necessarie. Per altre informazioni, vedere Autorizzazioni e consenso in Microsoft Identity Platform.
Dopo che l'utente viene autenticato e fornisce il consenso, Microsoft Identity Platform restituisce una risposta all'app nell'URI redirect_uri indicato, usando il metodo specificato nel parametro response_mode.
Risposta con esito positivo
Questo esempio mostra una risposta con esito positivo 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 state nella richiesta e nella risposta siano identici. |
È anche possibile ricevere un token ID se si richiede uno e si dispone della concessione implicita abilitata nella registrazione dell'applicazione. Questo comportamento viene talvolta definito flusso ibrido. Viene usato da framework come ASP.NET.
Risposta con 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 errore che può essere usata per classificare i tipi di errore che si verificano e reagire ad essi. Questa parte dell'errore viene fornita in modo che l'app possa reagire in modo appropriato all'errore, ma non spiega in dettaglio il motivo per cui 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 rilevato in genere 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 nell'ID Microsoft Entra o non viene aggiunta al tenant di Microsoft Entra dell'utente. L'applicazione può chiedere all'utente di installare l'applicazione e di aggiungerla a Microsoft Entra ID. |
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 acconsenta. |
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 rilevato in genere 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 può comunicare all'utente che la risposta è stata ritardata a causa di 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, Microsoft Entra ID non è in grado di trovarlo o è configurato in modo non corretto. | Questo errore indica che la risorsa, se esistente, non è stata configurata nel tenant. L'applicazione può chiedere all'utente di installare l'applicazione e di aggiungerla a Microsoft Entra ID. |
login_required |
Troppi utenti 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 attivi più utenti o nessun utente. Questo errore tiene conto del tenant scelto. Ad esempio, se sono presenti due account Microsoft Entra attivi 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 consenso. Ripetere la richiesta senza prompt=none. |
Richiedere un token ID o un flusso ibrido
Per sapere 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 OIDC con il flusso del codice di autorizzazione OAuth2.
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 traggono vantaggio da una latenza ridotta in questo modello.
Il flusso ibrido è uguale al 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=00001111-aaaa-2222-bbbb-3333cccc4444
&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 desidera un token ID nella risposta dall'endpoint /authorize . |
scope |
Obbligatorio | Per i token ID, questo parametro deve essere aggiornato per includere gli ambiti del token ID: openid e facoltativamente profile e email. |
nonce |
Obbligatorio | 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 inviare il token risultante a un'app. Il valore predefinito è query solo per un codice di autorizzazione, ma fragment se la richiesta include un oggetto id_token response_type come 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 leggono 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 con esito positivo
Questo esempio mostra una risposta con esito positivo 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 tramite la concessione implicita. Contiene un'attestazione speciale c_hash che rappresenta l'hash di 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 state nella richiesta e nella risposta siano identici. |
Riscattare un codice per un token di accesso
Tutti i client riservati hanno una scelta di usare i segreti client o le credenziali del certificato. I segreti condivisi simmetrici vengono generati da Microsoft Identity Platform. Le credenziali del certificato sono chiavi asimmetriche caricate dallo sviluppatore. Per altre informazioni, vedere Credenziali del certificato di autenticazione delle applicazioni di Microsoft Identity Platform.
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
Ora che è stata acquisita un'autorizzazione authorization_code ed è stata concessa 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=11112222-bbbb-3333-cccc-4444dddd5555
&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=sampleCredentia1s // 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 |
Obbligatorio | ID applicazione (client) assegnato all'app dall'interfaccia di amministrazione di Microsoft Entra, 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 in Microsoft Identity Platform. Questo parametro è un'estensione Microsoft per il flusso del codice di autorizzazione, progettata per consentire alle app di dichiarare la risorsa per cui vuole il token durante il riscatto del token. |
code |
Obbligatorio | authorization_code acquisito nella prima parte del flusso. |
redirect_uri |
Obbligatorio | 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 nel portale di registrazione dell'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. Come tutti i parametri, il segreto client deve essere codificato con URL prima di essere inviato. Questo passaggio viene eseguito dall'SDK. Per altre informazioni sulla codifica URI, vedere la specifica della sintassi generica URI. È supportato anche il modello di autenticazione di base per fornire le credenziali nell'intestazione dell'autorizzazione, per RFC 6749. |
Richiedere un token di accesso con credenziali del certificato
// Line breaks for legibility only
POST /{tenant}/oauth2/v2.0/token HTTP/1.1
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&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 |
Obbligatorio | ID applicazione (client) assegnato all'app dall'interfaccia di amministrazione di Microsoft Entra, 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 per il 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 |
Obbligatorio | authorization_code acquisito nella prima parte del flusso. |
redirect_uri |
Obbligatorio | 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 utilizzato per ottenere l'oggetto authorization_code. Obbligatorio se è stato usato PKCE nella richiesta di concessione del codice di autorizzazione. 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 tramite segreto condiviso, ad eccezione del fatto che il client_secret parametro viene sostituito da due parametri: a client_assertion_type e client_assertion.
Risposta con esito positivo
Questo esempio mostra una risposta con esito positivo del token:
{
"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 Microsoft Entra ID è Bearer. |
expires_in |
Per quanto tempo il token di accesso è valido, in secondi. |
scope |
Ambiti per cui è access_token valido. Facoltativo. Questo parametro non è standard e, se omesso, il token è per gli ambiti richiesti nella fase 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 altre informazioni sull'aggiornamento di un token di accesso, vedere Aggiornare il token di accesso più avanti in questo articolo. Nota: viene fornito solo è 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 è stato richiesto l'ambito openid. |
Risposta con 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: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: 2016-01-09 02:02:12Z",
"error_codes": [
70011
],
"timestamp": "2016-01-09 02:02:12Z",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
| Parametro | Descrizione |
|---|---|
error |
Stringa di codice errore che può essere usata per classificare i tipi di errore che si verificano e reagire ad essi. |
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 nuovamente 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 nell'ID Microsoft Entra o non viene aggiunta al tenant di Microsoft Entra dell'utente. L'applicazione può chiedere all'utente di installare l'applicazione e di aggiungerla a Microsoft Entra ID. |
invalid_client |
Autenticazione client non riuscita. | Credenziali del client non valide. Per risolvere il problema, l'amministratore di applicazioni aggiorna le credenziali. |
unsupported_grant_type |
Il server di autorizzazione non supporta il tipo di concessione dell'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, Microsoft Entra ID non è in grado di trovarlo o è configurato in modo non corretto. | 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 a Microsoft Entra ID. |
interaction_required |
Non standard, poiché 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 sull'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 la richiesta. |
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 acquisito correttamente un access_tokenoggetto , è possibile usare il token nelle 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 rilasciato 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. Tuttavia, in alcuni casi, 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 a pagina completa 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 rimuovere il token di aggiornamento precedente. La specifica OAuth 2.0 indica: "Il server di autorizzazione PUÒ rilasciare un nuovo token di aggiornamento, nel qual caso il client DEVE eliminare il token di aggiornamento precedente e sostituirlo con il nuovo token di aggiornamento. Il server di autorizzazione PUÒ revocare il token di aggiornamento precedente dopo aver rilasciato 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, pertanto le app devono essere preparate a eseguire nuovamente 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 credenziali e in genere non vedono nemmeno alcuna esperienza utente, ma 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. Questo problema è 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=00001111-aaaa-2222-bbbb-3333cccc4444
&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 applicazione (client) che l'esperienza Interfaccia di amministrazione di Microsoft Entra: Registrazioni app ha assegnato all'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 sezione devono essere equivalenti a o a un subset degli ambiti richiesti nella fase di richiesta originale authorization_code . Se gli ambiti specificati in questa richiesta si estendono su più server di risorse, Microsoft Identity Platform restituisce un token per la risorsa specificata nel primo ambito. Per altre informazioni, vedere Autorizzazioni e consenso in Microsoft Identity Platform. |
refresh_token |
Obbligatorio | 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é non client_secret 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 con esito positivo del token:
{
"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 Microsoft Entra è token di connessione. |
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 è 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 di Microsoft Identity Platform. Nota: viene fornito solo è 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 i servizi Microsoft possono usare un formato speciale che non verrà convalidato come token JWT e potrebbe anche essere crittografato per gli utenti (account Microsoft). Sebbene la lettura dei token sia uno strumento utile per il debug e l'apprendimento, è consigliabile non dipendere da questo per il codice o presupporre specifiche sui token che non sono per un'API che si controlla.
Risposta con 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: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: 2016-01-09 02:02:12Z",
"error_codes": [
70011
],
"timestamp": "2016-01-09 02:02:12Z",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
| Parametro | Descrizione |
|---|---|
error |
Stringa di codice errore che può essere usata per classificare i tipi di errore che si verificano e reagire ad essi. |
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
- Per iniziare a codificare, passare agli esempi di MSAL JS.
- Informazioni sugli scenari di scambio di token.