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

Článek
04/08/2024

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`, `/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`	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=00001111-aaaa-2222-bbbb-3333cccc4444&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_access`pů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.

Sdílet prostřednictvím