Flusso del codice di autorizzazione di OAuth 2.0 in Azure Active Directory B2C

Articolo
11/06/2023

È possibile usare la concessione del codice di autorizzazione OAuth 2.0 nelle app che vengono installate su un dispositivo per ottenere l'accesso a risorse protette, ad esempio le API Web. Usando l'implementazione di Azure Active Directory B2C (Azure AD B2C) di OAuth 2.0, è possibile aggiungere attività di iscrizione, accesso e altre attività di gestione delle identità alle app desktop, per dispositivi mobili e a pagina singola. Questo articolo è indipendente dal linguaggio. Descrive come inviare e ricevere messaggi HTTP senza usare alcuna libreria open source. Quando possibile, è consigliabile usare le librerie di autenticazione Microsoft supportate (MSAL). Esaminare le app di esempio che usano MSAL.

Il flusso del codice di autorizzazione di OAuth 2.0 è descritto nella sezione 4.1 della specifica di OAuth 2.0. È possibile usarlo per l'autenticazione e l'autorizzazione nella maggior parte dei tipi di applicazione, tra cui applicazioni Web, applicazioni a pagina singola e applicazioni installate in modo nativo. È possibile usare il flusso del codice di autorizzazione di OAuth 2.0 per acquisire in modo sicuro token di accesso e di aggiornamento per le applicazioni, i quali possono essere usati per accedere a risorse protette da un server di autorizzazione. Il token di aggiornamento consente al client di acquisire nuovi token di accesso (e aggiornamento) quando scade il token di accesso, in genere dopo un'ora.

Questo articolo illustra il flusso del codice di autorizzazione di OAuth 2.0 dei client pubblici. Un client pubblico è qualsiasi applicazione client che non può essere considerata attendibile in modo sicuro per mantenere l'integrità di una password segreta. Sono incluse applicazioni a pagina singola, app per dispositivi mobili, applicazioni desktop e essenzialmente qualsiasi applicazione che non viene eseguita in un server.

Nota

Per aggiungere la gestione delle identità a un'App Web usando Azure AD B2C, usare OpenID Connect al posto di OAuth 2.0.

Azure AD B2C estende i flussi standard OAuth 2.0 per non limitarsi esclusivamente a semplici operazioni di autorizzazione e autenticazione. Introduce il flusso utente. Con i flussi utente è possibile usare OAuth 2.0 per aggiungere esperienze utente all'applicazione, ad esempio la gestione dell'iscrizione, dell'accesso e del profilo. I provider di identità che usano il protocollo OAuth 2.0 includono Amazon, Microsoft Entra ID, Facebook, GitHub, Google e LinkedIn.

Per provare le richieste HTTP in questo articolo:

Sostituire {tenant} con il nome del tenant di Azure AD B2C.
Sostituire 90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6 con l'ID app di un'applicazione registrata in precedenza nel tenant di Azure AD B2C.
Sostituire {policy} con il nome di un criterio creato nel tenant, ad esempio b2c_1_sign_in.

Configurazione dell'URI di reindirizzamento necessaria per le app a pagina singola

Il flusso del codice di autorizzazione per le applicazioni a pagina singola richiede una configurazione aggiuntiva. Seguire le istruzioni per creare l'applicazione a pagina singola per contrassegnare correttamente l'URI di reindirizzamento come abilitato per CORS. Per aggiornare un URI di reindirizzamento esistente per abilitare CORS, è possibile fare clic sulla richiesta di migrazione nella sezione "Web" della scheda Autenticazione della registrazione dell'app. In alternativa, è possibile aprire l'editor del manifesto Registrazioni app e impostare il campo per l'URI type di reindirizzamento su spa nella replyUrlsWithType sezione .

Il spa tipo di reindirizzamento è compatibile con le versioni precedenti con il flusso implicito. Le app che attualmente usano 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.

1. Ottenere un codice di autorizzazione

Il flusso del codice di autorizzazione ha inizio con il client che indirizza l'utente all'endpoint /authorize . Questa è la parte interattiva del flusso, dove l'utente esegue operazioni. In questa richiesta il client indica nel parametro scope le autorizzazioni che deve acquisire dall'utente. Gli esempi seguenti (con interruzioni di riga per la leggibilità) illustrano come acquisire un codice di autorizzazione. Se si sta testando questa richiesta HTTP GET, usare il browser.

