Microsofts identitetsplattform och OAuth 2.0-enhetsauktoriseringsflödet

Artikel
04/08/2024

Microsofts identitetsplattform stöder beviljandet av enhetsauktorisering, vilket gör det möjligt för användare att logga in på indatabegränsade enheter, till exempel en smart-TV, IoT-enhet eller en skrivare. För att aktivera det här flödet har enheten användaren besöker en webbsida i en webbläsare på en annan enhet för att logga in. När användaren har loggat in kan enheten hämta åtkomsttoken och uppdateringstoken efter behov.

I den här artikeln beskrivs hur du kan programmera direkt mot protokollet i ditt program. När det är möjligt rekommenderar vi att du använder de Microsoft Authentication Libraries (MSAL) som stöds i stället för att hämta token och anropa skyddade webb-API:er. Du kan se exempelappar som använder MSAL som exempel.

Protokolldiagram

Hela enhetskodflödet visas i följande diagram. Varje steg förklaras i den här artikeln.

Device code flow

Begäran om enhetsauktorisering

Klienten måste först kontrollera med autentiseringsservern om en enhet och användarkod som används för att initiera autentisering. Klienten samlar in den här begäran från /devicecode slutpunkten. I begäran ska klienten även innehålla de behörigheter som krävs för att hämta från användaren.

Från det att begäran skickas har användaren 15 minuter på sig att logga in. Det här är standardvärdet för expires_in. Begäran bör endast göras när användaren anger att de är redo att logga in.

// 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

Parameter	Villkor	beskrivning
`tenant`	Obligatoriskt	Kan vara `/common`, `/consumers`eller `/organizations`. Det kan också vara den katalogklient som du vill begära behörighet från i GUID- eller eget namnformat.
`client_id`	Obligatoriskt	Det program-ID (klient)-ID som administrationscentret för Microsoft Entra – Appregistreringar upplevelse som tilldelats din app.
`scope`	Obligatoriskt	En utrymmesavgränsad lista över omfång som du vill att användaren ska samtycka till.

Enhetsauktoriseringssvar

Ett lyckat svar är ett JSON-objekt som innehåller den information som krävs för att användaren ska kunna logga in.

Parameter	Format	beskrivning
`device_code`	String	En lång sträng som används för att verifiera sessionen mellan klienten och auktoriseringsservern. Klienten använder den här parametern för att begära åtkomsttoken från auktoriseringsservern.
`user_code`	String	En kort sträng som visas för användaren som används för att identifiera sessionen på en sekundär enhet.
`verification_uri`	URI	Den URI som användaren ska gå till med `user_code` för att logga in.
`expires_in`	heltal	Antalet sekunder innan `device_code` och `user_code` upphör att gälla.
`interval`	heltal	Antalet sekunder som klienten ska vänta mellan avsökningsbegäranden.
`message`	String	En läsbar sträng för människor med instruktioner för användaren. Detta kan lokaliseras genom att inkludera en frågeparameter i begäran av formuläret `?mkt=xx-XX`och fylla i lämplig språkkulturkod.

Kommentar

Svarsfältet verification_uri_complete ingår inte eller stöds för närvarande. Vi nämner detta eftersom om du läser den standard som visas som verification_uri_complete en valfri del av enhetskodflödesstandarden.

Autentisera användaren

När klienten har fått user_code och verification_urivisas värdena och användaren uppmanas att logga in via sin mobil- eller datorwebbläsare.

Om användaren autentiserar med ett personligt konto, med eller /common/consumers, uppmanas de att logga in igen för att överföra autentiseringstillståndet till enheten. Det beror på att enheten inte kan komma åt användarens cookies. De uppmanas att samtycka till de behörigheter som begärs av klienten. Detta gäller dock inte för arbets- eller skolkonton som används för att autentisera.

Medan användaren autentiserar verification_urivid bör klienten avsöka /token slutpunkten för den begärda token med hjälp av 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...

Parameter	Obligatoriskt	Beskrivning
`tenant`	Obligatoriskt	Samma klient- eller klientalias som användes i den första begäran.
`grant_type`	Obligatoriskt	Måste vara `urn:ietf:params:oauth:grant-type:device_code`
`client_id`	Obligatoriskt	Måste matcha den `client_id` som användes i den första begäran.
`device_code`	Obligatoriskt	Den `device_code` som returneras i begäran om enhetsauktorisering.

Förväntade fel

Enhetskodflödet är ett avsökningsprotokoll, så fel som hanteras till klienten måste förväntas innan användarautentiseringen har slutförts.

Fel	beskrivning	Klientåtgärd
`authorization_pending`	Användaren har inte slutfört autentiseringen, men har inte avbrutit flödet.	Upprepa begäran efter minst `interval` sekunder.
`authorization_declined`	Slutanvändaren nekade auktoriseringsbegäran.	Stoppa avsökningen och återgå till ett oautentiserat tillstånd.
`bad_verification_code`	Den `device_code` som skickades till `/token` slutpunkten kändes inte igen.	Kontrollera att klienten skickar rätt `device_code` i begäran.
`expired_token`	`expires_in` Värdet för har överskridits och autentisering är inte längre möjligt med `device_code`.	Stoppa avsökningen och återgå till ett oautentiserat tillstånd.

Lyckat autentiseringssvar

Ett lyckat tokensvar ser ut så här:

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

Parameter	Format	beskrivning
`token_type`	String	Alltid `Bearer`.
`scope`	Blankstegsavgränsade strängar	Om en åtkomsttoken returnerades visas de omfång som åtkomsttoken är giltig för.
`expires_in`	heltal	Antal sekunder som den inkluderade åtkomsttoken är giltig för.
`access_token`	Ogenomskinlig sträng	Utfärdat för de omfång som begärdes .
`id_token`	JWT	Utfärdad om den ursprungliga `scope` parametern inkluderade omfånget `openid` .
`refresh_token`	Ogenomskinlig sträng	Utfärdad om den ursprungliga `scope` parametern inkluderade `offline_access`.

Du kan använda uppdateringstoken för att hämta nya åtkomsttoken och uppdateringstoken med samma flöde som dokumenteras i OAuth Code-flödesdokumentationen.

Varning

Försök inte verifiera eller läsa token för något API som du inte äger, inklusive token i det här exemplet, i koden. Token för Microsoft-tjänster kan använda ett särskilt format som inte verifieras som en JWT och som även kan krypteras för konsumentanvändare (Microsoft-konto). Läs token är ett användbart felsöknings- och inlärningsverktyg, men använd inte beroenden för detta i koden eller anta detaljer om token som inte är för ett API som du kontrollerar.

Dela via