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 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. È 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 per il 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 la 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	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	ID applicazione (client) assegnato all'app dall'interfaccia di amministrazione Registrazioni app di Microsoft Entra.
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	Stringa breve visualizzata all'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 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 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=535fb089-9ff3-47b6-9bfb-4f1264799865&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 completato 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	L'oggetto 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, 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	Emessa per gli ambiti che sono stati richiesti.
id_token	Token JSON Web	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 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). Durante la lettura dei token è uno strumento utile per il debug e l'apprendimento, non assumere dipendenze da questo nel codice o presupporre specifiche sui token che non sono per un'API che si controlla.