Implicitní tok udělení identity Od Microsoftu a OAuth 2.0
Platforma Microsoft Identity Platform podporuje implicitní tok udělení OAuth 2.0, jak je popsáno ve specifikaci OAuth 2.0. Definováním charakteristiky implicitního udělení je, že tokeny (tokeny ID nebo přístupové tokeny) se vrací přímo z koncového bodu /authorize místo koncového bodu /token. Často se používá jako součást toku autorizačního kódu v tom, co se označuje jako "hybridní tok" – načtení tokenu ID v požadavku /authorize spolu s autorizačním kódem.
Tento článek popisuje, jak programovat přímo proti protokolu v aplikaci k vyžádání tokenů z Microsoft Entra ID. 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). Podívejte se také na ukázkové aplikace, které používají KNIHOVNU MSAL.
Preferujte tok ověřovacího kódu
S plány pro odebrání souborů cookie třetích stran z prohlížečů už není tok implicitního udělení vhodný metodou ověřování. Funkce bezobslužného jednotného přihlašování (SSO) implicitního toku nefungují bez souborů cookie třetích stran, což způsobuje přerušení aplikací při pokusu o získání nového tokenu. Důrazně doporučujeme, aby všechny nové aplikace používaly tok autorizačního kódu, který teď místo implicitního toku podporuje jednostrákové aplikace. Stávající jednostrákové aplikace by se také měly migrovat do toku autorizačního kódu.
Vhodné scénáře pro implicitní udělení OAuth2
Implicitní udělení je spolehlivé pouze pro počáteční interaktivní část toku přihlašování, kde nedostatek souborů cookie třetích stran nemá vliv na vaši aplikaci. Toto omezení znamená, že byste ho měli používat výhradně jako součást hybridního toku, kde vaše aplikace požaduje kód a token z autorizačního koncového bodu. V hybridním toku obdrží vaše aplikace kód, který je možné uplatnit pro obnovovací token, a tím zajistí, aby přihlašovací relace vaší aplikace zůstala v čase platná.
Diagram protokolu
Následující diagram znázorňuje, jak vypadá celý implicitní tok přihlašování, a následující části popisují jednotlivé kroky podrobně.
Odeslání žádosti o přihlášení
Pokud chcete uživatele nejdřív přihlásit k aplikaci, můžete odeslat žádost o ověření OpenID Připojení a získat z id_token platformy Microsoft Identity Platform.
Důležité
Pokud chcete úspěšně požádat o token ID nebo přístupový token, registrace aplikace v Centru pro správu Microsoft Entra – Registrace aplikací stránka musí mít povolený odpovídající implicitní tok udělení, a to výběrem tokenů ID a přístupových tokenů v části Implicitní udělení a hybridní toky. Pokud 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=00001111-aaaa-2222-bbbb-3333cccc4444
&response_type=id_token
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&scope=openid
&response_mode=fragment
&state=12345
&nonce=678910
| Parametr | Typ | Popis |
|---|---|---|
tenant |
povinné | {tenant} Hodnotu v cestě požadavku můžete použít k řízení, kdo se může přihlásit k aplikaci. Povolené hodnoty jsou common, organizations, consumersa identifikátory tenanta. Další podrobnosti najdete v základech protokolu. Pro scénáře hosta, ve kterých podepíšete uživatele z jednoho tenanta do jiného tenanta, musíte zadat identifikátor tenanta, aby se správně přihlásil k tenantovi prostředku. |
client_id |
povinné | ID aplikace (klienta), které centrum pro správu Microsoft Entra – Registrace aplikací stránku přiřazenou k vaší aplikaci. |
response_type |
povinné | Musí obsahovat id_token openID Připojení přihlášení. Může obsahovat response_typetaké , . token Použití token zde umožní vaší aplikaci okamžitě získat přístupový token z autorizovaného koncového bodu, aniž by musela provést druhý požadavek na autorizaci koncového bodu. Pokud použijete token response_type, musí parametr obsahovat obor označující scope , pro který prostředek se má token vydat (například user.read v Microsoft Graphu). Může také obsahovat code místo zadání autorizačního token kódu pro použití v toku autorizačního kódu. Tato id_token+code odpověď se někdy označuje jako hybridní tok. |
redirect_uri |
Doporučené | Identifikátor URI přesměrování vaší aplikace, kde můžou aplikace odesílat a přijímat odpovědi na ověřování. Musí přesně odpovídat jednomu z identifikátorů URI přesměrování, které jste zaregistrovali na portálu, s výjimkou adresy URL zakódované. |
scope |
povinné | Seznam oborů oddělených mezerami. U openID Připojení (id_tokens) musí obsahovat oboropenid, který se v uživatelském rozhraní pro vyjádření souhlasu přeloží na oprávnění Přihlásit se. Volitelně můžete také chtít zahrnout rozsahy email a profile získat přístup k dalším uživatelským datům. V této žádosti můžete zahrnout i další obory pro vyžádání souhlasu s různými prostředky, pokud se požaduje přístupový token. |
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, 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. Náhodně vygenerovaná jedinečná hodnota se obvykle používá k zabránění útokům typu útok typu negery mezi 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 žádosti o ověření, jako je stránka nebo zobrazení, na které byli. |
nonce |
povinné | Hodnota zahrnutá v požadavku vygenerovaná aplikací, která bude zahrnuta do výsledného tokenu ID jako deklarace identity. Aplikace pak může tuto hodnotu ověřit, aby se omezily útoky na přehrání tokenu. Hodnota je obvykle randomizovaný, jedinečný řetězec, který lze použít k identifikaci původu požadavku. Vyžaduje se pouze v případě, že se požaduje id_token. |
prompt |
optional | Určuje typ interakce uživatele, který je povinný. Jediné platné hodnoty v tuto chvíli jsou login, none, select_accounta consent. prompt=login vynutí, aby uživatel zadal své přihlašovací údaje k této žádosti a neguje jednotné přihlašování. prompt=none je opačná – zajistí, aby uživatel nebyl vůbec prezentován s žádnou interaktivní výzvou. Pokud požadavek nejde dokončit bezobslužně prostřednictvím jednotného přihlašování, platforma Microsoft Identity Platform vrátí chybu. prompt=select_account odešle uživatele do nástroje pro výběr účtu, kde se zobrazí všechny účty, které se zapamatují v relaci. prompt=consent aktivuje dialogové okno souhlasu OAuth po přihlášení uživatele a požádá uživatele, aby udělil oprávnění aplikaci. |
login_hint |
optional | Tento parametr můžete použít k předběžnému vyplnění pole uživatelské jméno a e-mailová adresa přihlašovací stránky pro uživatele, pokud uživatelské jméno znáte předem. Aplikace tento parametr často používají během opětovného ověření po extrahování login_hintvolitelné deklarace identity z dřívějšího přihlášení. |
domain_hint |
optional | Pokud je součástí, 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é pracují v jednom tenantovi, kde zadají název domény v rámci daného tenanta a předají uživatele federačnímu poskytovateli daného tenanta. 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í výzva k zadání přihlašovacích údajů a dokončení ověřování. Platforma Microsoft Identity Platform také zajistí, aby uživatel souhlasil s oprávněními uvedenými v parametru scope dotazu. Pokud uživatel souhlasil s žádným z těchto oprávnění, vyzve uživatele, aby udělil souhlas s požadovanými oprávněními. Další informace najdete v tématu oprávnění, souhlas a aplikace s více tenanty.
Jakmile se uživatel ověří a udělí souhlas, platforma Microsoft Identity Platform vrátí odpověď na vaši aplikaci na uvedeném redirect_urimístě pomocí metody zadané v parametru response_mode .
Úspěšná odpověď
Úspěšná odpověď, která se používá response_mode=fragment a response_type=id_token+code vypadá takto (s koncem řádků kvůli čitelnosti):
GET https://localhost/myapp/#
code=0.AgAAktYV-sfpYESnQynylW_UKZmH-C9y_G1A
&id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...
&state=12345
| Parametr | Popis |
|---|---|
code |
Zahrnuté v případě response_type zahrnutí code. Jedná se o autorizační kód vhodný pro použití v toku autorizačního kódu. |
access_token |
Zahrnuté v případě response_type zahrnutí token. Přístupový token, který aplikace požadovala. Přístupový token by neměl být dekódován nebo jinak zkontrolován, měl by se považovat za neprůzný řetězec. |
token_type |
Zahrnuté v případě response_type zahrnutí token. To bude vždy Bearer. |
expires_in |
Zahrnuté v případě response_type zahrnutí token. Označuje počet sekund, po které je token platný pro účely ukládání do mezipaměti. |
scope |
Zahrnuté v případě response_type zahrnutí token. Určuje rozsahy, pro které budou access_token platné. Nesmí obsahovat všechny požadované obory, pokud nejsou použitelné pro uživatele. Například obory Microsoft Entra-only požadované při přihlašování pomocí osobního účtu. |
id_token |
Podepsaný webový token JSON (JWT). Aplikace může dekódovat segmenty tohoto tokenu a požádat o informace o uživateli, který se přihlásil. Aplikace může hodnoty ukládat do mezipaměti a zobrazovat je, ale nemělo by se na ně spoléhat na žádnou autorizaci ani hranice zabezpečení. Další informace otokench id_token reference Poznámka: Pouze pokud openid byl rozsah požadován a response_type zahrnut id_tokens. |
state |
Pokud je v požadavku zahrnutý parametr stavu, měla by se v odpovědi zobrazit stejná hodnota. Aplikace by měla ověřit, že hodnoty stavu v požadavku a odpovědi jsou identické. |
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.
Chybná odpověď
Chybové odpovědi se můžou také odeslat do redirect_uri aplikace, aby je mohla správně 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 dochází, a lze jej použít k reakci na chyby. |
error_description |
Konkrétní chybová zpráva, která může vývojáři pomoct identifikovat původní příčinu chyby ověřování. |
Bezobslužné získání přístupových tokenů
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 v prohlížečích založených na Chromiu, které nejsou v anonymním režimu, měli by vývojáři zvážit použití této části toku. V prohlížečích, které nepodporují soubory cookie třetích stran, se zobrazí chyba oznamující, že nejsou přihlášení žádní uživatelé, protože prohlížeč odebral soubory cookie relace přihlašovací stránky.
Teď, když jste uživatele podepsali do jednostráňové aplikace, můžete bezobslužně získat přístupové tokeny pro volání webových rozhraní API zabezpečených platformou Microsoft Identity Platform, jako je Microsoft Graph. I když jste už obdrželi token pomocí token response_type, můžete pomocí této metody získat tokeny k dalším prostředkům bez přesměrování uživatele, aby se znovu přihlásil.
V normálním toku OpenID Připojení/OAuth byste to udělali provedením požadavku na koncový bod Microsoft Identity Platform/token. Požadavek můžete vytvořit ve skrytém prvku iframe, abyste získali nové tokeny pro jiná webová rozhraní API:
// Line breaks for legibility only
https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444&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 žádosti o přihlášení.
Tip
Zkuste zkopírovat a vložit níže uvedený požadavek na kartu prohlížeče. (Nezapomeňte nahradit login_hint hodnoty správnou hodnotou pro uživatele.
https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id=535fb089-9ff3-47b6-9bfb-4f1264799865&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}
Mějte na paměti, ž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 prompt=none bude tento požadavek úspěšný nebo neúspěšný okamžitě a vrátí se do vaší aplikace. Odpověď se odešle do vaší aplikace na uvedeném místě redirect_uripomocí metody zadané v parametru response_mode .
Úspěšná odpověď
Úspěšná odpověď vypadá response_mode=fragment takto:
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 |
Zahrnuté v případě response_type zahrnutí token. Přístupový token, který aplikace požadovala, v tomto případě pro Microsoft Graph. Přístupový token by neměl být dekódován nebo jinak zkontrolován, měl by se považovat za neprůzný řetězec. |
token_type |
To bude vždy Bearer. |
expires_in |
Označuje počet sekund, po které je token platný pro účely ukládání do mezipaměti. |
scope |
Označuje obory, pro které bude přístupový token platný. Nesmí obsahovat všechny požadované obory, pokud nebyly použitelné pro uživatele (v případě, že se požaduje pouze obory Microsoft Entra, pokud se k přihlášení používá osobní účet). |
id_token |
Podepsaný webový token JSON (JWT). Zahrnuté v případě response_type zahrnutí id_token. Aplikace může dekódovat segmenty tohoto tokenu a požádat o informace o uživateli, který se přihlásil. Aplikace může hodnoty ukládat do mezipaměti a zobrazovat je, ale nemělo by se na ně spoléhat na žádnou autorizaci ani hranice zabezpečení. Další informace o id_tokens najdete v referenčních informacíchid_token. Poznámka: Poskytuje se pouze v případě, že openid byl požadován rozsah. |
state |
Pokud je v požadavku zahrnutý parametr stavu, měla by se v odpovědi zobrazit stejná hodnota. Aplikace by měla ověřit, že hodnoty stavu v požadavku a odpovědi jsou identické. |
Chybná odpověď
Chybové odpovědi se můžou také odeslat do redirect_uri aplikace, aby je mohla správně zpracovat. V případě prompt=none, že očekávaná chyba bude:
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 dochází, a lze jej použít k reakci na chyby. |
error_description |
Konkrétní chybová zpráva, která může vývojáři pomoct identifikovat původní příčinu chyby ověřování. |
Pokud se tato chyba zobrazí v požadavku iframe, musí se uživatel interaktivně přihlásit, aby načetl nový token. Tento případ můžete zpracovat jakýmkoli způsobem, který dává smysl pro vaši aplikaci.
Aktualizace tokenů
Implicitní udělení neposkytuje obnovovací tokeny. Platnost tokenů ID i přístupových tokenů vyprší po krátké době, takže vaše aplikace musí být připravená pravidelně aktualizovat tyto tokeny. Pokud chcete aktualizovat některý typ tokenu, můžete pomocí parametru prompt=none provést stejný skrytý požadavek prvku iframe, který řídí chování platformy identity. Pokud chcete získat nový token ID, nezapomeňte použít id_token v sadě response_type a scope=openida také nonce parametr.
V prohlížečích, které nepodporují soubory cookie třetích stran, to způsobí chybu, která značí, že není přihlášený žádný uživatel.
Odeslání žádosti o odhlášení
OpenID Připojení end_session_endpoint umožňuje vaší aplikaci odeslat žádost na platformu Microsoft Identity Platform, aby ukončila relaci uživatele a vymaže soubory cookie nastavené platformou Microsoft Identity Platform. K úplnému odhlášení uživatele z webové aplikace by vaše aplikace měla ukončit vlastní relaci s uživatelem (obvykle vymazáním mezipaměti tokenů nebo vyřazením souborů cookie) a pak prohlížeč přesměrovat na:
https://login.microsoftonline.com/{tenant}/oauth2/v2.0/logout?post_logout_redirect_uri=https://localhost/myapp/
Další kroky
- Projděte si ukázky MSAL JS a začněte psát kód.
- Projděte si tok autorizačního kódu jako novější, lepší alternativu k implicitní udělení.