Microsoft Identity Platform e il flusso di concessione dell'autorizzazione del dispositivo OAuth 2.0

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

Questo articolo descrive come programmare direttamente con il protocollo nella tua applicazione. Quando possibile, è consigliabile usare le librerie di autenticazione Microsoft supportate (MSAL) per acquisire i token e chiamare api Web protette. È possibile fare riferimento ad app di esempio che usano MSAL per esempi.

Diagramma del protocollo

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

Richiesta di autorizzazione del dispositivo

Il client deve prima verificare con il server di autenticazione un dispositivo e il codice utente usati per avviare l'autenticazione. Il client raccoglie questa richiesta dall'endpoint /devicecode . Nella richiesta, il client deve includere anche le autorizzazioni necessarie per l'acquisizione 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	Obbligatorio	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	Obbligatorio	L'ID applicazione (client) che la funzionalità Microsoft Entra admin center – Registrazioni app ha assegnato all'app.
scope	Obbligatorio	Elenco di ambiti separati da spazi a cui si desidera che l'utente dia il consenso.

Risposta all'autorizzazione del dispositivo

Una risposta con esito positivo è 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 il token di accesso dal server di autorizzazione.
user_code	Stringa	Stringa breve visualizzata all'utente usata per identificare la sessione in un dispositivo secondario.
verification_uri	URI (Identificatore Uniforme delle Risorse)	L'URI a user_code cui l'utente deve accedere.
expires_in	Int	Numero di secondi prima dell'oggetto device_code e user_code della scadenza.
interval	Int	Il numero di secondi in cui il client deve attendere tra le richieste di polling.
message	Stringa	Stringa leggibile con istruzioni per l'utente. Questa operazione può essere localizzata includendo un parametro di query nella richiesta del modulo ?mkt=xx-XX, compilando il codice delle impostazioni cultura del linguaggio appropriato.

Nota

Il verification_uri_complete campo della risposta non è incluso o supportato in questo momento. Questo viene menzionato perché se si legge lo standard visualizzato come verification_uri_complete 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 accedere di nuovo 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 in verification_uri, il client deve eseguire il polling dell'endpoint /token per il token richiesto usando .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	Obbligatorio	Descrizione
tenant	Obbligatorio	Lo stesso alias tenant o tenant usato nella richiesta iniziale.
grant_type	Obbligatorio	Deve essere urn:ietf:params:oauth:grant-type:device_code
client_id	Obbligatorio	Deve corrispondere all'oggetto client_id utilizzato nella richiesta iniziale.
device_code	Obbligatorio	Oggetto 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 del cliente
authorization_pending	L'utente non ha completato l'autenticazione, ma non ha annullato il flusso.	Ripetere la richiesta dopo almeno interval secondi.
authorization_declined	L'utente finale ha negato la richiesta di autorizzazione.	Arrestare il polling e ripristinare uno stato non autenticato.
bad_verification_code	L'oggetto device_code inviato all'endpoint /token non è stato riconosciuto.	Verificare che il client invii la risposta corretta device_code 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 riuscita

Una risposta di token con esito positivo è simile alla 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 spazi	Se è stato restituito un token di accesso, vengono elencati gli ambiti in cui il token di accesso è valido.
expires_in	Int	Numero di secondi per cui il token di accesso incluso è valido.
access_token	Stringa opaca	Rilasciato per gli ambiti e richiesti.
id_token	JWT	Emesso se il parametro scope originale includeva l'ambito openid.
refresh_token	Stringa opaca	Generato se il parametro scope originale includeva 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.

Avvertimento

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 consumer (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.