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 toho použít podporované knihovny MICROSOFT Authentication Library (MSAL) k získání tokenů a volání zabezpečených webových rozhraní API. Seznam ukázek kódu, které používají MSAL, najdete v ukázkách kódu platformy Microsoft Identity Platform.
Varování
Microsoft doporučuje nepoužívat implicitní tok udělení. Ve většině scénářů jsou k dispozici a doporučeny bezpečnější alternativy. Některé konfigurace tohoto toku vyžadují velmi vysoký stupeň důvěryhodnosti v aplikaci a nesou rizika, která nejsou přítomna v jiných tocích. Tento tok byste měli použít jenom v případě, že jiné bezpečnější toky nejsou přijatelné. Další informace najdete v tématech zabezpečení s implicitními toky udělení.
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ě.
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á.
Preferujte tok ověřovacího kódu
U některých prohlížečů , které odstraňují podporu souborů cookie třetích stran, už není implicitní tok udělení vhodný metodou ověřování. Funkce tiché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.
Aspekty zabezpečení s implicitními toky udělení
Implicitní tok udělení je určený pro tradiční webové aplikace, kde má server kontrolu nad bezpečným zpracováním dat POST. Existují dva hlavní způsoby doručování tokenů pomocí implicitního toku udělení: kde response_mode se vrátí jako fragment adresy URL nebo jako parametr dotazu (pomocí form POST a GET ). V implicitní toku, kde response_mode=form_postse token bezpečně doručí prostřednictvím html formuláře POST do identifikátoru URI přesměrování klienta. Tato metoda zajišťuje, že token není vystavený v fragmentu adresy URL, což zase zabraňuje rizikům úniku tokenů prostřednictvím historie prohlížeče nebo hlaviček referrerů.
Pokud se tokeny doručují pomocí response_mode=fragment, dojde k obavám zabezpečení s implicitními toky . Fragment adresy URL je součástí adresy URL, která přichází za # symbolem a není odeslána na server, když prohlížeč požádá o novou stránku, ale je k dispozici pro JavaScript spuštěný v prohlížeči. To znamená, že token je vystavený libovolnému JavaScriptu běžícímu na stránce, což může být bezpečnostní riziko, pokud stránka obsahuje skripty třetích stran. Tyto obavy zabezpečení pro tokeny v spA se také nevztahují na implicitní tok s form POST.
Kdy byste měli povolit vydání přístupového tokenu nebo tokenu ID při vyžádání pomocí implicitního udělení nebo hybridního toku?
Implicitní udělení a hybridní tok nejsou tak zabezpečené jako ostatní toky OAuth. Pokud to není nezbytně nutné, neměli byste povolit vydání přístupového tokenu nebo tokenu ID při vyžádání pomocí implicitního udělení nebo hybridního toku v registraci aplikace. Pokud vy (nebo vaši vývojáři) k implementaci ověřování a autorizace používáte knihovnu MSAL ve vaší aplikaci, není nutné povolit žádné pole.
Pokud ale vy (nebo vaši vývojáři) ve vaší aplikaci nepoužíváte knihovnu MSAL, následující tabulka popisuje, kdy by se měly povolit přístupové tokeny nebo token ID.
| Typ aplikace, kterou vytváříte | Tokeny, které byste měli povolit v registraci aplikace |
|---|---|
| Spa (jednostránkové aplikace), která nepoužívá tok autorizačního kódu s PKCE | Přístupové tokeny a tokeny ID |
| Webová aplikace nebo aplikace SPA, která volá webové rozhraní API přes JavaScript pomocí implicitního toku | Přístupové tokeny a tokeny ID |
| Webová aplikace ASP.NET Core a další webové aplikace, které používají hybridní ověřování | Tokeny ID |
Odeslání žádosti o přihlášení
Pokud chcete uživatele nejprve přihlásit k aplikaci, můžete odeslat žádost o ověření OpenID Connect 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 |
požadovaný | {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 |
požadovaný | ID aplikace (klienta), které centrum pro správu Microsoft Entra – Registrace aplikací stránku přiřazenou k vaší aplikaci. |
response_type |
požadovaný | Musí obsahovat id_token přihlášení openID Connect. Může obsahovat response_typetaké , . token Použití token zde umožňuje aplikaci okamžitě přijímat přístupový token z koncového bodu /authorize, aniž by musela provést druhý požadavek na koncový bod /authorize. 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 se odpovědi na ověřování odesílají a přijímají ve vaší aplikaci. Musí přesně odpovídat jednomu z identifikátorů URI přesměrování, které jste zaregistrovali v Centru pro správu Microsoft Entra, s výjimkou adresy URL zakódované. |
scope |
požadovaný | Seznam oborů oddělených mezerami. Pro OpenID Connect (id_tokens) musí obsahovat obor openid, 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 |
doporučený | Určuje metodu, která se má použít k odeslání výsledného tokenu zpět do vaší aplikace. Výchozí hodnota je query pouze pro přístupový token, ale fragment pokud požadavek obsahuje id_token. Zbezpečnostních form_post |
state |
doporučený | V odpovědi tokenu se také vrátí hodnota zahrnutá v požadavku. 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 |
požadovaný | Hodnota zahrnutá v požadavku vygenerovaná aplikací, která je součástí 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 |
volitelný | 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 naopak – zajišťuje, aby uživatel nebyl zobrazen s žádnou interaktivní výzvou vůbec. Pokud požadavek nejde dokončit bezobslužně přes jednotné přihlašování, vrátí platforma Microsoft Identity Platform chybu. prompt=select_account odešle uživatele do nástroje pro výběr účtu, kde se všechny účty zapamatovaly 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 |
volitelný | 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_hint volitelné deklarace identity z dřívějšího přihlášení. |
domain_hint |
volitelný | V případě 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 efektivnější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 daném tenantovi a předávají 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žívání 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 zajišťuje, 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í, požádá 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 víceklientských aplikací.
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 je 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. Označuje jeden nebo více oborů, pro které access_token je 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é. |
Varová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.
Chybová 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ů
Teď, když je váš uživatel přihlášený k jednostráňové aplikaci, 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.
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.
V normálním toku OpenID Connect/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í.
Spropitné
Zkuste zkopírovat a vložit následující požadavek na kartu prohlížeče pomocí skutečné client_id a username z registrace aplikace. To vám umožní zobrazit žádost o bezobslužný token v akci.
https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id={your-client-id}&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={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 tento požadavek buď proběhne úspěšně, nebo se okamžitě nezdaří 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 je 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 jeden nebo více oborů, pro které je přístupový token platný. Nesmí obsahovat všechny požadované obory, pokud nebyly použitelné pro uživatele (pokud 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é. |
Chybová odpověď
Chybové odpovědi se můžou také odeslat do redirect_uri aplikace, aby je mohla správně zpracovat. Pokud prompt=nonese jedná o očekávanou chybu:
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 řídit chování platformy Identity Platform stejným způsobem jako dříve popsaný požadavek iframe. Pokud chcete získat nový token ID, nezapomeňte ho response_type scope=openidpoužít id_token v a a parametrunonce.
V prohlížečích, které nepodporují soubory cookie třetích stran, dojde k chybě, která značí, že není přihlášený žádný uživatel.
Odeslání žádosti o odhlášení
OpenID Connect 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/
Viz také
- 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í.