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.
Celý tok kódu zařízení se zobrazuje v následujícím diagramu. Každý krok je vysvětlený v tomto článku.
Žá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.
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.
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.
Upozornění
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.