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


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

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ő /commonLehet , /consumersvagy /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-XXké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.