Flusso di concessione implicita di Microsoft Identity Platform e OAuth 2.0

Microsoft Identity Platform supporta il flusso di concessione implicita OAuth 2.0, come descritto nella specifica OAuth 2.0. La caratteristica che definisce la concessione implicita è che i token (token ID o token di accesso) vengono restituiti direttamente dall'endpoint /authorize anziché dall'endpoint /token. Questa operazione viene spesso usata come parte del flusso del codice di autorizzazione, in quanto viene chiamato "flusso ibrido" - recuperando il token ID nella richiesta /authorize insieme a un codice di autorizzazione.

Questo articolo descrive come programmare direttamente sul protocollo nell'applicazione per richiedere token da Microsoft Entra ID. Quando possibile, è consigliabile usare le librerie di autenticazione Microsoft (MSAL) supportate anziché acquisire i token e chiamare le API Web protette. Vedere anche le app di esempio che usano MSAL.

Preferisce il flusso del codice di autenticazione

Con i piani per la rimozione di cookie di terze parti dai browser, il flusso di concessione implicita non è più un metodo di autenticazione appropriato. Le funzionalità di Single Sign-On (SSO) invisibile all'utente del flusso implicito non funzionano senza cookie di terze parti, causando l'interruzione delle applicazioni quando tentano di ottenere un nuovo token. È consigliabile che tutte le nuove applicazioni usino il flusso del codice di autorizzazione che supporta ora app a pagina singola al posto del flusso implicito. Anche le app a pagina singola esistenti devono eseguire la migrazione al flusso del codice di autorizzazione.

Scenari adatti alla concessione implicita OAuth2

La concessione implicita è affidabile solo per la parte iniziale interattiva del flusso di accesso, in cui la mancanza di cookie di terze parti non influisce sull'applicazione. Questa limitazione significa che è consigliabile usarla esclusivamente come parte del flusso ibrido, in cui l'applicazione richiede un codice e un token dall'endpoint di autorizzazione. In un flusso ibrido, l'applicazione riceve un codice che può essere riscattato per un token di aggiornamento, assicurando così che la sessione di accesso dell'app rimanga valida nel tempo.

Diagramma del protocollo

Il diagramma seguente illustra l'aspetto dell'intero flusso di accesso implicito e le sezioni che seguono descrivono in dettaglio ogni passaggio.

Diagram showing the implicit sign-in flow

Inviare la richiesta di accesso

Per consentire inizialmente all'utente di accedere all'app, è possibile inviare una richiesta di autenticazione OpenID Connessione e ottenere un oggetto id_token da Microsoft Identity Platform.

Importante

Per richiedere correttamente un token ID e/o un token di accesso, la registrazione dell'app nell'interfaccia di amministrazione di Microsoft Entra - Registrazioni app pagina deve avere il flusso di concessione implicita corrispondente abilitato, selezionando token ID e token di accesso nella sezione Concessione implicita e flussi ibridi. Se non è abilitato, verrà restituito un unsupported_response errore:

The provided value for the input parameter 'response_type' is not allowed for this client. Expected value is 'code'

// Line breaks for legibility only

