Microsoft Identitásplatform és az OAuth 2.0 eszközengedélyezési engedélyezési folyamat

Cikk
04/08/2024

A Microsoft Identitásplatform támogatja az eszközengedélyezési engedélyt, amely lehetővé teszi a felhasználók számára, hogy bejelentkezhessenek a bemeneti korlátozásokkal rendelkező eszközökre, például intelligens TV-be, IoT-eszközbe vagy nyomtatóba. A folyamat engedélyezéséhez az eszköz egy másik eszközön lévő böngészőben egy weblapot látogat meg a bejelentkezéshez. Miután a felhasználó bejelentkezett, az eszköz szükség szerint lekérheti a hozzáférési jogkivonatokat és frissítheti a jogkivonatokat.

Ez a cikk azt ismerteti, hogy hogyan programozhat közvetlenül a protokollra építve az alkalmazásban. Azt javasoljuk, hogy amikor lehetséges, inkább a támogatott Microsoft hitelesítési kódtárakat (MSAL) használja a tokenek beszerzéséhez és biztonságos webes API-k meghívásához. Példákért tekintse meg az MSAL-t használó mintaalkalmazásokat.

Protokolldiagram

A teljes eszközkód-folyamat az alábbi ábrán látható. A cikk minden lépését ismerteti.

Device code flow

Eszközengedélyezési kérelem

Az ügyfélnek először meg kell keresnie a hitelesítési kiszolgálót a hitelesítés indításához használt eszköz- és felhasználói kóddal kapcsolatban. Az ügyfél a végpontról gyűjti be ezt a kérést /devicecode . A kérelemben az ügyfélnek tartalmaznia kell a felhasználótól beszerezni kívánt engedélyeket is.

A kérés elküldése után a felhasználónak 15 perce van bejelentkezni. Ez a beállítás alapértelmezett értéke expires_in. A kérés csak akkor hajtható végre, ha a felhasználó jelzi, hogy készen áll a bejelentkezésre.

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

Paraméter	Feltétel	Leírás
`tenant`	Kötelező	`/common`Lehet , `/consumers`vagy `/organizations`. Ez lehet az a címtár-bérlő is, amelytől guid vagy rövid névformátumban szeretne engedélyt kérni.
`client_id`	Kötelező	Az alkalmazás (ügyfél) azonosítója, amelyet a Microsoft Entra felügyeleti központ – Alkalmazásregisztrációk alkalmazáshoz rendelt felhasználói felület.
`scope`	Kötelező	Azoknak a hatóköröknek a szóközzel tagolt listája, amelyeket a felhasználónak engedélyeznie kell.

Eszközengedélyezési válasz

A sikeres válasz egy JSON-objektum, amely tartalmazza a felhasználó bejelentkezéséhez szükséges információkat.

Paraméter	Formátum	Leírás
`device_code`	Sztring	Az ügyfél és az engedélyezési kiszolgáló közötti munkamenet ellenőrzésére használt hosszú sztring. Az ügyfél ezzel a paraméterrel kéri le a hozzáférési jogkivonatot az engedélyezési kiszolgálótól.
`user_code`	Sztring	Egy rövid sztring, amely egy másodlagos eszközön található munkamenet azonosítására szolgál a felhasználó számára.
`verification_uri`	URI	A felhasználó `user_code` által a bejelentkezéshez szükséges URI.
`expires_in`	egész	A lejárat előtti és `user_code` a lejárat előtti `device_code` másodpercek száma.
`interval`	egész	Az ügyfél által a lekérdezési kérelmek között várakozó másodpercek száma.
`message`	Sztring	Egy emberi olvasásra alkalmas sztring, amely a felhasználó utasításait tartalmazza. Ez honosítható úgy, hogy az űrlap `?mkt=xx-XX`kérésében egy lekérdezési paramétert is beszúr, és kitölti a megfelelő nyelvi kulturális kódot.

Feljegyzés

A verification_uri_complete válaszmező jelenleg nem szerepel vagy nem támogatott. Ezt azért említjük, mert ha elolvassa a szabványt, az verification_uri_complete az eszközkód-folyamat szabványának választható részeként jelenik meg.

A felhasználó hitelesítése

