Microsoft identity platform a implicitní tok udělení oprávnění
Rozhraní Microsoft identity platform podporuje tok implicitního udělení OAuth 2.0, jak je popsáno ve specifikaci OAuth 2.0. Definující charakteristikou implicitního udělení je, že tokeny (tokeny ID nebo přístupové tokeny) se vrátí přímo z koncového bodu /authorize místo koncového bodu /token. To se často používá jako součást toku autorizačního kódu vtakzvaném "hybridním toku" – načtení tokenu ID v požadavku /authorize spolu s autorizačním kódem.
Tento článek popisuje, jak programovat přímo s protokolem ve vaší aplikaci a žádat o tokeny ze služby Azure AD. Pokud je to možné, doporučujeme místo toho použít podporované knihovny Microsoft Authentication Library (MSAL) k získání tokenů a volání zabezpečených webových rozhraní API. Podívejte se také na ukázkové aplikace, které používají MSAL.
Tip
Zkuste tento požadavek a další informace odeslat v Postmanu – nezapomeňte nahradit tokeny a ID.
Preferovat tok ověřovacího kódu
Vzhledem k tomu, že plány odebránísouborů cookie třetích stran z prohlížečů už není tok implicitního udělení oprávnění vhodnou metodou ověřování. Bezobslužné funkce jednotného přihlašování implicitního toku nefungují bez souborů cookie třetích stran, což způsobí, že se aplikace při pokusu o získání nového tokenu přeruší. Důrazně doporučujeme, aby všechny nové aplikace místo implicitního toku používají tok autorizačního kódu, který teď místo implicitního toku podporuje jedno stránkovací aplikace, a aby se na tok autorizačního kódu začaly migrovat i stávající jedno stránkovací aplikace.
Vhodné scénáře pro implicitní udělení OAuth2
Implicitní udělení je spolehlivé pouze pro počáteční interaktivní část toku přihlášení, kdy absence souborů cookie třetích stran nemůže mít vliv na vaši aplikaci. Toto omezení znamená, že byste ho měli používat výhradně jako součást hybridního toku, kdy vaše aplikace požaduje kód a také token z koncového bodu autorizace. Tím zajistíte, že vaše aplikace obdrží kód, který je možné uplatnit na obnovovací token, a tím zajistíte, že přihlašovací relace vaší aplikace zůstane v průběhu času platná.
Diagram protokolu
Následující diagram znázorňuje, jak vypadá celý tok implicitního přihlašování, a následující části popisují jednotlivé kroky podrobněji.
Odeslání žádosti o přihlášení
Pokud chcete uživatele nejprve přihlásit k aplikaci, můžete odeslat OpenID Připojení o ověření a získat ho z id_token Microsoft identity platform.
Důležité
Pokud chcete úspěšně požádat o token ID nebo přístupový token, musí mít registrace aplikace na stránce Azure Portal – Registrace aplikací povolený odpovídající tok implicitního udělení, a to výběrem tokenů ID a přístupových tokenů v části Implicitní udělení a hybridní toky. Pokud tato možnost není povolená, unsupported_response vrátí se chyba: The provided value for the input parameter 'response_type' is not allowed for this client. Expected value is 'code'
// Line breaks for legibility only
https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&response_type=id_token
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&scope=openid
&response_mode=fragment
&state=12345
&nonce=678910
Tip
Pokud chcete otestovat přihlášení pomocí implicitního toku, klikněte na https://login.microsoftonline.com/common/oauth2/v2.0/authorize.. . Po přihlášení by se prohlížeč měl přesměrovat na adresu s na https://localhost/myapp/ id_token panelu Adresa.
| Parametr | Typ | Description |
|---|---|---|
tenant |
vyžadováno | Hodnotu v cestě požadavku můžete použít k řízení toho, kdo {tenant} se může přihlásit k aplikaci. Povolené hodnoty jsou common organizations , , a consumers identifikátory tenanta. Další podrobnosti najdete v tématu Základy protokolů. V případě scénářů hosta, kdy podepíšete uživatele z jednoho tenanta do jiného tenanta, je důležité zadat identifikátor tenanta, abyste ho správně zaregistrovali do tenanta prostředků. |
client_id |
vyžadováno | ID aplikace (klienta), které Azure Portal – Registrace aplikací přiřazené vaší aplikaci. |
response_type |
vyžadováno | Musí obsahovat id_token pro OpenID Připojení přihlášení. Může také zahrnovat response_type token . Použití této funkce umožní vaší aplikaci okamžitě získat přístupový token z koncového bodu autorizace bez nutnosti provádět druhý požadavek token na koncový bod autorizace. Pokud použijete response_type, musí parametr obsahovat obor určující, pro který prostředek se má token vydat token scope (například user.read v Microsoft Graph). Může také obsahovat místo code pro token poskytnutí autorizačního kódu pro použití v toku autorizačního kódu. Tato id_token a kód se někdy nazývá hybridní tok. |
redirect_uri |
Doporučené | Název redirect_uri, kam může vaše aplikace odeslat a získat ověřovací odpovědi. Musí přesně odpovídat jedné z možností redirect_uris jste zaregistrovali na portálu, ale musí být zakódovaná pomocí adresy URL. |
scope |
vyžadováno | Seznam oborů oddělených mezerami. Pro OpenID Připojení (id_tokens) musí obsahovat obor , který se v uživatelském rozhraní pro souhlas přeloží na oprávnění openid "Přihlásit se". Volitelně můžete také zahrnout obory a pro získání přístupu k dalším email profile uživatelským datům. V případě vyžádání přístupového tokenu můžete do této žádosti o souhlas s různými prostředky zahrnout také další rozsahy. |
response_mode |
optional | Určuje metodu, která se má použít k odeslání výsledného tokenu zpět do vaší aplikace. Ve výchozím nastavení se dotazuje pouze na přístupový token, ale fragmentuje se, pokud požadavek obsahuje id_token. |
state |
Doporučené | Hodnota zahrnutá v požadavku, která bude vrácena také v odpovědi tokenu. Může to být řetězec libovolného obsahu, který chcete. Náhodně vygenerovaná jedinečná hodnota se obvykle používá k tomu, aby se zabránilo útokům na padělání požadavků napříč weby. Stav se také používá ke kódování informací o stavu uživatele v aplikaci před tím, než došlo k požadavku na ověření, jako je například stránka nebo zobrazení, na které byl uživatel. |
nonce |
vyžadováno | Hodnota zahrnutá v požadavku vygenerovaná aplikací, která bude zahrnutá ve výsledném id_token jako deklarace identity. Aplikace pak může tuto hodnotu ověřit, aby se zmírněly útoky při opětovném přehrání tokenu. Hodnota je obvykle náhodný jedinečný řetězec, který lze použít k identifikaci původu požadavku. Vyžaduje se pouze v případě id_token je vyžadována žádost o oprávnění uživatele. |
prompt |
optional | Určuje typ interakce uživatele, který je vyžadován. Jediné platné hodnoty jsou v tuto chvíli login(přihlášení), none (žádný), select_account (select_account) a consent (souhlas). prompt=login vynutí zadání přihlašovacích údajů uživatele k této žádosti a negace jednotného přihlašování. prompt=none je naopak – zajistí, že se uživateli vůbec nebude prezentovat žádná interaktivní výzva. Pokud požadavek nelze dokončit bezobslužně prostřednictvím jednotného přihlašování, Microsoft identity platform vrátí chybu. prompt=select_account odešle uživatele do výběru účtu, kde se zobrazí všechny účty, které se v relaci zapamatují. prompt=consent po přihlášení uživatele aktivuje dialogové okno souhlasu OAuth s žádostí uživatele o udělení oprávnění k aplikaci. |
login_hint |
optional | Tento parametr můžete použít k předběžnému vyplnění pole uživatelského jména a e-mailové adresy přihlašovací stránky uživatele, pokud uživatelské jméno znáte předem. Aplikace tento parametr často používají při opětovném ověření po extrakci volitelné deklarace login_hint identity z dřívějšího přihlášení. |
domain_hint |
optional | Pokud je zahrnutý, přeskočí proces zjišťování na základě e-mailu, který uživatel prochází na přihlašovací stránce, což vede k trochu jednoduššímu uživatelskému prostředí. Tento parametr se běžně používá pro obchodní aplikace, které fungují v jednom tenantovi, kde zadá název domény v rámci daného tenanta a předá uživatele poskytovateli federace pro daného tenanta. Všimněte si, že tento tip brání hostům v přihlášení k této aplikaci a omezuje použití cloudových přihlašovacích údajů, jako je FIDO. |
V tomto okamžiku se uživateli zobrazí dotaz, jestli má zadat svoje přihlašovací údaje a dokončit ověření. Následující Microsoft identity platform také zajistí, že uživatel souhlasí s oprávněními uvedená v scope parametru dotazu. Pokud uživatel s žádným z těchto oprávnění souhlasí, požádá ho o souhlas s požadovanými oprávněními. Další informace najdete v článku o oprávněních, souhlasu a aplikacích s více tenanty.
Jakmile se uživatel ověří a udělí souhlas, Microsoft identity platform vrátí vaší aplikaci odpověď na vyznačené adrese pomocí metody zadané redirect_uri v response_mode parametru .
Úspěšná odpověď
Úspěšná odpověď pomocí příkazu a response_mode=fragment response_type=id_token+code vypadá takto (s koncům řádků kvůli čitelnosti):
GET https://localhost/myapp/#
code=0.AgAAktYV-sfpYESnQynylW_UKZmH-C9y_G1A
&id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...
&state=12345
| Parametr | Popis |
|---|---|
code |
Zahrnuto v response_type případě, že code zahrnuje . Jedná se o autorizační kód vhodný pro použití v toku autorizačního kódu. |
access_token |
Zahrnuto v response_type případě, že token zahrnuje . Přístupový token, který aplikace požaduje. Přístupový token by se neměl dekódovat ani jinak kontrolovat, měl by se považovat za neprůhledný řetězec. |
token_type |
Zahrnuto v response_type případě, že token zahrnuje . Bude vždy Bearer . |
expires_in |
Zahrnuto v response_type případě, že token zahrnuje . Určuje počet sekund, po který je token platný pro účely ukládání do mezipaměti. |
scope |
Zahrnuto v response_type případě, že token zahrnuje . Určuje obory, pro které access_token budou platné. Nemusí zahrnovat všechny požadované obory, pokud nebyly použitelné pro uživatele (v případě, že se požaduje jenom obory Azure AD, když se k přihlášení použije osobní účet). |
id_token |
Podepsaný JSON Web Token (JWT). Aplikace může dekódovat segmenty tohoto tokenu a požádat o informace o přihlášeném uživateli. Aplikace může hodnoty ukládat do mezipaměti a zobrazovat je, ale neměla by se na ně spoléhat při autorizaci nebo zabezpečení. Další informace o id_tokens najdete v tématu id_token reference . Poznámka: K dispozici pouze v openid případě, že byl požadován obor response_type a zahrnut id_tokens . |
state |
Pokud je v požadavku zahrnut parametr stavu, měla by se v odpovědi objevit stejná hodnota. Aplikace by měla ověřit, že hodnoty stavu v požadavku a odpovědi jsou identické. |
Upozornění
Nepokoušejte se ve svém kódu ověřovat ani číst tokeny pro žádné rozhraní API, které vlastníte, včetně tokenů v tomto příkladu. Tokeny pro služby Microsoft mohou používat speciální formát, který se neověřuje jako JWT a může být také šifrován pro uživatele příjemce (účet Microsoft). Čtení tokenů je užitečný nástroj pro ladění a učení, ale nezá závislostí na tomto tokenu v kódu ani předpokládejte konkrétní informace o tokenech, které nejsou pro rozhraní API, které řídíte.
Chybová odpověď
Chybové odpovědi je také možné odeslat do , redirect_uri aby je aplikace dokáže odpovídajícím způsobem zpracovat:
GET https://localhost/myapp/#
error=access_denied
&error_description=the+user+canceled+the+authentication
| Parametr | Popis |
|---|---|
error |
Řetězec kódu chyby, který lze použít ke klasifikaci typů chyb, ke kterým dojde, a lze ho použít k reakci na chyby. |
error_description |
Konkrétní chybová zpráva, která může vývojáři pomoct identifikovat hlavní příčinu chyby ověřování. |
Získání přístupových tokenů bezobslužně na pozadí
Důležité
Tato část implicitního toku pravděpodobně nebude fungovat pro vaši aplikaci, protože se používá v různých prohlížečích kvůli odebrání souborů cookie třetích stran ve výchozím nastavení. I když to stále funguje Chromium prohlížečích, které nejsou v anonymním režimu, měli by vývojáři tuto část toku znovu zvážit. V prohlížečích, které nepodporují soubory cookie třetích stran, se zobrazí chyba oznamující, že se nepřihlásí žádní uživatelé, protože soubory cookie relace přihlašovací stránky odebral prohlížeč.
Teď, když jste uživatele přihlásili k jedno stránkovací aplikaci, můžete bezobslužně získat přístupové tokeny pro volání webových rozhraní API zabezpečených službou Microsoft identity platform, jako je například Microsoft Graph. I když jste již obdrželi token pomocí response_type, můžete pomocí této metody získat tokeny k dalším prostředkům, aniž byste museli uživatele přesměrovat, aby se znovu token přihlašoval.
V normálním toku OpenID Připojení/OAuth byste to provést vytvořením požadavku na koncový Microsoft identity platform /token koncového bodu. Požadavek můžete vytvořit ve skrytém elementu iframe, abyste mohli získat nové tokeny pro jiná webová rozhraní API:
// Line breaks for legibility only
https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&response_type=token
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fuser.read
&response_mode=fragment
&state=12345
&nonce=678910
&prompt=none
&login_hint=myuser@mycompany.com
Podrobnosti o parametrech dotazu v adrese URL najdete v tématu odeslání žádosti o přihlášení.
Tip
Zkuste & níže uvedený požadavek na kartu prohlížeče. (Nezapomeňte nahradit hodnoty správnou login_hint hodnotou pro vašeho uživatele.)
https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id=6731de76-14a6-49ae-97bc-6eba6914391e&response_type=token&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F&scope=https%3A%2F%2Fgraph.microsoft.com%2Fuser.read&response_mode=fragment&state=12345&nonce=678910&prompt=none&login_hint={your-username}
Všimněte si, že to bude fungovat i v prohlížečích bez podpory souborů cookie třetích stran, protože ho zadáváte přímo do panelu prohlížeče, a ne v rámci iframe.
Díky parametru bude tento požadavek buď úspěšný, nebo okamžitě selže a prompt=none vrátí se do vaší aplikace. Odpověď bude odeslána do vaší aplikace na vyznačené redirect_uri adrese pomocí metody zadané v response_mode parametru .
Úspěšná odpověď
Úspěšná odpověď s response_mode=fragment použitím příkazu vypadá asi takhle:
GET https://localhost/myapp/#
access_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...
&state=12345
&token_type=Bearer
&expires_in=3599
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fdirectory.read
| Parametr | Popis |
|---|---|
access_token |
Zahrnuto v response_type případě, že zahrnuje token . Přístupový token, o který aplikace požádala, v tomto případě pro Microsoft Graph. Přístupový token by se neměl dekódovat ani jinak kontrolovat, měl by se považovat za neprůhledný řetězec. |
token_type |
Bude vždy Bearer . |
expires_in |
Určuje počet sekund, po který je token platný pro účely ukládání do mezipaměti. |
scope |
Určuje obory, pro které bude access_token platná. Nemusí zahrnovat všechny požadované obory, pokud nebyly použitelné pro uživatele (v případě, že se požaduje jenom obory Azure AD, když se k přihlášení použije osobní účet). |
id_token |
Podepsaný JSON Web Token (JWT). Zahrnuto v response_type případě, že zahrnuje id_token . Aplikace může dekódovat segmenty tohoto tokenu a požádat o informace o přihlášeném uživateli. Aplikace může hodnoty ukládat do mezipaměti a zobrazovat je, ale neměla by se na ně spoléhat při autorizaci nebo zabezpečení. Další informace o id_tokens najdete v id_token referenčních informacích. Poznámka: K dispozici pouze v openid případě, že byl požadován obor. |
state |
Pokud je v požadavku zahrnut parametr stavu, měla by se v odpovědi objevit stejná hodnota. Aplikace by měla ověřit, že hodnoty stavu v požadavku a odpovědi jsou identické. |
Chybová odpověď
Chybové odpovědi je také možné odeslat do redirect_uri , aby je aplikace dokáže odpovídajícím způsobem zpracovat. V případě prompt=none bude očekávaná chyba:
GET https://localhost/myapp/#
error=user_authentication_required
&error_description=the+request+could+not+be+completed+silently
| Parametr | Popis |
|---|---|
error |
Řetězec kódu chyby, který lze použít ke klasifikaci typů chyb, ke kterým dojde, a lze ho použít k reakci na chyby. |
error_description |
Konkrétní chybová zpráva, která může vývojáři pomoct identifikovat hlavní příčinu chyby ověřování. |
Pokud se tato chyba zobrazí v požadavku iframe, musí se uživatel znovu interaktivně přihlásit, aby získal nový token. Tento případ můžete zpracovat způsobem, který dává smysl pro vaši aplikaci.
Aktualizace tokenů
Implicitní udělení neposkytuje obnovovací tokeny. Platnost hodnot i s vyprší po krátké době, takže vaše aplikace musí být připravená na pravidelné id_token access_token aktualizace těchto tokenů. Pokud chcete aktualizovat některý z typů tokenů, můžete provést stejný skrytý požadavek iframe uvedený výše pomocí parametru , který řídí chování prompt=none platformy identit. Pokud chcete získat nový , nezapomeňte použít v a id_token id_token a také parametr response_type scope=openid nonce .
V prohlížečích, které nepodporují soubory cookie třetích stran, se zobrazí chyba oznamující, že není přihlášený žádný uživatel.
Odeslání žádosti o odhlášení
OpenID Připojení umožňuje vaší aplikaci odeslat požadavek na Microsoft identity platform, aby se ukončí relace uživatele, a vymazat soubory cookie nastavené end_session_endpoint Microsoft identity platform . Pokud chcete uživatele úplně odhlásit z webové aplikace, měla by aplikace ukončit vlastní relaci s uživatelem (obvykle vymazáním mezipaměti tokenů nebo vyhozením souborů cookie) a pak přesměrovat prohlížeč na:
https://login.microsoftonline.com/{tenant}/oauth2/v2.0/logout?post_logout_redirect_uri=https://localhost/myapp/
| Parametr | Typ | Description |
|---|---|---|
tenant |
vyžadováno | Hodnotu v cestě požadavku můžete použít k řízení toho, kdo {tenant} se může přihlásit k aplikaci. Povolené hodnoty jsou common organizations , , a consumers identifikátory tenanta. Další podrobnosti najdete v tématu Základy protokolů. |
post_logout_redirect_uri |
Doporučené | Adresa URL, na kterou se má uživatel vrátit po dokončení odhlášení. Tato hodnota musí odpovídat jedné z identifikátorů URI přesměrování zaregistrovaných pro aplikaci. Pokud není zahrnutý, uživateli se zobrazí obecná zpráva od Microsoft identity platform. |
Další kroky
- Pokud chcete začít kódovat, prohlédněte si ukázky MSAL JS.
- Zkontrolujte tok autorizačního kódu jako novější, lepší alternativu k implicitnímu udělení.