Dela via

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.

Den här artikeln beskriver hur du programmerar direkt mot protokollet i ditt program. När det är möjligt rekommenderar vi att du använder Microsofts autentiseringsbibliotek (MSAL) som stöds i stället för att hämta tokens 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.

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 slutpunkten /devicecode. 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 Tillstånd Beskrivning
tenant Krävs 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 Krävs Det applikations-ID (klient-ID) som tilldelats din app i administrationscentret för Microsoft Entra – Appregistreringar.
scope Krävs 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 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 (Uniform Resource Identifier) Den URI som användaren ska gå till med user_code för att logga in.
expires_in Int Antalet sekunder innan device_code och user_code upphör att gälla.
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.

Anmärkning

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 Krävs Beskrivning
tenant Krävs Samma klient- eller klientalias som användes i den första begäran.
grant_type Krävs Måste vara urn:ietf:params:oauth:grant-type:device_code
client_id Krävs Måste matcha den client_id som användes i den första begäran.
device_code Krävs 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 Sträng Alltid Bearer.
scope Strängar som separeras med mellanslag 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 -skop som begärdes.
id_token JWT Utfärdad om den ursprungliga scope-parametern innehöll openid omfång.
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). Att läsa tokens är ett användbart felsöknings- och inlärningsverktyg, men använd inte beroenden av detta i din kod eller anta detaljer om tokens som inte är för ett API som du kontrollerar.