https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=535fb089-9ff3-47b6-9bfb-4f1264799865
&response_type=id_token
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&scope=openid
&response_mode=fragment
&state=12345
&nonce=678910
Parametro Tipo Descrizione
tenant Obbligatorio Il valore {tenant} del percorso della richiesta può essere usato per controllare chi può accedere all'applicazione. I valori consentiti sono common, organizations, consumers e gli identificatori del tenant. Per altri dettagli, vedere Nozioni di base sul protocollo. In modo critico, 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 corretto al tenant della risorsa.
client_id Obbligatorio ID applicazione (client) assegnato all'app dall'interfaccia di amministrazione di Microsoft Entra- Registrazioni app pagina.
response_type Obbligatorio Deve includere id_token per l'accesso a OpenID Connect. Può includere anche , response_typetoken. Usando qui il token , l'app può ricevere immediatamente un token di accesso dall'endpoint di autorizzazione senza dover inviare una seconda richiesta a tale endpoint. Se si usa il token response_type, il scope parametro deve contenere un ambito che indica la risorsa per cui rilasciare il token, ad esempio user.read in Microsoft Graph. Può anche contenere code al posto di fornire un codice di token autorizzazione, da usare nel flusso del codice di autorizzazione. Questa id_token+code risposta viene talvolta chiamata flusso ibrido.
redirect_uri consigliato URI di reindirizzamento dell'app dove le risposte di autenticazione possono essere inviate e ricevute dall'app. Deve corrispondere esattamente a uno degli URI di reindirizzamento registrati nel portale, ad eccezione del fatto che deve essere codificato in URL.
scope Obbligatorio Elenco di ambiti separati da spazi. Per OpenID Connessione (id_tokens), deve includere l'ambito openid, che si traduce nell'autorizzazione "Accedi" nell'interfaccia utente del consenso. Facoltativamente, è anche possibile includere gli email ambiti e profile per ottenere l'accesso a dati utente aggiuntivi. È anche possibile includere altri ambiti in questa richiesta per richiedere il consenso a varie risorse, se viene richiesto un token di accesso.
response_mode facoltative Specifica il metodo da usare per inviare il token risultante a un'app. L'impostazione predefinita è eseguire una query solo per un token di accesso, ma frammento se la richiesta include un id_token.
state consigliato Valore incluso nella richiesta che verrà restituito anche 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 parametro state viene anche usato per codificare le informazioni sullo stato dell'utente nell'app attivo prima dell'esecuzione della richiesta di autenticazione, ad esempio la pagina o la vista attiva.
nonce Obbligatorio Valore incluso nella richiesta, generato dall'app, che verrà incluso nel token ID 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. Obbligatorio solo quando viene richiesto un valore id_token.
prompt facoltative Indica il tipo di interazione utente richiesto. Gli unici valori validi al momento sono login, none, select_accounte consent. prompt=login forza l'utente a immettere le sue credenziali alla richiesta, negando l'accesso Single Sign-On. prompt=none è l'opposto: garantisce che all'utente non venga presentata alcuna richiesta interattiva. Se la richiesta non può essere completata automaticamente tramite SSO, Microsoft Identity Platform restituirà un errore. prompt=select_account invia l'utente a un selettore di account in cui verranno visualizzati tutti gli account memorizzati nella sessione. 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.
login_hint facoltative È possibile usare questo parametro per pre-compilare i campi nome utente e indirizzo di posta elettronica nella pagina di accesso, se già si conosce il nome utente. Spesso le app usano questo parametro durante la riautenticazione, dopo aver già estratto l'attestazione login_hint facoltativa da un accesso precedente.
domain_hint facoltative Se incluso, ignora il processo di individuazione basato sulla posta elettronica che l'utente passa attraverso la pagina di accesso, con un'esperienza utente leggermente più semplificata. Questo parametro viene comunemente usato per le app line-of-business che operano in un singolo tenant, in cui forniranno un nome di dominio all'interno di un determinato tenant, inoltrando l'utente al provider federativo per tale tenant. Questo hint impedisce agli utenti guest di accedere a questa applicazione e limita l'uso di credenziali cloud come FIDO.

A questo punto, all'utente verrà richiesto 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 a nessuna di queste autorizzazioni, l'endpoint chiederà all'utente di fornire il consenso per le autorizzazioni obbligatorie. Per altre informazioni, vedere autorizzazioni, consenso e app multi-tenant.

Dopo che l'utente esegue l'autenticazione e concede il consenso, Microsoft Identity Platform restituisce una risposta all'app in corrispondenza dell'oggetto indicato redirect_uriusando il metodo specificato nel response_mode parametro .

Risposta riuscita

Una risposta con esito positivo che usa response_mode=fragment e response_type=id_token+code è simile a quanto riportato di seguito. Sono state aggiunte interruzioni di riga per migliorare la leggibilità:

