Autorizzare l'accesso ad applicazioni Web con OpenID Connect e Azure Active Directory

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

È consigliabile usare OpenID Connect se si compila un'applicazione Web ospitata su un server e accessibile da browser.

Registrare l'applicazione nel tenant di Active Directory

Registrare prima di tutto l'applicazione con il tenant di Azure Active Directory (Azure AD). Verrà fornito un ID per l'applicazione, abilitandola per ricevere token.

1. Accedere al portale di Azure.

2. Scegliere il tenant di Azure AD selezionando l'account nell'angolo superiore destro della pagina, quindi selezionando lo spostamento Switch Directory e quindi selezionando il tenant appropriato.

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

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

4. Nel menu a sinistra di Azure Active Directory selezionare Registrazioni app e quindi 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 questa esercitazione, ma se si desidera esempi specifici per applicazioni Web o applicazioni client pubbliche, vedere le guide introduttive.

   • Nome è il nome dell'applicazione e descrive l'applicazione agli utenti finali.
   • In Tipi di account supportati selezionare Account in qualsiasi directory organizzativa e account Microsoft personali.
   • Specificare l'URI di reindirizzamento. Per le applicazioni Web, questo è l'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 usa 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 assegna all'applicazione un identificatore client univoco ( ID applicazione). Poiché questo valore sarà necessario nelle sezioni successive, copiarlo dalla pagina dell'applicazione.

7. Per trovare l'applicazione nella portale di Azure, selezionare Registrazioni app e quindi selezionare Visualizza tutte le applicazioni.

Flusso di autenticazione con OpenID Connect

Il flusso di accesso di base include i passaggi seguenti: ognuno di essi è descritto in dettaglio di seguito.

Documento di metadati OpenID Connect

OpenID Connect descrive un documento di metadati che contiene la maggior parte delle informazioni necessarie perché un'applicazione esegua l'accesso. Il documento include informazioni come gli URL da usare e il percorso delle chiavi di firma pubbliche del servizio. Il documento di metadati OpenID Connect è reperibile all'indirizzo:

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

I metadati sono un semplice documento JavaScript Object Notation (JSON). Per un esempio, vedere il frammento di codice seguente. Il contenuto del frammento di codice è descritto dettagliatamente nelle specifiche di OpenID Connect. Si noti che l'inserimento di un ID tenant anziché common al posto di {tenant} precedente comporterà URI specifici del tenant nell'oggetto JSON restituito.

{
    "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 include chiavi di firma personalizzate perché è stata usata la funzionalità di mapping delle attestazioni, è necessario accodare un parametro di query appid contenente l'ID app per ottenere un indirizzo jwks_uri che punta alle informazioni della chiave di firma dell'app. Ad esempio, https://login.microsoftonline.com/{tenant}/.well-known/openid-configuration?appid=6731de76-14a6-49ae-97bc-6eba6914391e contiene una l'indirizzo jwks_urihttps://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 indirizzarlo all'endpoint /authorize . Questa richiesta è simile a quella della prima parte di Flusso del codice di autorizzazione di OAuth 2.0, con alcune importanti differenze:

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

Una richiesta di esempio si presenta quindi come segue:

// 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

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

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

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.

Convalidare il token ID

La semplice ricezione di un id_token non è sufficiente per autenticare l'utente. È necessario convalidare la firma e verificare le attestazioni in id_token in base ai requisiti dell'app. L'endpoint di Azure AD usa i token Web JSON (JWT) e la crittografia a chiave pubblica per firmare i token e verificarne la validità.

È possibile scegliere di convalidare id_token nel codice client, ma una procedura comune consiste nell'inviare id_token a un server back-end dove verrà eseguita la convalida.

È inoltre consigliabile convalidare attestazioni aggiuntive in base allo scenario. Alcune convalide comuni includono:

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

Dopo aver completato la convalida di id_token, è possibile avviare 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 AAD id_tokens.

Inviare una richiesta di disconnessione

Durante la disconnessione di un utente dall’applicazione, non basta cancellare i cookie dell’applicazione o terminare la sessione con l’utente. È anche necessario reindirizzare l'utente a per la end_session_endpoint disconnessione. In caso contrario, l'utente potrà ripetere l'autenticazione all'app senza immettere nuovamente le credenziali, perché avrà una sessione di Single Sign-On valida con l'endpoint di Azure AD.

È sufficiente reindirizzare l'utente all' end_session_endpoint riportato nel documento dei metadati di OpenID:

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

Single Sign-Out

Quando si reindirizza l'utente all'end_session_endpoint, Azure AD cancella la sessione dell'utente dal browser. L'utente può tuttavia essere ancora connesso ad altre applicazioni che usano Azure AD per l'autenticazione. Per consentire che tutte le applicazioni eseguano la disconnessione dell'utente simultaneamente, Azure AD invia una richiesta HTTP GET all'oggetto LogoutUrl registrato 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 vuole supportare l'accesso Single Sign-Out nell'applicazione, è necessario implementare questo tipo di oggetto LogoutUrl nel codice dell'applicazione. È possibile impostare LogoutUrl nel portale di Azure:

1. Accedere al portale di Azure.
2. Fare clic sull'account nell'angolo superiore destro della pagina per scegliere l'istanza di Active Directory.
3. Nel pannello di navigazione a sinistra scegliere Azure Active Directory, quindi scegliere Registrazioni per l'app e selezionare l'applicazione desiderata.
4. Fare clic su Impostazioni e Proprietà e individuare la casella di testo URL disconnessione.

Acquisizione dei token

Molte app Web non solo eseguono l'accesso dell'utente, ma accedono anche a un servizio Web per conto dell'utente tramite OAuth. Questo scenario combina OpenID Connect per l'autenticazione utente durante l'acquisizione simultanea di un authorization_code oggetto che può essere usato per usare access_tokens 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 verificherà che l'utente abbia dato il consenso per le autorizzazioni indicate nel parametro di query scope e restituirà all'app un codice di autorizzazione da scambiare con un token di accesso.

Risposta di esito positivo

Una risposta con esito positivo, inviata all'oggetto redirect_uri using 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

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

Per una descrizione dei possibili codici di errore e l'azione consigliata per il client, vedere Codici 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 far accedere l'utente è necessario convalidare l' id_token esattamente come descritto sopra. Per ottenere i token di accesso, è possibile seguire la procedura descritta nella sezione "Usare un codice di autorizzazione per richiedere un token di accesso" della documentazione del flusso del codice OAuth.

Passaggi successivi

• Altre informazioni sui token di accesso.
• Altre informazioni sulle id_token attestazioni e .