Microsoft identity platform a tok udělení autorizace zařízení OAuth 2.0

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í televize, zařízení IoT nebo tiskárna. Pokud chcete tento tok povolit, musí uživatel navštívit webovou stránku v prohlížeči na jiném zařízení a přihlásit se. Jakmile se uživatel přihlásí, může zařízení podle potřeby získat přístupové tokeny a tokeny aktualizovat.

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 toho k získání tokenů a volání zabezpečených webových rozhraní API použít podporované knihovny Microsoft Authentication Libraries (MSAL). Příklady najdete v ukázkových aplikacích, které používají KNIHOVNu MSAL .

Tip

Zkuste spustit tento požadavek v nástroji Postman.
Zkuste spustit tento a další požadavky v nástroji Postman – nezapomeňte nahradit tokeny a ID.

Diagram protokolu

Celý tok kódu zařízení je znázorněn v následujícím diagramu. Jednotlivé kroky jsou vysvětlené v tomto článku.

Tok kódu zařízení

Žádost o autorizaci zařízení

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

Od okamžiku odeslání žádosti má uživatel 15 minut na přihlášení. Toto je výchozí hodnota pro expires_in. Žádost by se měla podat jenom v případě, že uživatel uvedl, ž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=6731de76-14a6-49ae-97bc-6eba6914391e
&scope=user.read%20openid%20profile

Parametr Podmínka Popis
tenant Povinné 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 Vyžadováno ID aplikace (klienta), které Azure Portal – Registrace aplikací prostředí přiřazené vaší aplikaci.
scope Vyžadováno Seznam oborů oddělených mezerami , se kterými má uživatel vyjádřit souhlas.

Odpověď na autorizaci zařízení

Úspěšná odpověď bude objekt JSON obsahující požadované informace, aby se uživatel mohl přihlásit.

Parametr Formát Description
device_code Řetězec Dlouhý řetězec, který slouží 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ý slouží 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 pomocí , aby se mohl přihlásit.
expires_in int Počet sekund před device_code a user_code vypršením platnosti.
interval int Počet sekund, po který by měl klient čekat mezi požadavky dotazování.
message Řetězec Řetězec čitelný pro člověka s pokyny pro uživatele. To se dá lokalizovat zahrnutím parametru dotazu do požadavku formuláře ?mkt=xx-XXa vyplněním kódu jazykové verze příslušného jazyka.

Poznámka

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

Ověření uživatele

Jakmile user_code klient obdrží a verification_uri, zobrazí je uživateli s pokynem, aby k přihlášení použil mobilní telefon nebo prohlížeč počítače.

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

Zatímco se uživatel ověřuje v objektu verification_uri, klient by se měl dotazovat koncovému /token bodu na požadovaný token pomocí device_code.

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=6731de76-14a6-49ae-97bc-6eba6914391e&device_code=GMMhmHCXhWEzkobqIHGG_EnNYYsAkukHspeYUk9E8...
Parametr Povinné Popis
tenant Povinné Stejný alias tenanta nebo tenanta použitý v počáteční žádosti.
grant_type Vyžadováno Musí být urn:ietf:params:oauth:grant-type:device_code
client_id Vyžadováno Musí odpovídat hodnotě client_id použité v počáteční žádosti.
device_code Vyžadováno Hodnota 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 před dokončením ověřování uživatele je potřeba očekávat chyby doručené klientovi.

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

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

Úspěšná odpověď tokenu bude vypadat 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 Description
token_type Řetězec Vždy hodnota 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, po který je zahrnutý přístupový token platný.
access_token Neprůszný řetězec Vydáno pro požadované obory .
id_token JWT Vydáno, pokud původní scope parametr zahrnoval openid obor.
refresh_token Neprůsvný řetězec Vydáno, pokud původní scope parametr obsahoval 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 kódu OAuth.

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 Microsoftu můžou používat speciální formát, který se neověří jako JWT, a můžou být také šifrované pro uživatele s uživatelským účtem (účet Microsoft). Čtení tokenů je užitečný nástroj pro ladění a výuku, ale nepřebídejte na nich v kódu závislosti ani nepředpokládáte specifika tokenů, které nejsou pro rozhraní API, které ovládáte.