GET https://localhost/myapp/#
code=0.AgAAktYV-sfpYESnQynylW_UKZmH-C9y_G1A
&id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...
&state=12345
Parametro Descrizione
code Incluso se response_type include code. È un codice di autorizzazione adatto per l'uso nel flusso del codice di autorizzazione.
access_token Incluso se response_type include token. Token di accesso richiesto dall'app. Il token di accesso non deve essere decodificato o controllato in altro modo, deve essere considerato come una stringa opaca.
token_type Incluso se response_type include token. Sarà sempre Bearer.
expires_in Incluso se response_type include token. Indica il numero di secondi di validità del token, ai fini della memorizzazione nella cache.
scope Incluso se response_type include token. Indica gli ambiti per i quali avrà validità access_token. Potrebbe non includere tutti gli ambiti richiesti se non sono applicabili all'utente. Ad esempio, gli ambiti solo Entra di Microsoft richiesti durante l'accesso tramite un account personale.
id_token Token JSON Web (JWT) 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 sui token ID, vedere .id_token reference
Nota: viene fornito solo se openid l'ambito è stato richiesto e response_type incluso id_tokens.
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.

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 servizi Microsoft 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 con errore

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

GET https://localhost/myapp/#
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 che si verificano e correggerli.
error_description Messaggio di errore specifico che consente a uno sviluppatore di identificare la causa principale di un errore di autenticazione.

Acquisire i token di accesso in modo invisibile all'utente

Importante

Questa parte del flusso implicito è improbabile che funzioni per l'applicazione perché viene usata in diversi browser a causa della rimozione di cookie di terze parti per impostazione predefinita. Anche se questo funziona ancora nei browser basati su Chromium che non sono in incognito, gli sviluppatori dovrebbero riconsiderare l'uso di questa parte del flusso. Nei browser che non supportano cookie di terze parti, si riceverà un errore che indica che nessun utente è connesso, perché i cookie di sessione della pagina di accesso sono stati rimossi dal browser.

Dopo aver eseguito l'accesso dell'utente all'app a pagina singola, è possibile ottenere automaticamente i token di accesso per chiamare le API Web protette da Microsoft Identity Platform, ad esempio Microsoft Graph. Anche se è già stato ricevuto un token usando il token response_type, è possibile usare questo metodo per acquisire i token a risorse aggiuntive senza reindirizzare l'utente per eseguire di nuovo l'accesso.

Nel normale flusso OpenID Connessione/OAuth eseguire questa operazione effettuando una richiesta all'endpoint di Microsoft Identity Platform/token. È possibile effettuare la richiesta in un iframe nascosto per ottenere nuovi token per altre API Web:

// Line breaks for legibility only

https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=535fb089-9ff3-47b6-9bfb-4f1264799865
&response_type=token
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fuser.read
&response_mode=fragment
&state=12345
&nonce=678910
&prompt=none
&login_hint=myuser@mycompany.com

Per informazioni dettagliate sui parametri di query nell'URL, vedere Inviare la richiesta di accesso.

Suggerimento

