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

  • Článek

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 vaši aplikaci programovat přímo s použitím protokolu. Pokud je to možné, doporučujeme místo získávání tokenů a volání zabezpečených webových rozhraní API raději používat podporované knihovny MSAL (Microsoft Authentication Libraries). 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.

Device code flow

Žá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 /devicecode bodu. 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í účastníci Může být /common, /consumersnebo /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 Požaduje se ID aplikace (klienta), které centrum pro správu Microsoft Entra – Registrace aplikací prostředí přiřazené k vaší aplikaci.
scope Požaduje se 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 String 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 String 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 String Ř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=535fb089-9ff3-47b6-9bfb-4f1264799865&device_code=GMMhmHCXhWEzkobqIHGG_EnNYYsAkukHspeYUk9E8...
Parametr Požadováno Popis
tenant Povinní účastníci Stejný alias tenanta nebo tenanta použitý v počáteční žádosti.
grant_type Požaduje se Musí být urn:ietf:params:oauth:grant-type:device_code
client_id Požaduje se Musí odpovídat client_id použitému v počátečním požadavku.
device_code Požaduje se 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 String Vždy hodnota Bearer.
scope Řádkování oddělených řetězců 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 požadované obory .
id_token JWT Vydáno, pokud původní scope parametr zahrnoval openid obor.
refresh_token Neprůzný řetězec Vydáno, pokud byl součástí offline_accesspůvodního scope parametru .

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.

Upozorňující

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 Microsoft můžou používat speciální formát, který se neověří jako JWT a může být také zašifrovaný pro uživatele s uživatelským účtem (účtem 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.