GET https://{tenant}.b2clogin.com/{tenant}.onmicrosoft.com/{policy}/oauth2/v2.0/authorize?
client_id=90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6
&response_type=code
&redirect_uri=urn%3Aietf%3Awg%3Aoauth%3A2.0%3Aoob
&response_mode=query
&scope=90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6%20offline_access%20https://{tenant-name}/{app-id-uri}/{scope}
&state=arbitrary_data_you_can_receive_in_the_response
&code_challenge=YTFjNjI1OWYzMzA3MTI4ZDY2Njg5M2RkNmVjNDE5YmEyZGRhOGYyM2IzNjdmZWFhMTQ1ODg3NDcxY2Nl
&code_challenge_method=S256

Parametro	Necessaria?	Descrizione
{tenant}	Necessario	Nome del tenant di Azure AD B2C
{policy}	Necessario	Flusso utente da eseguire. Specificare il nome di un flusso utente creato nel tenant di Azure AD B2C. Ad esempio: `b2c_1_sign_in`, `b2c_1_sign_up` o `b2c_1_edit_profile`.
client_id	Necessario	ID applicazione assegnato all'app nel portale di Azure.
response_type	Necessario	Tipo di risposta, che deve includere `code` per il flusso del codice di autorizzazione. È possibile ricevere un token ID se lo si include nel tipo di risposta, ad esempio `code+id_token`, e in questo caso, l'ambito deve includere `openid`.
redirect_uri	Necessario	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 come URL.
ambito	Necessario	Elenco di ambiti separati da spazi. L'ambito `openid` indica un'autorizzazione per l'accesso dell'utente e per ottenere i dati relativi all'utente sotto forma di token ID. L'ambito `offline_access` è facoltativo per le applicazioni Web. Indica che l'applicazione richiederà un token di aggiornamento per l'accesso esteso alle risorse. L'ID client indica che il token emesso è destinato all'uso da parte del client registrato di Azure AD B2C. Indica `https://{tenant-name}/{app-id-uri}/{scope}` un'autorizzazione per le risorse protette, ad esempio un'API Web. Per altre informazioni, vedere Richiedere un token di accesso.
response_mode	Consigliato	Metodo da usare per inviare all'app il codice di autorizzazione risultante. Può essere `query`, `form_post` o `fragment`.
state	Consigliato	Valore incluso nella richiesta che può essere una stringa di qualsiasi contenuto che si intende usare. Per evitare attacchi di richiesta intersito falsa, in genere viene usato un valore univoco generato casualmente. Anche lo stato viene usato per codificare le informazioni sullo stato dell'utente nell'app prima del verificarsi della richiesta di autenticazione, ad esempio la pagina in cui si trova l'utente o il flusso utente che era in esecuzione.
prompt	Facoltativo	Tipo di interazione utente obbligatoria. L'unico valore valido in questa fase è `login`, che impone all'utente di immettere le credenziali per la richiesta. L'accesso Single Sign-On non avrà effetto.
code_challenge	consigliato / obbligatorio	Usato per proteggere i privilegi concessi sui codici di autorizzazione tramite la chiave di prova per Code Exchange (PKCE). Obbligatorio con `code_challenge_method` incluso. È necessario aggiungere la logica nell'applicazione per generare e `code_verifiercode_challenge`. `code_challenge` è un hash SHA256 con codifica URL Base64 dell'oggetto `code_verifier`. L'oggetto viene archiviato `code_verifier` nell'applicazione per un uso successivo e viene inviato `code_challenge` insieme alla richiesta di autorizzazione. Per altre informazioni, vedere il PKCE RFC. Questa operazione è ora consigliata per tutti i tipi di applicazioni: app native, applicazione a pagina singola e client riservati come le app Web.
`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 per qualche motivo il client non può supportare SHA256. Se si esclude `code_challenge_method`, ma si include `code_challenge`ancora , si presuppone che sia `code_challenge` testo non crittografato. Microsoft Identity Platform supporta `plain` e `S256`. Per altre informazioni, vedere il PKCE RFC. Questa operazione è obbligatoria per app a pagina singola che usano il flusso del codice di autorizzazione.
login_hint	No	Può essere usato per pre-compilare il campo nome di accesso della pagina di accesso. Per altre informazioni, vedere Prepopolato il nome di accesso.
domain_hint	No	Fornisce un suggerimento ad Azure AD B2C sul provider di identità social che deve essere usato per l'accesso. Se viene incluso un valore valido, l'utente passa direttamente alla pagina di accesso al provider di identità. Per altre informazioni, vedere Reindirizzare l'accesso a un provider di social network.
Parametri personalizzati	No	Parametri personalizzati che possono essere usati con criteri personalizzati. Ad esempio, l'URI del contenuto della pagina personalizzata dinamica o i resolver attestazioni chiave-valore.

Viene a questo punto richiesto all'utente di completare il flusso di lavoro del flusso utente. È possibile che venga richiesto all'utente di immettere nome utente e password, di accedere con un'identità di social networking, di iscriversi alla directory o di effettuare qualsiasi altro passaggio. Le azioni dell'utente dipendono dal modo in cui è definito il flusso utente.

Dopo aver completato il flusso utente, Microsoft Entra ID restituisce una risposta all'app al valore usato per redirect_uri. Viene usato il metodo specificato nel parametro response_mode. La risposta è esattamente la stessa per ogni scenario di azione dell'utente, indipendentemente dal flusso utente eseguito.

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

GET urn:ietf:wg:oauth:2.0:oob?
code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...        // the authorization_code, truncated
&state=arbitrary_data_you_can_receive_in_the_response                // the value provided in the request

Parametro	Descrizione
codice	Codice di autorizzazione richiesto dall'app. L'app può usare il codice di autorizzazione per richiedere un token di accesso per una risorsa di destinazione. I codici di autorizzazione hanno una durata molto breve. In genere scadono dopo circa 10 minuti.
state	Vedere la descrizione completa nella tabella della sezione precedente. 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 le risposte di errore possono essere inviate all'URI di reindirizzamento in modo che l'app possa gestirle adeguatamente:

GET urn:ietf:wg:oauth:2.0:oob?
error=access_denied
&error_description=The+user+has+cancelled+entering+self-asserted+information
&state=arbitrary_data_you_can_receive_in_the_response

Parametro	Descrizione
error	Stringa di codice di errore che è possibile usare per classificare i tipi di errori che si verificano. È possibile usare la stringa anche per rispondere agli errori.
error_description	Messaggio di errore specifico che consente di identificare la causa principale di un errore di autenticazione.
state	Vedere la descrizione completa nella tabella precedente. 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.

2. Ottenere un token di accesso

Ora che è stato acquisito il codice di autorizzazione, è possibile riscattare code per un token per la risorsa desiderata inviando una richiesta POST all'endpoint /token. In Azure AD B2C è possibile richiedere token di accesso per altre API come di consueto specificando gli ambiti nella richiesta.

È anche possibile richiedere un token di accesso per l'API Web back-end dell'app per convenzione usando l'ID client dell'app come ambito richiesto (che comporterà un token di accesso con tale ID client come "destinatari"):

POST https://{tenant}.b2clogin.com/{tenant}.onmicrosoft.com/{policy}/oauth2/v2.0/token HTTP/1.1

Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&client_id=90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6
&scope=90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6 offline_access
&code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&redirect_uri=urn:ietf:wg:oauth:2.0:oob
&code_verifier=ThisIsntRandomButItNeedsToBe43CharactersLong

Parametro	Necessaria?	Descrizione
{tenant}	Necessario	Nome del tenant di Azure AD B2C
{policy}	Necessario	Flusso utente usato per acquisire il codice di autorizzazione. Non è possibile usare un flusso utente diverso in questa richiesta.
client_id	Necessario	ID applicazione assegnato all'app nel portale di Azure.
client_secret	Sì, in App Web	Segreto dell'applicazione generato nella portale di Azure. I segreti client vengono usati in questo flusso per scenari di app Web, in cui il client può archiviare in modo sicuro un segreto client. Per scenari client nativi (client pubblici), i segreti client non possono essere archiviati in modo sicuro e pertanto non vengono usati in questa chiamata. Se si usa un segreto client, modificarlo su base periodica.
grant_type	Necessario	Tipo di concessione. Per il flusso del codice di autorizzazione il tipo di concessione deve essere `authorization_code`.
ambito	Consigliato	Elenco di ambiti separato da spazi. Un singolo valore di ambito indica Microsoft Entra ID entrambe le autorizzazioni richieste. L'uso dell'ID client come ambito indica che l'app necessita di un token di accesso, che può essere usato per il servizio o l'API Web, rappresentato dallo stesso ID client. L'ambito `offline_access` indica che l'app necessita di un token di aggiornamento per avere un accesso di lunga durata alle risorse. È anche possibile usare l'ambito `openid` per richiedere un token ID ad Azure Active Directory B2C.
codice	Necessario	Codice di autorizzazione acquisito dall'endpoint `/authorize` .
redirect_uri	Necessario	L'URI di reindirizzamento dell'applicazione dove è stato ricevuto il codice di autorizzazione.
code_verifier	Consigliato	Lo stesso `code_verifier` usato per ottenere il codice di autorizzazione. Obbligatorio se nella richiesta di concessione del codice di autorizzazione è stato usato PKCE. Per altre informazioni, vedere il PKCE RFC.

Se si esegue il test di questa richiesta HTTP POST, è possibile usare qualsiasi client HTTP, ad esempio Microsoft PowerShell o Postman.

Una risposta di token con esito positivo ha un aspetto simile al seguente:

{
    "not_before": "1442340812",
    "token_type": "Bearer",
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
    "scope": "90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6 offline_access",
    "expires_in": "3600",
    "refresh_token": "AAQfQmvuDy8WtUv-sd0TBwWVQs1rC-Lfxa_NDkLqpg50Cxp5Dxj0VPF1mx2Z...",
}

Parametro	Descrizione
not_before	Il momento in cui il token viene considerato valido, nel periodo.
token_type	Valore del tipo di token. L'unico tipo supportato Microsoft Entra ID è Bearer.
access_token	Token JSON Web (JWT) firmato richiesto.
ambito	Ambiti per i quali il token è valido. È possibile usare gli ambiti anche per memorizzare i token nella cache per un uso successivo.
expires_in	Periodo di validità del token (in secondi).
token di aggiornamento	Token di aggiornamento di OAuth 2.0. L'app può usare questo token per acquisire token aggiuntivi dopo la scadenza del token corrente. I token di aggiornamento sono di lunga durata. È possibile usarli per mantenere l'accesso alle risorse per periodi prolungati di tempo. Per altre informazioni, vedere le informazioni di riferimento sul token di Azure AD B2C.

Le risposte di errore si presentano nel modo seguente:

{
    "error": "access_denied",
    "error_description": "The user revoked access to the app.",
}

Parametro	Descrizione
error	Stringa di codice di errore che è possibile usare per classificare i tipi di errori che si verificano. È possibile usare la stringa anche per rispondere agli errori.
error_description	Messaggio di errore specifico che consente di identificare la causa principale di un errore di autenticazione.

3. Usare il token

Dopo avere acquisito un token di accesso, è possibile usarlo nelle richieste alle API Web back-end includendolo nell'intestazione Authorization:

GET /tasks
Host: mytaskwebapi.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...

4. Aggiornare il token

I token di accesso e i token ID hanno breve durata. È necessario aggiornarli dopo la scadenza per continuare ad accedere alle risorse. Quando si aggiorna il token di accesso, Azure AD B2C restituisce un nuovo token. Il token di accesso aggiornato avrà aggiornato nbf (non prima), iat (rilasciato all'indirizzo) e exp (scadenza) i valori dell'attestazione. Tutti gli altri valori di attestazione saranno gli stessi del token di accesso originariamente rilasciato.

Per aggiornare il token, inviare un'altra richiesta POST all'endpoint /token . questa volta specificando refresh_token invece di code:

POST https://{tenant}.b2clogin.com/{tenant}.onmicrosoft.com/{policy}/oauth2/v2.0/token HTTP/1.1

Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&client_id=90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6
&scope=90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6 offline_access
&refresh_token=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&redirect_uri=urn:ietf:wg:oauth:2.0:oob

Parametro	Necessaria?	Descrizione
{tenant}	Necessario	Nome del tenant di Azure AD B2C
{policy}	Necessario	Flusso utente usato per acquisire il token di aggiornamento originale. Non è possibile usare un flusso utente diverso in questa richiesta.
client_id	Necessario	ID applicazione assegnato all'app nel portale di Azure.
client_secret	Sì, in App Web	Segreto dell'applicazione generato nel portale di Azure. I segreti client vengono usati in questo flusso per gli scenari di app Web, in cui il client può archiviare in modo sicuro un segreto client. Per gli scenari di app nativa (client pubblico), i segreti client non possono essere archiviati in modo sicuro e pertanto non vengono usati in questa chiamata. Se si usa un segreto client, modificarlo periodicamente.
grant_type	Necessario	Tipo di concessione. Per questa parte del flusso del codice di autorizzazione il tipo di concessione deve essere `refresh_token`.
ambito	Consigliato	Elenco di ambiti separato da spazi. Un singolo valore di ambito indica di Microsoft Entra ID entrambe le autorizzazioni richieste. L'uso dell'ID client come ambito indica che l'app necessita di un token di accesso, che può essere usato per il servizio o l'API Web, rappresentato dallo stesso ID client. L'ambito `offline_access` indica che l'app necessita di un token di aggiornamento per un accesso di lunga durata alle risorse. È anche possibile usare l'ambito `openid` per richiedere un token ID ad Azure Active Directory B2C.
redirect_uri	Facoltativo	L'URI di reindirizzamento dell'applicazione dove è stato ricevuto il codice di autorizzazione.
token di aggiornamento	Necessario	Token di aggiornamento originale acquisito nella seconda sezione del flusso.

Una risposta di token con esito positivo ha un aspetto simile al seguente:

{
    "not_before": "1442340812",
    "token_type": "Bearer",
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
    "scope": "90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6 offline_access",
    "expires_in": "3600",
    "refresh_token": "AAQfQmvuDy8WtUv-sd0TBwWVQs1rC-Lfxa_NDkLqpg50Cxp5Dxj0VPF1mx2Z...",
}

Parametro	Descrizione
not_before	Il momento in cui il token viene considerato valido, nel periodo.
token_type	Valore del tipo di token. L'unico tipo supportato da Microsoft Entra ID è Bearer.
access_token	Token JWT firmato richiesto.
ambito	Ambiti per i quali il token è valido. È possibile usare gli ambiti anche per memorizzare i token nella cache per un uso successivo.
expires_in	Periodo di validità del token (in secondi).
token di aggiornamento	Token di aggiornamento di OAuth 2.0. L'app può usare questo token per acquisire token aggiuntivi dopo la scadenza del token corrente. I token di aggiornamento hanno durata elevata e possono essere usati per mantenere l'accesso alle risorse per lunghi periodi di tempo. Per altre informazioni, vedere le informazioni di riferimento sul token di Azure AD B2C.

Le risposte di errore si presentano nel modo seguente:

{
    "error": "access_denied",
    "error_description": "The user revoked access to the app.",
}

Parametro	Descrizione
error	Stringa di codice di errore che è possibile usare per classificare i tipi di errori che si verificano. È possibile usare la stringa anche per rispondere agli errori.
error_description	Messaggio di errore specifico che consente di identificare la causa principale di un errore di autenticazione.

Usare la directory di Azure AD B2C

Per provare queste richieste, completare i passaggi seguenti. Sostituire i valori dell'esempio usato in questo articolo con valori personalizzati.

Creare una directory Azure AD B2C. Usare il nome della directory nelle richieste.
Creare un'applicazione per ottenere un ID applicazione e un URI di reindirizzamento. Includere un client nativo nell'app.
Creare i flussi utente per ottenere i propri nomi di flusso utente.

Condividi tramite