Microsofts identitetsplattform och OAuth 2.0-enhetsauktoriseringsflödet

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 låter enheten användaren besöka en webbsida i en webbläsare på en annan enhet för att logga in. När användaren loggar in kan enheten hämta åtkomsttoken och uppdatera token 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.

Tips

Prova att köra den här begäran i Postman
Prova att köra den här begäran och mer i Postman – glöm inte att ersätta token och ID:t!

Protokolldiagram

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

Enhetskodflöde

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 också innehålla de behörigheter som den behöver för att hämta från användaren.

Från det ögonblick som 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 har angett 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=6731de76-14a6-49ae-97bc-6eba6914391e
&scope=user.read%20openid%20profile

Parameter Villkor Beskrivning
tenant Krävs Kan vara /common, /consumerseller /organizations. Det kan också vara katalogklientorganisationen som du vill begära behörighet från i GUID- eller eget namnformat.
client_id Obligatorisk Det program-ID (klient)-ID som Azure Portal – Appregistreringar upplevelse som tilldelats din app.
scope Obligatorisk En blankstegsavgränsad lista över omfång som du vill att användaren ska godkänna.

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 Sträng 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 Sträng 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 int Antalet sekunder före device_code och user_code förfaller.
interval int Antalet sekunder som klienten ska vänta mellan avsökningsbegäranden.
message Sträng 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-XXoch fylla i lämplig språkkulturkod.

Anteckning

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 du har fått user_code och verification_urivisar klienten dessa för användaren och instruerar dem att använda sin mobiltelefon eller datorwebbläsare för att logga in.

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 också att godkänna 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=6731de76-14a6-49ae-97bc-6eba6914391e&device_code=GMMhmHCXhWEzkobqIHGG_EnNYYsAkukHspeYUk9E8...
Parameter Krävs Beskrivning
tenant Krävs Samma klient- eller klientalias som användes i den första begäran.
grant_type Obligatorisk Måste vara urn:ietf:params:oauth:grant-type:device_code
client_id Obligatorisk Måste matcha den client_id som användes i den första begäran.
device_code Obligatorisk Returneras device_code i begäran om enhetsauktorisering.

Förväntade fel

Enhetskodflödet är ett avsökningsprotokoll, så fel som hanteras av 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 Det device_code gick inte att identifiera skickade till /token slutpunkten. Kontrollera att klienten skickar rätt device_code i begäran.
expired_token Värdet för expires_in 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 Sträng Alltid Bearer.
scope Blankstegsavgränsade strängar Om en åtkomsttoken returnerades visas de omfång som åtkomsttoken är giltig för.
expires_in int 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ärdat om den ursprungliga scope parametern inkluderade omfånget openid .
refresh_token Täckande sträng Utfärdas 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 beskrivs 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 valideras som en JWT och som även kan krypteras för konsumentanvändare (Microsoft-konto). Även om läsning av token är ett användbart felsöknings- och inlärningsverktyg bör du inte använda beroenden för detta i din kod eller anta detaljer om token som inte är för ett API som du kontrollerar.