OpenID Connect in Microsoft Identity Platform

OpenID Connect (OIDC) estende il protocollo di autorizzazione OAuth 2.0 da usare come un altro protocollo di autenticazione. È possibile usare OIDC per abilitare l'accesso Single Sign-On (SSO) tra le applicazioni abilitate per OAuth usando un token di sicurezza denominato token ID.

La specifica completa per OIDC è disponibile nel sito Web di OpenID Foundation all'indirizzo specifica OpenID Connect Core 1.0.

Flusso del protocollo: accesso

Il diagramma seguente illustra il flusso di accesso di base di OpenID Connect. I passaggi del flusso sono descritti in modo più dettagliato nelle sezioni successive dell'articolo.

Abilitare i token ID

Il token ID introdotto da OpenID Connect viene rilasciato dal server di autorizzazione, Microsoft Identity Platform, quando l'applicazione client ne richiede uno durante l'autenticazione utente. Il token ID consente a un'applicazione client di verificare l'identità dell'utente e di ottenere altre informazioni (attestazioni) su di esse.

I token ID non vengono rilasciati per impostazione predefinita per un'applicazione registrata con Microsoft Identity Platform. I token ID per un'applicazione sono abilitati usando uno dei metodi seguenti:

1. Accedi all'Interfaccia di amministrazione di Microsoft Entra.
2. Passare a Identità>Applicazioni>Registrazioni app><la tua applicazione>>Autenticazione.
3. In Configurazioni della piattaforma selezionare Aggiungi una piattaforma.
4. Nel riquadro visualizzato selezionare la piattaforma appropriata per l'applicazione. Ad esempio, selezionare Web per un'applicazione Web.
5. In URI di reindirizzamento aggiungere l'URI di reindirizzamento dell'applicazione. Ad esempio: https://localhost:8080/.
6. In Concessione implicita e flussi ibridi selezionare la casella di controllo token ID (usati per i flussi impliciti e ibridi).

Oppure:

1. Selezionare Identità>Applicazioni>Registrazioni app><la tua applicazione>>Manifesto.
2. Impostare oauth2AllowIdTokenImplicitFlow su true nel manifesto dell'applicazione della registrazione dell'app.

Se i token ID non sono abilitati per l'app e ne viene richiesta una, Microsoft Identity Platform restituisce un unsupported_response errore simile al seguente:

Il valore fornito per il parametro di input 'response_type' non è consentito per questo client. Expected value is 'code' (Il valore fornito per il parametro di input 'response_type' non è consentito per questo client. Il valore previsto è 'code').

La richiesta di un token ID specificando un response_type di id_token è illustrata in Inviare la richiesta di accesso più avanti nell'articolo.

Recuperare il documento di configurazione OpenID

I provider OpenID come Microsoft Identity Platform forniscono un Documento di configurazione del provider OpenID in un endpoint accessibile pubblicamente contenente gli endpoint OIDC del provider, le attestazioni supportate e altri metadati. Le applicazioni client possono usare i metadati per individuare gli URL da usare per l'autenticazione e le chiavi di firma pubblica del servizio di autenticazione.

Le librerie di autenticazione sono gli utenti più comuni del documento di configurazione OpenID, che usano per l'individuazione degli URL di autenticazione, delle chiavi di firma pubblica del provider e di altri metadati del servizio. Se nell'app viene usata una libreria di autenticazione, è probabile che non sia necessario inviare a mano le richieste di codice e le risposte dall'endpoint del documento di configurazione OpenID.

Trovare l'URI del documento di configurazione OpenID dell'app

A ogni registrazione dell'app in Microsoft Entra ID viene fornito un endpoint accessibile pubblicamente che serve il documento di configurazione OpenID. Per determinare l'URI dell'endpoint del documento di configurazione per l'app, aggiungere il percorso di configurazione OpenID noto all'URL dell'autorità di registrazione dell'app.

• Percorso del documento di configurazione noto: /.well-known/openid-configuration
• URL dell'autorità: https://login.microsoftonline.com/{tenant}/v2.0

Il valore di {tenant} varia in base al gruppo di destinatari che accede all'applicazione, come illustrato nella tabella seguente. L'URL dell'autorità varia anche in base all'istanza cloud.

Per trovare il documento di configurazione OIDC nell'Interfaccia di amministrazione di Microsoft Entra, accedere all'Interfaccia di amministrazione di Microsoft Entra e quindi:

1. Passare a Identità>Applicazioni>Registrazioni app><la tua applicazione>>Endpoint.
2. Individuare l'URI in Documento dei metadati openID Connect.

Esempio di richiesta

La richiesta seguente ottiene i metadati di configurazione OpenID dall'endpoint del documento di configurazione OpenID dell'autorità di common nel cloud pubblico di Azure:

GET /common/v2.0/.well-known/openid-configuration
Host: login.microsoftonline.com

Risposta di esempio

I metadati di configurazione vengono restituiti in formato JSON, come illustrato nell'esempio seguente (troncato per brevità). I metadati restituiti nella risposta JSON sono descritti in dettaglio nella specifica di individuazione OpenID Connect 1.0.

{
  "authorization_endpoint": "https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize",
  "token_endpoint": "https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token",
  "token_endpoint_auth_methods_supported": [
    "client_secret_post",
    "private_key_jwt"
  ],
  "jwks_uri": "https://login.microsoftonline.com/{tenant}/discovery/v2.0/keys",
  "userinfo_endpoint": "https://graph.microsoft.com/oidc/userinfo",
  "subject_types_supported": [
      "pairwise"
  ],
  ...
}

Inviare la richiesta di accesso

Per autenticare un utente e richiedere un token ID da usare nell'applicazione, indirizzare l'agente-utente all'endpoint /authorize di Microsoft Identity Platform. La richiesta è simile a quella della prima parte del flusso del codice di autorizzazione di OAuth 2.0, con alcune importanti differenze:

• Includere l'ambito openid nel parametro scope.
• Specificare id_token nel parametro response_type.
• Includere il parametro nonce.

Richiesta di accesso di esempio (interruzioni di riga incluse solo per la leggibilità):

GET https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&response_type=id_token
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=form_post
&scope=openid
&state=12345
&nonce=678910

A questo punto, all'utente viene chiesto di immettere le credenziali e completare l'autenticazione. Microsoft Identity Platform garantisce che l'utente abbia dato il consenso alle autorizzazioni indicate nel parametro di query scope. Se l'utente non ha dato il consenso per alcuna autorizzazione, Microsoft Identity Platform chiede all'utente di dare il consenso per le autorizzazioni obbligatorie. Sono disponibili altre informazioni su autorizzazioni, consenso e app multi-tenant.

Dopo che l'utente ha eseguito l'autenticazione e dato il consenso, Microsoft Identity Platform restituisce una risposta all'app nell'URI di reindirizzamento indicato usando il metodo specificato nel parametro response_mode.

Risposta con esito positivo

La risposta con esito positivo quando si usa response_mode=form_post è simile alla seguente:

POST /myapp/ HTTP/1.1
Host: localhost
Content-Type: application/x-www-form-urlencoded

id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNB...&state=12345

Risposta con errore

Le risposte di errore possono essere inviate anche all'URI di reindirizzamento in modo che l'app possa gestirle, ad esempio:

POST /myapp/ HTTP/1.1
Host: localhost
Content-Type: application/x-www-form-urlencoded

error=access_denied&error_description=the+user+canceled+the+authentication

Codici per gli errori dell'endpoint di autorizzazione

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

Convalidare il token ID

La ricezione di un token ID nell'app potrebbe non essere sempre sufficiente per autenticare completamente l'utente. Potrebbe anche essere necessario convalidare la firma del token ID e verificarne le attestazioni in base ai requisiti dell'app. Come tutti i provider OpenID, i token ID di Microsoft Identity Platform sono token JSON Web (JWT) firmati usando la crittografia a chiave pubblica.

Le app Web e le API Web che usano token ID per l'autorizzazione devono convalidarle perché tali applicazioni ottengono l'accesso ai dati. Altri tipi di applicazione potrebbero tuttavia non trarre vantaggio dalla convalida del token ID. Le applicazioni native e a pagina singola (SPA), ad esempio, raramente traggono vantaggio dalla convalida dei token ID perché qualsiasi entità con accesso fisico al dispositivo o al browser può potenzialmente ignorare la convalida.

Di seguito sono riportati due esempi di evitamento di convalida dei token:

• Fornire token falsi o chiavi modificando il traffico di rete nel dispositivo
• Debug dell'applicazione ed esecuzione della logica di convalida durante l'esecuzione del programma.

Se si convalidano i token ID nell'applicazione, è consigliabile non farlo manualmente. Usare invece una libreria di convalida dei token per analizzare e convalidare i token. Le librerie di convalida dei token sono disponibili per la maggior parte dei linguaggi di sviluppo, dei framework e delle piattaforme.

Cosa convalidare in un token ID

Oltre a convalidare la firma del token ID, è necessario convalidare diverse attestazioni come descritto in Convalida di un token ID. Vedere anche Informazioni importanti sulla firma dell'effetto di attivazione della chiave.

Diverse altre convalide sono comuni e variano in base agli scenari dell'applicazione, tra cui:

• Garantire che l'utente o l'organizzazione dispongano dell'iscrizione all'app.
• Garantire che l'utente disponga di autorizzazioni/privilegi adeguati.
• Garantire che sia stato applicato un determinato livello di autenticazione, ad esempio l'autenticazione a più fattori.

Dopo aver convalidato il token ID, è possibile iniziare una sessione con l'utente e usare le informazioni nelle attestazioni del token per la personalizzazione, la visualizzazione o l'archiviazione dei dati.

Diagramma di protocollo: acquisizione dei token di accesso

Molte applicazioni non solo devono dare l'accesso a un utente, ma anche a una risorsa protetta come un'API Web per conto dell'utente. Questo scenario combina OpenID Connect per ottenere un token ID per l'autenticazione dell'utente e OAuth 2.0 per ottenere un token di accesso per una risorsa protetta.

Il flusso completo di accesso OpenID Connect e di acquisizione dei token è simile a quello illustrato nel diagramma:

Ottenere un token di accesso per l'endpoint UserInfo

Oltre al token ID, le informazioni dell'utente autenticato vengono rese disponibili anche nell'endpoint UserInfo OIDC.

Per ottenere un token di accesso per l'endpoint UserInfo OIDC, modificare la richiesta di accesso come descritto di seguito:

// Line breaks are for legibility only.

GET https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444        // Your app registration's Application (client) ID
&response_type=id_token%20token                       // Requests both an ID token and access token
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F       // Your application's redirect URI (URL-encoded)
&response_mode=form_post                              // 'form_post' or 'fragment'
&scope=openid+profile+email                           // 'openid' is required; 'profile' and 'email' provide information in the UserInfo endpoint as they do in an ID token. 
&state=12345                                          // Any value - provided by your app
&nonce=678910                                         // Any value - provided by your app

È possibile usare il flusso del codice di autorizzazione, il flusso del codice del dispositivo o un token di aggiornamento al posto di response_type=token per ottenere un token di accesso per l'app.

Risposta del token riuscita

Risposta con esito positivo usando response_mode=form_post:

POST /myapp/ HTTP/1.1
Host: localhost
Content-Type: application/x-www-form-urlencoded
 access_token=eyJ0eXAiOiJKV1QiLCJub25jZSI6I....
 &token_type=Bearer
 &expires_in=3598
 &scope=email+openid+profile
 &id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI....
 &state=12345

I parametri di risposta indicano la stessa cosa indipendentemente dal flusso usato per acquisirli.

Risposta con errore

Le risposte di errore possono essere inviate anche all'URI di reindirizzamento in modo che l'app possa gestirle adeguatamente:

POST /myapp/ HTTP/1.1
Host: localhost
Content-Type: application/x-www-form-urlencoded

error=access_denied&error_description=the+user+canceled+the+authentication

Per una descrizione dei possibili codici di errore e delle risposte client consigliate, vedere Codici per gli errori dell'endpoint di autorizzazione.

Dopo aver ottenuto un codice di autorizzazione e un token ID, è possibile far accedere l'utente e ottenere i token di accesso per suo conto. Per far accedere l'utente, è necessario convalidare il token ID come descritto in valida token. Per ottenere i token di accesso, seguire la procedura descritta nella documentazione del flusso del codice OAuth.

Chiamata dell'endpoint UserInfo

Esaminare la documentazione UserInfo per esaminare come chiamare l'endpoint UserInfo con questo token.

Inviare una richiesta di disconnessione

Per disconnettere un utente, eseguire entrambe le operazioni seguenti:

