Microsoft Identity Platform e il flusso di concessione delle autorizzazioni per dispositivi OAuth 2.0

Articolo
07/12/2024

Microsoft Identity Platform supporta la concessione dell'autorizzazione del dispositivo, che consente agli utenti di accedere a dispositivi con vincoli di input, ad esempio una smart TV, un dispositivo IoT o una stampante. Per abilitare questo flusso, il dispositivo richiede all'utente di visitare una pagina Web nel browser in un altro dispositivo per l'accesso. Dopo che l'utente ha eseguito l'accesso, il dispositivo è in grado di ottenere i token di accesso e i token di aggiornamento in base alle esigenze.

Questo articolo descrive come programmare direttamente in base al protocollo nell'applicazione. Quando possibile, è consigliabile usare le librerie di autenticazione Microsoft (MSAL) supportate anziché acquisire i token e chiamare le API Web protette. Per esempi, vedere le app di esempio che usano MSAL.

Diagramma del protocollo

L'intero flusso di codice del dispositivo è illustrato nel diagramma seguente. In questo articolo viene illustrato ogni passaggio.

Flusso del codice del dispositivo

Richiesta di autorizzazione per il dispositivo

Il client deve prima di tutto verificare sul server di autenticazione un codice dispositivo e utente, usati per avviare l'autenticazione. Il client raccoglie la richiesta dall'endpoint /devicecode. Nella richiesta, il client deve includere anche le autorizzazioni che deve acquisire dall'utente.

Dal momento in cui viene inviata la richiesta, l'utente ha 15 minuti per accedere. Questo è il valore predefinito per expires_in. La richiesta deve essere effettuata solo quando l'utente indica che è pronto per l'accesso.

// Line breaks are for legibility only.

POST https://login.microsoftonline.com/{tenant}/oauth2/v2.0/devicecode
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&scope=user.read%20openid%20profile

Parametro	Condizione	Descrizione
`tenant`	Richiesto	Può essere `/common`, `/consumers` o `/organizations`. Può anche essere il tenant della directory da cui si vuole richiedere l'autorizzazione in formato GUID o nome descrittivo.
`client_id`	Richiesto	L'ID applicazione (client) che l'esperienza Interfaccia di amministrazione di Microsoft Entra: Registrazioni app ha assegnato all'app.
`scope`	Richiesto	Elenco separato da spazi di ambiti a cui si vuole che l'utente dia il consenso.

Risposta di autorizzazione per il dispositivo

Una risposta di esito positivo sarà un oggetto JSON contenente le informazioni necessarie per consentire all'utente di eseguire l'accesso.

Parametro	Formato	Descrizione
`device_code`	Stringa	Stringa lunga usata per verificare la sessione tra il client e il server di autorizzazione. Il client usa questo parametro per richiedere al server di autorizzazione il token di accesso.
`user_code`	String	Una stringa breve visualizzata dall'utente, usata per identificare la sessione in un dispositivo secondario.
`verification_uri`	URI	L'URI a cui l'utente deve passare con il `user_code` per eseguire l'accesso.
`expires_in`	int	Il numero di secondi prima della scadenza del `device_code` e del `user_code`.
`interval`	int	Numero di secondi di attesa del client tra le richieste di polling.
`message`	String	Stringa leggibile con le istruzioni per l'utente. Può essere localizzata includendo un parametro di query nella richiesta del form `?mkt=xx-XX`, compilando l'apposito codice della lingua di destinazione.

Nota

Il campo di risposta verification_uri_complete non è incluso o supportato in questo momento. Questo viene menzionato perché se si legge lo standard si noterà che verification_uri_complete è elencato come parte facoltativa dello standard del flusso di codice del dispositivo.

Autenticazione dell'utente

Dopo che il client riceve user_code e verification_uri, i valori vengono visualizzati e l'utente viene indirizzato all'accesso tramite il browser per dispositivi mobili o PC.

Se l'utente esegue l'autenticazione con un account personale, usando /common o /consumers, viene chiesto di eseguire di nuovo l'accesso per trasferire lo stato di autenticazione al dispositivo. Ciò è dovuto al fatto che il dispositivo non è in grado di accedere ai cookie dell'utente. Viene chiesto di fornire il consenso alle autorizzazioni richieste dal client. Tuttavia, questo non si applica agli account aziendali o dell'istituto di istruzione usati per l'autenticazione.

Mentre l'utente esegue l'autenticazione all'verification_uri, il client deve eseguire il polling dell'endpoint /tokenper il token richiesto usando il device_code.

POST https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:device_code&client_id=00001111-aaaa-2222-bbbb-3333cccc4444&device_code=GMMhmHCXhWEzkobqIHGG_EnNYYsAkukHspeYUk9E8...

Parametro	Richiesto	Descrizione
`tenant`	Richiesto	Lo stesso alias tenant o tenant usato nella richiesta iniziale.
`grant_type`	Richiesto	Deve essere `urn:ietf:params:oauth:grant-type:device_code`
`client_id`	Richiesto	Deve corrispondere al `client_id` usato nella richiesta iniziale.
`device_code`	Richiesto	Il `device_code` restituito nella richiesta di autorizzazione del dispositivo.

Errori previsti

Il flusso del codice del dispositivo è un protocollo di polling in modo che gli errori serviti al client devono essere previsti prima del completamento dell'autenticazione utente.

Errore	Descrizione	Azione client
`authorization_pending`	L'utente non ha ancora terminato l'autenticazione, ma non ha annullato il flusso.	Ripetere la richiesta dopo almeno `interval` secondi.
`authorization_declined`	L'utente finale ha rifiutato la richiesta di autorizzazione.	Arrestare il polling e ripristinare uno stato non autenticato.
`bad_verification_code`	Il `device_code` inviato all'endpoint `/token` non è stato riconosciuto.	Verificare che il client stia inviando il `device_code` corretto nella richiesta.
`expired_token`	Il valore di `expires_in` è stato superato e l'autenticazione non è più possibile con `device_code`.	Arrestare il polling e ripristinare uno stato non autenticato.

Risposta di autenticazione di esito positivo

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

{
    "token_type": "Bearer",
    "scope": "User.Read profile openid email",
    "expires_in": 3599,
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
    "refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
    "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctOD..."
}

Parametro	Formato	Descrizione
`token_type`	Stringa	Sempre `Bearer`.
`scope`	Stringhe separate da uno spazio	Se è stato restituito un token di accesso, verranno elencati gli ambiti per cui è valido.
`expires_in`	int	Numero di secondi per cui il token di accesso incluso verrà considerato valido.
`access_token`	Stringa opaca	Emessa per gli ambiti che sono stati richiesti.
`id_token`	JWT	Emessa nel parametro `scope` originale incluso nell'ambito `openid`.
`refresh_token`	Stringa opaca	Emessa nel parametro `scope` originale incluso `offline_access`.

È possibile usare il token di aggiornamento per acquisire nuovi token di accesso e token di aggiornamento usando lo stesso flusso documentato nella documentazione del flusso del codice OAuth.

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 i servizi Microsoft possono usare un formato speciale che non verrà convalidato come token JWT e potrebbe anche essere crittografato per gli utenti (account Microsoft). Sebbene la lettura dei token sia uno strumento utile per il debug e l'apprendimento, è consigliabile non dipendere da questo per il codice o presupporre specifiche sui token che non sono per un'API che si controlla.

Condividi tramite