Microsoft Identity Platform a tok udělení autorizace zařízení OAuth 2.0

2025-04-02

Platforma Microsoft Identity Platform podporuje udělení autorizace zařízení, které uživatelům umožňuje přihlásit se k zařízením s omezeným vstupem, jako je inteligentní TV, zařízení IoT nebo tiskárna. Aby bylo možné tento tok povolit, musí zařízení navštívit webovou stránku v prohlížeči na jiném zařízení, aby se mohl přihlásit. Jakmile se uživatel přihlásí, zařízení může podle potřeby získat přístupové tokeny a aktualizovat tokeny.

Tento článek popisuje, jak programovat přímo proti protokolu ve vaší aplikaci. Pokud je to možné, doporučujeme místo toho použít podporované knihovny MSAL (Microsoft Authentication Library) k získání tokenů a volání zabezpečených webových rozhraní API. Příklady najdete v ukázkových aplikacích, které používají knihovnu MSAL .

Diagram protokolu

Celý tok kódu zařízení se zobrazuje v následujícím diagramu. Každý krok je vysvětlený v tomto článku.

tok kódu zařízení

Žádost o autorizaci zařízení

Klient musí nejprve zkontrolovat ověřovací server pro zařízení a uživatelský kód použitý k zahájení ověřování. Klient shromažďuje tento požadavek z koncového bodu /devicecode. V požadavku by měl klient obsahovat také oprávnění, která potřebuje k získání od uživatele.

Od okamžiku odeslání požadavku má uživatel k přihlášení 15 minut. Toto je výchozí hodnota pro expires_in. Požadavek by měl být proveden pouze v případě, že uživatel indikuje, že je připraven k přihlášení.

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

Parametr	Podmínka	Popis
`tenant`	Povinné	Může být `/common`, `/consumers`nebo `/organizations`. Může to být také tenant adresáře, od kterého chcete požádat o oprávnění ve formátu GUID nebo popisného názvu.
`client_id`	Povinné	ID aplikace (klienta), které vaše aplikace získala prostřednictvím prostředí centrum pro správu Microsoft Entra – Registrace aplikací.
`scope`	Povinné	Seznam oborů oddělených mezerami, se kterými má uživatel souhlasit.

Odpověď na autorizaci zařízení

Úspěšná odpověď je objekt JSON obsahující požadované informace, které uživateli umožní přihlásit se.

Parametr	Formát	Popis
`device_code`	Řetězec	Dlouhý řetězec použitý k ověření relace mezi klientem a autorizačním serverem. Klient použije tento parametr k vyžádání přístupového tokenu z autorizačního serveru.
`user_code`	Řetězec	Krátký řetězec zobrazený uživateli, který se používá k identifikaci relace na sekundárním zařízení.
`verification_uri`	Identifikátor uri	Identifikátor URI, na který by měl uživatel přejít, `user_code` aby se mohl přihlásit.
`expires_in`	Int	Počet sekund před vypršením `device_code` platnosti.`user_code`
`interval`	Int	Počet sekund, po které má klient čekat mezi požadavky dotazování.
`message`	Řetězec	Řetězec čitelný člověkem s pokyny pro uživatele. To lze lokalizovat zahrnutím parametru dotazu do požadavku formuláře `?mkt=xx-XX`, vyplněním příslušného jazykového kódu jazyka.

Poznámka:

Pole verification_uri_complete odpovědi není v tuto chvíli zahrnuto ani podporováno. Zmíníme to, protože pokud si přečtete normu , která verification_uri_complete je uvedená jako volitelná součást standardu toku kódu zařízení.

Ověřování uživatele

Jakmile klient obdrží user_code a verification_urizobrazí se hodnoty a uživatel se přesměruje, aby se přihlásil prostřednictvím svého mobilního nebo počítačového prohlížeče.

Pokud se uživatel ověří pomocí osobního účtu nebo /common/consumers, zobrazí se výzva k opětovnému přihlášení, aby se do zařízení přenesl do stavu ověřování. Důvodem je to, že zařízení nemá přístup k souborům cookie uživatele. Zobrazí se výzva k vyjádření souhlasu s oprávněními požadovanými klientem. To se ale nevztahuje na pracovní nebo školní účty používané k ověření.

Zatímco se uživatel ověřuje v objektu verification_uri, měl by se klient dotazovat /token na koncový bod požadovaného tokenu device_codepomocí .

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

Parametr	Povinné	Popis
`tenant`	Povinné	Stejný alias tenanta nebo tenanta použitý v počáteční žádosti.
`grant_type`	Povinné	Musí být `urn:ietf:params:oauth:grant-type:device_code`
`client_id`	Povinné	Musí odpovídat `client_id` použitému v počátečním požadavku.
`device_code`	Povinné	Vrácená `device_code` v žádosti o autorizaci zařízení.

Očekávané chyby

Tok kódu zařízení je protokol dotazování, takže chyby obsluhované klientovi se musí před dokončením ověřování uživatele očekávat.

Chyba	Popis	Akce klienta
`authorization_pending`	Uživatel nedokončil ověřování, ale nezrušil tok.	Opakujte požadavek po alespoň `interval` sekundách.
`authorization_declined`	Koncový uživatel zamítl žádost o autorizaci.	Ukončete dotazování a vraťte se k neověřenému stavu.
`bad_verification_code`	Odeslaná `device_code` do koncového `/token` bodu nebyla rozpoznána.	Ověřte, že klient odesílá v požadavku správný kód `device_code` .
`expired_token`	`expires_in` Hodnota byla překročena a ověřování již není možné s `device_code`.	Ukončete dotazování a vraťte se k neověřenému stavu.

Úspěšná odpověď na ověření

Úspěšná odpověď tokenu vypadá takto:

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

Parametr	Formát	Popis
`token_type`	Řetězec	Vždy `Bearer`.
`scope`	Řetězce oddělené mezerami	Pokud byl vrácen přístupový token, zobrazí se seznam oborů, ve kterých je přístupový token platný.
`expires_in`	Int	Počet sekund, pro které je zahrnutý přístupový token platný.
`access_token`	Neprůzný řetězec	Vydáno pro obory , které byly požadovány.
`id_token`	JWT	Vydáno, pokud původní `scope` parametr zahrnoval rozsah `openid`.
`refresh_token`	Neprůzný řetězec	Vydáno, pokud původní `scope` parametr zahrnoval `offline_access`.

Obnovovací token můžete použít k získání nových přístupových tokenů a obnovovacích tokenů pomocí stejného toku popsaného v dokumentaci k toku OAuth Code.

Výstraha

Nepokoušejte se ověřovat ani číst tokeny pro žádné rozhraní API, které nevlastníte, včetně tokenů v tomto příkladu, ve vašem kódu. Tokeny pro služby Microsoftu můžou používat speciální formát, který se neověří jako JWT a může být také zašifrován pro uživatele s uživatelským účtem (účet Microsoft). Přestože je čtení tokenů užitečným nástrojem pro ladění a učení, nepřebídejte závislosti na tomto kódu ani nepředpokládejte konkrétní údaje o tokenech, které nejsou určené pro rozhraní API, které řídíte.

Sdílet prostřednictvím