1. Reindirizzare l'agente-utente dell'utente all'URI di disconnessione di Microsoft Identity Platform.
2. Cancellare i cookie dell'app o terminare la sessione dell'utente nell'applicazione.

Se non si esegue una di queste operazioni, l'utente potrebbe rimanere autenticato e non ricevere la richiesta di accesso al successivo uso dell'app.

Reindirizzare l'agente-utente al end_session_endpoint come illustrato nel documento di configurazione di OpenID Connect. Il end_session_endpoint supporta sia le richieste HTTP GET che POST.

GET https://login.microsoftonline.com/common/oauth2/v2.0/logout?
post_logout_redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F

Single Sign-Out

Quando si reindirizza l'utente a end_session_endpoint in un'applicazione, Microsoft Identity Platform termina la sessione utente per questa applicazione. Tuttavia, l'utente potrebbe comunque accedere ad altre applicazioni che usano gli stessi account Microsoft per l'autenticazione.

Quando un utente ha eseguito l'accesso a più applicazioni Web o a pagina singola registrate in questa directory (nota anche come tenant) consente a questo utente di disconnettersi immediatamente da tutte le applicazioni disconnettendosi in una delle applicazioni.

Per abilitare l'accesso Single Sign-Out per l'applicazione Entra, è necessario usare la funzionalità di disconnessione del canale front-end OpenID Connect. Questa funzionalità consente a un'applicazione di notificare ad altre applicazioni che l'utente ha disconnesso. Quando l'utente esce da un'applicazione, Microsoft Identity Platform invia una richiesta HTTP GET all'URL di disconnessione del canale anteriore di ogni applicazione a cui l'utente ha eseguito l'accesso.

Queste applicazioni devono rispondere a questa richiesta eseguendo le due azioni seguenti per il completamento dell'accesso Single Sign-Out:

1. Cancellare qualsiasi sessione che identifichi l'utente.
2. Le applicazioni devono rispondere a questa richiesta cancellando qualsiasi sessione che identifica l'utente e restituendo una risposta 200.

Che cos'è un URL di disconnessione del canale anteriore?

Un URL di disconnessione del canale anteriore è il punto in cui l'applicazione Web o SPA riceve la richiesta di disconnessione dal server di autenticazione Entra ed esegue la funzionalità di single sign-out. Ogni applicazione ha un URL di disconnessione del canale anteriore.

Quando è necessario impostare un URL di disconnessione del canale anteriore?

Se l'utente o lo sviluppatore ha determinato che l'accesso Single Sign-Out è necessario per un'applicazione, è necessario impostare l'URL di disconnessione del canale anteriore per la registrazione dell'app dell'applicazione. Dopo aver impostato l'URL di disconnessione del canale anteriore per la registrazione dell'app dell'applicazione, Microsoft Identity Platform invia una richiesta HTTP GET all'URL di disconnessione front-channel di questa applicazione quando l'utente connesso ha disconnesso un'altra applicazione.

Come configurare l'accesso Single Sign-Out usando la funzionalità di disconnessione del canale front-end

Per usare la funzionalità di disconnessione del canale anteriore per un set di applicazioni, è necessario completare le due attività seguenti:

• Impostare l'URL di disconnessione del canale anteriore nell'interfaccia di amministrazione di Microsoft Entra per tutte le applicazioni che devono essere disconnesse contemporaneamente. Ogni applicazione ha in genere un proprio URL di disconnessione del canale anteriore dedicato.
• Modificare il codice delle applicazioni in modo che ascoltino una richiesta HTTP GET inviata da Microsoft Identity Platform all'URL di disconnessione del canale anteriore e rispondano a questa richiesta cancellando qualsiasi sessione che identifica l'utente e restituendo una risposta 200.

Come scegliere un URL di disconnessione del canale anteriore

L'URL di disconnessione del canale anteriore deve essere un URL in grado di ricevere e rispondere alle richieste HTTP GET e deve essere in grado di cancellare qualsiasi sessione che identifica l'utente. Di seguito sono riportati alcuni esempi di URL di disconnessione del canale anteriore:

• https://example.com/frontchannel_loout
• https://example.com/signout
• https://example.com/logout

Passaggi successivi

• Esaminare la documentazione dell'endpoint UserInfo.
• Popolare i valori delle attestazioni in un token con i dati dei sistemi locali.
• Includere attestazioni personalizzate nei token.