Condividi tramite

Autorizzare l'accesso alle applicazioni Web usando OpenID Connect e Azure Active Directory

Avvertimento

Questo contenuto riguarda l'endpoint di Azure AD v1.0 precedente. Usare l' Microsoft Identity Platform per i nuovi progetti.

OpenID Connect è un livello di identità semplice basato sul protocollo OAuth 2.0. OAuth 2.0 definisce meccanismi per ottenere e usare i token di accesso per accedere alle risorse protette, ma non definiscono metodi standard per fornire informazioni sull'identità. OpenID Connect implementa l'autenticazione come estensione per il processo di autorizzazione OAuth 2.0. Fornisce informazioni sull'utente finale sotto forma di un id_token che verifica l'identità e fornisce informazioni di base sul profilo dell'utente.

OpenID Connect è consigliabile se si sta creando un'applicazione Web ospitata in un server e a cui si accede tramite un browser.

Registrare un'applicazione con il tenant di Active Directory

Prima di tutto, registrare l'applicazione con il tenant di Azure Active Directory (Azure AD). In questo modo verrà assegnato un ID applicazione per l'applicazione, oltre a abilitarlo per ricevere i token.

  1. Accedere al portale di Azure.

  2. Scegliere il tenant di Azure AD selezionando l'account nell'angolo superiore destro della pagina, quindi navigando su Cambia directory e selezionando il tenant appropriato.

    • Ignorare questo passaggio se si ha un solo tenant di Azure AD nell'account o se è già stato selezionato il tenant di Azure AD appropriato.

  3. Nel portale di Azure cercare e selezionare Azure Active Directory.

  4. Nel menu azure Active Directory a sinistra selezionare Registrazioni appe quindi selezionare Nuova registrazione.

  5. Seguire le istruzioni e creare una nuova applicazione. Non importa se si tratta di un'applicazione web o di un client pubblico (mobile & desktop) per questo tutorial, ma se desideri esempi specifici per applicazioni web o client pubblici, consulta le guide rapide .

    • Nome è il nome dell'applicazione e descrive l'applicazione agli utenti finali.
    • In Tipi di account supportati, seleziona Account in qualsiasi directory organizzativa e account Microsoft personali.
    • Specificare l'URI di reindirizzamento . Per le applicazioni Web, si tratta dell'URL di base dell'app in cui gli utenti possono accedere. Ad esempio: http://localhost:12345. Per il client pubblico (mobile & desktop), Azure AD lo utilizza per restituire le risposte dei token. Immettere un valore specifico per l'applicazione. Ad esempio: http://MyFirstAADApp.

  6. Dopo aver completato la registrazione, Azure AD assegnerà all'applicazione un identificatore client univoco (l'ID applicazione ). Questo valore è necessario nelle sezioni successive, quindi copiarlo dalla pagina dell'applicazione.

  7. Per trovare l'applicazione nel portale di Azure, selezionare Registrazioni appe quindi selezionare Visualizza tutte le applicazioni.

Flusso di autenticazione con OpenID Connect

Il flusso di accesso più semplice contiene i passaggi seguenti: ognuno di essi è descritto in dettaglio di seguito.

Flusso di autenticazione OpenId Connect

Documento di metadati OpenID Connect

OpenID Connect descrive un documento di metadati che contiene la maggior parte delle informazioni necessarie per l'esecuzione dell'accesso da parte di un'app. Sono incluse informazioni quali gli URL da usare e la posizione delle chiavi di firma pubbliche del servizio. Il documento di metadati OpenID Connect è disponibile all'indirizzo:

https://login.microsoftonline.com/{tenant}/.well-known/openid-configuration

I metadati sono un semplice documento JSON (JavaScript Object Notation). Per un esempio, vedere il frammento di codice seguente. Il contenuto del frammento è descritto in modo completo nella specifica OpenID Connect. Si noti che specificando un ID tenant anziché common al posto di {tenant} precedente, gli URI specifici del tenant verranno restituiti nell'oggetto JSON.

{
    "authorization_endpoint": "https://login.microsoftonline.com/{tenant}/oauth2/authorize",
    "token_endpoint": "https://login.microsoftonline.com/{tenant}/oauth2/token",
    "token_endpoint_auth_methods_supported":
    [
        "client_secret_post",
        "private_key_jwt",
        "client_secret_basic"
    ],
    "jwks_uri": "https://login.microsoftonline.com/common/discovery/keys"
    "userinfo_endpoint":"https://login.microsoftonline.com/{tenant}/openid/userinfo",
    ...
}