Miután az ügyfél megkapta user_code és verification_urimegjelenítette az értékeket, a rendszer arra utasítja a felhasználót, hogy jelentkezzen be a mobil- vagy PC-böngészőn keresztül.

Ha a felhasználó egy személyes fiókkal hitelesít, a rendszer arra kéri, /common/consumershogy jelentkezzen be újra, hogy a hitelesítési állapotot átvihesse az eszközre. Ennek az az oka, hogy az eszköz nem tudja elérni a felhasználó cookie-ját. A rendszer arra kéri őket, hogy járuljanak hozzá az ügyfél által kért engedélyekhez. Ez azonban nem vonatkozik a hitelesítéshez használt munkahelyi vagy iskolai fiókokra.

Amíg a felhasználó hitelesíti a verification_uricímet, az ügyfélnek le kell kérnie a /token kért jogkivonat végpontjának lekérdezését a device_codehasználatával.

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

Paraméter	Kötelező	Leírás
`tenant`	Kötelező	Az eredeti kérelemben használt bérlői vagy bérlői alias.
`grant_type`	Kötelező	Kell `urn:ietf:params:oauth:grant-type:device_code`
`client_id`	Kötelező	Meg kell egyeznie a `client_id` kezdeti kérelemben használtval.
`device_code`	Kötelező	Az `device_code` eszközengedélyezési kérelemben visszaadott érték.

Várt hibák

Az eszközkód-folyamat egy lekérdezési protokoll, ezért az ügyfélnek kézbesített hibákat a felhasználói hitelesítés befejezése előtt kell elvárni.

Hiba	Leírás	Ügyfélművelet
`authorization_pending`	A felhasználó még nem fejezte be a hitelesítést, de nem törölte a folyamatot.	Ismételje meg a kérést legalább `interval` másodperc elteltével.
`authorization_declined`	A végfelhasználó megtagadta az engedélyezési kérelmet.	Állítsa le a lekérdezést, és állítsa vissza a hitelesítés nélküli állapotot.
`bad_verification_code`	A `device_code` végpontra `/token` küldött üzenet nem lett felismerve.	Ellenőrizze, hogy az ügyfél a helyes `device_code` üzenetet küldi-e a kérésben.
`expired_token`	A rendszer túllépte az `expires_in` értéket, és a hitelesítés már nem lehetséges.`device_code`	Állítsa le a lekérdezést, és állítsa vissza a hitelesítés nélküli állapotot.

Sikeres hitelesítési válasz

A sikeres jogkivonat-válasz a következőképpen néz ki:

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

Paraméter	Formátum	Leírás
`token_type`	Sztring	Mindig `Bearer`.
`scope`	Szóközzel elválasztott sztringek	Ha egy hozzáférési jogkivonatot ad vissza, ez felsorolja azokat a hatóköröket, amelyekre a hozzáférési jogkivonat érvényes.
`expires_in`	egész	A belefoglalt hozzáférési jogkivonat érvényessége másodpercben.
`access_token`	Átlátszatlan sztring	A kért hatókörökhöz lett kiadva.
`id_token`	JWT	Ki van adva, ha az eredeti `scope` paraméter tartalmazza a hatókört `openid` .
`refresh_token`	Átlátszatlan sztring	Ki van adva, ha az eredeti `scope` paramétert tartalmazza `offline_access`.

A frissítési jogkivonattal új hozzáférési jogkivonatokat és jogkivonatokat szerezhet be az OAuth Code folyamatdokumentációjában dokumentált folyamattal.

Figyelmeztetés

Ne kísérelje meg a jogkivonatok érvényesítését vagy olvasását a kódban a nem birtokolt API-k esetében, beleértve az ebben a példában szereplő jogkivonatokat is. A Microsoft-szolgáltatások jogkivonatai olyan speciális formátumot használhatnak, amely nem érvényesíthető JWT-ként, és titkosíthatók a fogyasztói (Microsoft-fiók) felhasználók számára is. Bár a jogkivonatok olvasása hasznos hibakeresési és tanulási eszköz, ne vegyen fel függőségeket a kódban, és ne feltételezze a nem ön által vezérelt API-khoz tartozó jogkivonatokat.

Megosztás a következőn keresztül: