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 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=535fb089-9ff3-47b6-9bfb-4f1264799865
&scope=user.read%20openid%20profile

Parameter Villkor beskrivning
tenant Obligatoriskt Kan vara /common, /consumerseller /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-XXoch 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=535fb089-9ff3-47b6-9bfb-4f1264799865&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.