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

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.

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.