Prova a copiare e incollare la richiesta seguente in una scheda del browser. (Non dimenticare di sostituire i valori login_hint con i valori corretti per l'utente)

https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id=535fb089-9ff3-47b6-9bfb-4f1264799865&response_type=token&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F&scope=https%3A%2F%2Fgraph.microsoft.com%2Fuser.read&response_mode=fragment&state=12345&nonce=678910&prompt=none&login_hint={your-username}

Si noti che questo funzionerà anche nei browser senza supporto di cookie di terze parti, poiché si sta immettendo direttamente in una barra del browser invece di aprirlo all'interno di un iframe.

Con il parametro prompt=none , questa richiesta avrà immediatamente esito positivo o negativo e farà tornare all'applicazione. La risposta verrà inviata all'app in corrispondenza dell'oggetto indicato redirect_uriusando il metodo specificato nel response_mode parametro .

Risposta riuscita

Una risposta con esito positivo che usa response_mode=fragment ha un aspetto simile al seguente:

GET https://localhost/myapp/#
access_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...
&state=12345
&token_type=Bearer
&expires_in=3599
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fdirectory.read
Parametro Descrizione
access_token Incluso se response_type include token. Token di accesso richiesto dall'app, in questo caso per Microsoft Graph. Il token di accesso non deve essere decodificato o controllato in altro modo, deve essere considerato come una stringa opaca.
token_type Sarà sempre Bearer.
expires_in Indica il numero di secondi di validità del token, ai fini della memorizzazione nella cache.
scope Indica gli ambiti per i quali il token di accesso sarà valido. Potrebbe non includere tutti gli ambiti richiesti, se non sono applicabili all'utente (nel caso di ambiti solo Entra di Microsoft richiesti quando viene usato un account personale per l'accesso).
id_token Token JSON Web (JWT) firmato. Incluso se response_type include id_token. 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 sugli oggetti id_token, vedere le informazioni di riferimento su id_token.
Nota: viene fornito solo è stato richiesto l'ambito openid.
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.

Risposta con errore

Le risposte di errore possono essere inviate anche a redirect_uri , in modo che l'app possa gestirle adeguatamente. Nel caso di prompt=none, un errore previsto sarà:

GET https://localhost/myapp/#
error=user_authentication_required
&error_description=the+request+could+not+be+completed+silently
Parametro Descrizione
error Stringa di codice di errore che può essere usata per classificare i tipi di errori che si verificano e correggerli.
error_description Messaggio di errore specifico che consente a uno sviluppatore di identificare la causa principale di un errore di autenticazione.

Se si riceve questo errore nella richiesta iframe, l'utente deve accedere di nuovo in modo interattivo per recuperare un nuovo token. È possibile scegliere di gestire questa situazione in qualsiasi modo appropriato per l'applicazione.

Aggiornare i token

La concessione implicita non fornisce token di aggiornamento. Entrambi i token ID e i token di accesso scadono dopo un breve periodo di tempo, quindi l'app deve essere preparata per aggiornare periodicamente questi token. Per aggiornare uno dei due tipi di token, è possibile eseguire la stessa richiesta iframe nascosta precedente usando il parametro per controllare il prompt=none comportamento di Identity Platform. Se si vuole ricevere un nuovo token ID, assicurarsi di usare id_token in response_type e scope=openid, nonché un nonce parametro .

Nei browser che non supportano cookie di terze parti, verrà generato un errore che indica che nessun utente ha eseguito l'accesso.

Inviare una richiesta di disconnessione

Il Connessione end_session_endpoint OpenID consente all'app di inviare una richiesta a Microsoft Identity Platform per terminare la sessione di un utente e cancellare i cookie impostati da Microsoft Identity Platform. Per disconnettere completamente un utente da un'applicazione Web, l'app deve terminare la sessione in cui è presente l'utente (in genere cancellando la cache di un token o eliminando i cookie) e quindi reindirizzare il browser all'indirizzo seguente:

https://login.microsoftonline.com/{tenant}/oauth2/v2.0/logout?post_logout_redirect_uri=https://localhost/myapp/
Parametro Tipo Descrizione
tenant Obbligatorio Il valore {tenant} del percorso della richiesta può essere usato per controllare chi può accedere all'applicazione. I valori consentiti sono common, organizations, consumers e gli identificatori del tenant. Per altre informazioni, vedere le nozioni di base sul protocollo.
post_logout_redirect_uri consigliato URL di destinazione al quale l'utente deve essere reindirizzato dopo la disconnessione. Questo valore deve corrispondere a uno degli URI di reindirizzamento registrati per l'applicazione. Se non è incluso, l'utente visualizzerà un messaggio generico da Microsoft Identity Platform.

Passaggi successivi

  • Per iniziare a codificare, passare agli esempi di MSAL JS.
  • Esaminare il flusso del codice di autorizzazione come alternativa più recente e migliore alla concessione implicita.