Se l'app ha chiavi di firma personalizzate in seguito all'uso della funzionalità di mapping delle attestazioni , devi aggiungere un appid parametro di query contenente l'ID app per ottenere informazioni jwks_uri sulla chiave di firma dell'app. Ad esempio: https://login.microsoftonline.com/{tenant}/.well-known/openid-configuration?appid=6731de76-14a6-49ae-97bc-6eba6914391e contiene un jwks_uri di https://login.microsoftonline.com/{tenant}/discovery/keys?appid=6731de76-14a6-49ae-97bc-6eba6914391e.

Inviare la richiesta di accesso

Quando l'applicazione Web deve autenticare l'utente, deve indirizzare l'utente all'endpoint /authorize . Questa richiesta è simile alla prima parte del flusso del codice di autorizzazione OAuth 2.0, con alcune differenze importanti:

  • La richiesta deve includere l'ambito openid nel scope parametro .
  • Il response_type parametro deve includere id_token.
  • La richiesta deve includere il nonce parametro .

Una richiesta di esempio sarà quindi simile alla seguente:

// Line breaks for legibility only

GET https://login.microsoftonline.com/{tenant}/oauth2/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&response_type=id_token
&redirect_uri=http%3A%2F%2Flocalhost%3a12345
&response_mode=form_post
&scope=openid
&state=12345
&nonce=7362CAEA-9CA5-4B43-9BA3-34D7C303EBA7
Parametro TIPO Descrizione
inquilino Obbligatorio Il valore {tenant} del percorso della richiesta può essere usato per controllare chi può accedere all'applicazione. I valori consentiti sono identificatori del tenant, ad esempio 8eaef023-2b34-4da1-9baa-8bc8c9d6a490 o contoso.onmicrosoft.com o common per i token indipendenti dal tenant
ID cliente Obbligatorio ID applicazione assegnato all'app quando è stato registrato con Azure AD. È possibile trovarla nel portale di Azure. Fare clic su Azure Active Directory, fare clic su Registrazioni app, scegliere l'applicazione e individuare l'ID applicazione nella pagina dell'applicazione.
tipo_di_risposta Obbligatorio Deve includere id_token per l'accesso a OpenID Connect. Può includere anche altri response_types, ad esempio code o token.
scopo consigliato La specifica OpenID Connect richiede l'ambito openid, che si traduce nel permesso "Accedi" nell'interfaccia utente di consenso. Questo e altri ambiti OIDC vengono ignorati nell'endpoint v1.0, ma è comunque una procedura consigliata per i client conformi agli standard.
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 o GUID che può essere usata per identificare l'origine della richiesta.
uri_di_reindirizzamento consigliato L'URI di reindirizzamento della tua app, dove le risposte di autenticazione possono essere inviate e ricevute dalla tua app. Deve corrispondere esattamente a uno dei redirect_uris registrati nel portale, ad eccezione del fatto che deve essere codificato in URL. Se mancante, l'agente utente verrà inviato a uno degli URI di reindirizzamento registrati per l'app, in modo casuale. La lunghezza massima è di 255 byte
modalità_di_risposta opzionale Specifica il metodo che deve essere usato per inviare il authorization_code risultante all'app. I valori supportati sono form_post per il post del modulo HTTP e fragment per il frammento di URL. Per le applicazioni Web, è consigliabile usare response_mode=form_post per garantire il trasferimento più sicuro dei token all'applicazione. Il valore predefinito per qualsiasi flusso, incluso un id_token, è fragment.
stato consigliato Valore incluso nella richiesta restituita nella risposta del token. Può trattarsi di una stringa di qualsiasi contenuto desiderato. Per prevenire gli attacchi di Cross-Site Request Forgery (CSRF), viene generalmente utilizzato un valore univoco generato casualmente. Il parametro state viene anche utilizzato per codificare le informazioni sullo stato dell'utente nell'app prima che avvenisse la richiesta di autenticazione, come la pagina o la vista in cui si trovavano.
richiesta opzionale Indica il tipo di interazione utente richiesto. Attualmente, gli unici valori validi sono 'login', 'none' e 'consent'. prompt=login forza l'utente a inserire le proprie credenziali in tale richiesta, negando l'autenticazione unica (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, l'endpoint restituisce un 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.
suggerimento di login opzionale Può essere usato per pre-compilare il campo nome utente/indirizzo di posta elettronica della pagina di accesso per l'utente, se si conosce il nome utente in anticipo. Spesso le app usano questo parametro durante la riautenticazione, avendo già estratto il nome utente da un accesso precedente usando l'attestazione preferred_username.

A questo punto viene chiesto all'utente di immettere le credenziali e completare l'autenticazione.

Risposta di esempio

Una risposta di esempio, inviata all'oggetto redirect_uri specificato nella richiesta di accesso dopo l'autenticazione dell'utente, potrebbe essere simile alla seguente:

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

id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNB...&state=12345
Parametro Descrizione
id_token (token di identificazione) Il id_token richiesto dall'app. È possibile usare il id_token per verificare l'identità dell'utente e iniziare una sessione con loro.
stato Valore incluso nella richiesta che viene restituito nella risposta del token. Per prevenire gli attacchi di Cross-Site Request Forgery (CSRF), viene generalmente utilizzato un valore univoco generato casualmente. Il parametro state viene anche utilizzato per codificare le informazioni sullo stato dell'utente nell'app prima che avvenisse la richiesta di autenticazione, come la pagina o la vista in cui si trovavano.

Risposta di errore

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

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

error=access_denied&error_description=the+user+canceled+the+authentication
Parametro Descrizione
Errore Stringa di codice di errore che può essere usata per classificare i tipi di errori che si verificano e può essere usata per reagire agli errori.
descrizione_errore Messaggio di errore specifico che consente a uno sviluppatore di identificare la causa principale di un errore di autenticazione.

Codici di errore per l'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 del cliente
richiesta non valida Errore del protocollo, ad esempio un parametro obbligatorio mancante. Correggere e inviare di nuovo la richiesta. Si tratta di un errore di sviluppo e viene in genere rilevato durante il test iniziale.
cliente non autorizzato L'applicazione client non è autorizzata a richiedere un codice di autorizzazione. Ciò si verifica in genere quando l'applicazione client non è registrata in Azure AD o non viene aggiunta al tenant di Azure AD dell'utente. L'applicazione può richiedere all'utente di installare l'applicazione e aggiungerla ad Azure AD.
accesso negato Consenso negato dal proprietario della risorsa L'applicazione client può notificare all'utente che non può continuare a meno che l'utente non acconsenta.
tipo_di_risposta_non_supportato Il server di autorizzazione non supporta il tipo di risposta nella richiesta. Correggere e inviare di nuovo la richiesta. Si tratta di un errore di sviluppo e viene in genere rilevato durante il test iniziale.
errore del server 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 è ritardata a causa di un errore temporaneo.
temporaneamente_non_disponibile Il server è temporaneamente troppo occupato per gestire la richiesta. Ripetere la richiesta. L'applicazione client potrebbe spiegare all'utente che la risposta è ritardata a causa di una condizione temporanea.
risorsa non valida La risorsa di destinazione non è valida perché non esiste, Azure AD non riesce a trovarlo o non è configurato correttamente. Indica che la risorsa, se esistente, non è stata configurata nel tenant. L'applicazione può richiedere all'utente di installare l'applicazione e aggiungerla ad Azure AD.

Convalidare il id_token

La semplice ricezione di un oggetto id_token non è sufficiente per autenticare l'utente. È necessario convalidare la firma e verificare le attestazioni come richiesto dall'app id_token. L'endpoint di Azure AD usa token JSON Web (JWT) e la crittografia a chiave pubblica per firmare i token e verificare che siano validi.

È possibile scegliere di convalidare il id_token nel codice client, ma una procedura comune consiste nell'inviare l'oggetto id_token a un server di backend e quindi eseguire la convalida lì.

È anche possibile convalidare attestazioni aggiuntive a seconda dello scenario. Alcune convalide comuni includono:

  • Garantire che l'utente o l'organizzazione dispongano dell'iscrizione all'app.
  • Assicurarsi che l'utente disponga di autorizzazioni/privilegi appropriati usando i claim wids o roles.
  • Verifica di un certo livello di autenticazione, ad esempio l'autenticazione a più fattori.

Dopo aver convalidato , id_tokenè possibile iniziare una sessione con l'utente e usare le attestazioni in id_token per ottenere informazioni sull'utente nell'app. Queste informazioni possono essere usate per la visualizzazione, i record, la personalizzazione e così via. Per altre informazioni su id_tokens e attestazioni, vedere id_tokens AAD.

Inviare una richiesta di disconnessione

Quando vuoi disconnettere l'utente dall'app, non è sufficiente cancellare i cookie dell'app o terminare la sessione con l'utente. È anche necessario reindirizzare l'utente alla end_session_endpoint pagina di disconnessione. In caso contrario, l'utente potrà autenticarsi nuovamente nell'app senza inserire nuovamente le credenziali, poiché disporrà di una sessione Single Sign-On valida con l'endpoint di Azure AD.

È sufficiente reindirizzare l'utente all'oggetto end_session_endpoint elencato nel documento dei metadati openID Connect:

GET https://login.microsoftonline.com/common/oauth2/logout?
post_logout_redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
Parametro TIPO Descrizione
post_logout_redirect_uri consigliato URL a cui l'utente deve essere reindirizzato dopo la disconnessione riuscita. Questo URL deve corrispondere a uno degli URI di reindirizzamento registrati per l'applicazione nel portale di registrazione dell'app. Se post_logout_redirect_uri non è incluso, viene visualizzato un messaggio generico.

Single Sign-Out

Quando si reindirizza l'utente a end_session_endpoint, Azure AD cancella la sessione dell'utente dal browser. Tuttavia, l'utente potrebbe comunque accedere ad altre applicazioni che usano Azure AD per l'autenticazione. Per consentire a tali applicazioni di disconnettere l'utente contemporaneamente, Azure AD invia una richiesta HTTP GET al componente registrato LogoutUrl di tutte le applicazioni a cui l'utente è attualmente connesso. Le applicazioni devono rispondere a questa richiesta cancellando qualsiasi sessione che identifica l'utente e restituendo una risposta 200. Se si desidera supportare una disconnessione singola nell'applicazione, è necessario implementare tale funzionalità nel codice dell'applicazione LogoutUrl. È possibile impostare il LogoutUrl dal portale di Azure.

  1. Accedere al portale di Azure.
  2. Scegliere Active Directory facendo clic sul proprio account nell'angolo superiore destro della pagina.
  3. Nel pannello di spostamento a sinistra scegliere Azure Active Directory, quindi scegliere Registrazioni app e selezionare l'applicazione.
  4. Fare clic su Impostazioni, quindi proprietà e trovare la casella di testo URL disconnessione .

Acquisizione di token

Molte applicazioni web devono non solo autenticare l'utente, ma anche accedere a un servizio web per conto dell'utente usando OAuth. Questo scenario combina OpenID Connect per l'autenticazione utente, acquisendo simultaneamente un authorization_code che può essere usato per ottenere access_tokens tramite il flusso del codice di autorizzazione OAuth.

Ottenere i token di accesso

Per acquisire i token di accesso, è necessario modificare la richiesta di accesso precedente:

// Line breaks for legibility only

GET https://login.microsoftonline.com/{tenant}/oauth2/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e        // Your registered Application ID
&response_type=id_token+code
&redirect_uri=http%3A%2F%2Flocalhost%3a12345          // Your registered Redirect Uri, url encoded
&response_mode=form_post                              // `form_post' or 'fragment'
&scope=openid
&resource=https%3A%2F%2Fservice.contoso.com%2F        // The identifier of the protected resource (web API) that your application needs access to
&state=12345                                          // Any value, provided by your app
&nonce=678910                                         // Any value, provided by your app

Includendo gli ambiti di autorizzazione nella richiesta e usando response_type=code+id_token, l'endpoint authorize garantisce che l'utente abbia acconsentito alle autorizzazioni indicate nel scope parametro di query e restituisca all'app un codice di autorizzazione per lo scambio di un token di accesso.

Risposta riuscita

Una risposta con esito positivo, inviata all'oggetto redirect_uri usando response_mode=form_post, ha un aspetto simile al seguente:

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

id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNB...&code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...&state=12345
Parametro Descrizione
id_token (token di identificazione) Il id_token richiesto dall'app. È possibile usare id_token per verificare l'identità dell'utente e iniziare una sessione con l'utente.
codice 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. Authorization_codes sono di breve durata e in genere scadono dopo circa 10 minuti.
stato 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 di errore

Le risposte di errore possono essere inviate anche a redirect_uri , 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
Parametro Descrizione
Errore Stringa di codice di errore che può essere usata per classificare i tipi di errori che si verificano e può essere usata per reagire agli errori.
descrizione_errore Messaggio di errore specifico che consente a uno sviluppatore di identificare la causa principale di un errore di autenticazione.

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

Dopo aver ottenuto un'autorizzazione code e un id_token, è possibile accedere all'utente e ottenere i token di accesso per loro conto. Per accedere all'utente, è necessario convalidare esattamente id_token come descritto in precedenza. Per ottenere i token di accesso, è possibile seguire i passaggi descritti nella sezione "Usare il codice di autorizzazione per richiedere un token di accesso" della documentazione del flusso di codice OAuth.

Passaggi successivi

  • Last updated on