Autorizace přístupu k webovým aplikacím s použitím OpenID Connect a Azure Active Directory
Upozornění
Tento obsah je určený pro starší koncový bod Azure AD verze 1.0. Pro nové projekty použijte Microsoft identity platform.
OpenID Connect je jednoduchá vrstva identity založená na protokolu OAuth 2.0. OAuth 2.0 definuje mechanismy pro získání a použití přístupových tokenů pro přístup k chráněným prostředkům, ale nedefinují standardní metody pro poskytování informací o identitě. OpenID Connect implementuje ověřování jako rozšíření procesu autorizace OAuth 2.0. Poskytuje informace o koncovém uživateli ve formě objektu id_token , který ověřuje identitu uživatele a poskytuje základní profilové informace o uživateli.
OpenID Connect je naše doporučení, pokud vytváříte webovou aplikaci, která je hostovaná na serveru a přistupuje se k němu přes prohlížeč.
Registrace aplikace pomocí tenanta AD
Nejprve zaregistrujte aplikaci v tenantovi Azure Active Directory (Azure AD). Pro svou aplikaci tak získáte ID a umožníte jí přijímat tokeny.
Přihlaste se k webu Azure Portal.
Vyberte svého Azure AD tenanta tak, že v pravém horním rohu stránky vyberete svůj účet, pak vyberete navigaci Přepnout adresář a pak vyberete příslušného tenanta.
- Tento krok přeskočte, pokud máte pod svým účtem jenom jednoho tenanta Azure AD nebo pokud jste už vybrali odpovídajícího tenanta Azure AD.
V Azure Portal vyhledejte a vyberte Azure Active Directory.
V levé nabídce Azure Active Directory vyberte Registrace aplikací a pak vyberte Nová registrace.
Postupujte podle zobrazených pokynů a vytvořte novou aplikaci. Nezáleží na tom, jestli se jedná o webovou aplikaci nebo veřejnou klientskou aplikaci (mobilní & desktopovou), ale pokud chcete konkrétní příklady pro webové aplikace nebo veřejné klientské aplikace, podívejte se na naše rychlé starty.
- Název je název aplikace, který aplikaci popisuje koncovým uživatelům.
- V části Podporované typy účtů vyberte Účty v libovolném adresáři organizace a osobní účty Microsoft.
- Zadejte identifikátor URI pro přesměrování. U webových aplikací se jedná o základní adresu URL vaší aplikace, kam se uživatelé můžou přihlásit. Například,
http://localhost:12345. U veřejného klienta (mobilní & desktop) ho Azure AD používá k vrácení odpovědí na tokeny. Zadejte hodnotu specifickou pro vaši aplikaci. Například,http://MyFirstAADApp.
Po dokončení registrace přiřadí Azure AD vaší aplikaci jedinečný identifikátor klienta (ID aplikace). Tuto hodnotu potřebujete v dalších částech, proto ji zkopírujte ze stránky aplikace.
Pokud chcete najít aplikaci v Azure Portal, vyberte Registrace aplikací a pak vyberte Zobrazit všechny aplikace.
Tok ověřování pomocí OpenID Connect
Nejzákladnější tok přihlášení obsahuje následující kroky – každý z nich je podrobně popsaný níže.
Dokument metadat OpenID Connect
OpenID Connect popisuje dokument metadat, který obsahuje většinu informací potřebných k přihlášení aplikace. Patří sem informace, jako jsou adresy URL, které se mají použít, a umístění veřejných podpisových klíčů služby. Dokument metadat OpenID Connect najdete tady:
https://login.microsoftonline.com/{tenant}/.well-known/openid-configuration
Metadata jsou jednoduchý dokument JSON (JavaScript Object Notation). Příklad najdete v následujícím fragmentu kódu. Obsah fragmentu kódu je plně popsaný ve specifikaci OpenID Connect. Všimněte si, že poskytnutí ID tenanta místo common výše uvedeného typu {tenant} způsobí, že se vrátí identifikátory URI specifické pro tenanta v objektu JSON.
{
"authorization_endpoint": "https://login.microsoftonline.com/{tenant}/oauth2/authorize",
"token_endpoint": "https://login.microsoftonline.com/{tenant}/oauth2/token",
"token_endpoint_auth_methods_supported":
[
"client_secret_post",
"private_key_jwt",
"client_secret_basic"
],
"jwks_uri": "https://login.microsoftonline.com/common/discovery/keys"
"userinfo_endpoint":"https://login.microsoftonline.com/{tenant}/openid/userinfo",
...
}
Pokud má vaše aplikace vlastní podpisové klíče v důsledku použití funkce mapování deklarací identity , musíte připojit appid parametr dotazu obsahující ID aplikace, abyste získali jwks_uri odkazování na informace o podpisovém klíči vaší aplikace. Příklad: https://login.microsoftonline.com/{tenant}/.well-known/openid-configuration?appid=6731de76-14a6-49ae-97bc-6eba6914391e obsahuje hodnotu jwks_urihttps://login.microsoftonline.com/{tenant}/discovery/keys?appid=6731de76-14a6-49ae-97bc-6eba6914391e.
Odeslání žádosti o přihlášení
Když webová aplikace potřebuje uživatele ověřit, musí ho nasměrovat na /authorize koncový bod. Tento požadavek se podobá první části toku autorizačního kódu OAuth 2.0 s několika důležitými rozdíly:
- Požadavek musí v parametru obsahovat obor
openidscope. - Parametr
response_typemusí obsahovatid_token. - Požadavek musí obsahovat
nonceparametr .
Ukázková žádost by tedy vypadala takto:
// Line breaks for legibility only
GET https://login.microsoftonline.com/{tenant}/oauth2/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&response_type=id_token
&redirect_uri=http%3A%2F%2Flocalhost%3a12345
&response_mode=form_post
&scope=openid
&state=12345
&nonce=7362CAEA-9CA5-4B43-9BA3-34D7C303EBA7
| Parametr | Typ | Description |
|---|---|---|
| Nájemce | vyžadováno | Hodnota {tenant} v cestě požadavku se dá použít k řízení, kdo se může k aplikaci přihlásit. Povolené hodnoty jsou například 8eaef023-2b34-4da1-9baa-8bc8c9d6a490 identifikátory tenanta nebo contoso.onmicrosoft.comcommon nebo pro tokeny nezávislé na tenantovi. |
| client_id | vyžadováno | ID aplikace přiřazené vaší aplikaci, když jste ji zaregistrovali u Azure AD. Najdete ho v Azure Portal. Klikněte na Azure Active Directory, klikněte na Registrace aplikací, zvolte aplikaci a na stránce aplikace vyhledejte ID aplikace. |
| response_type | vyžadováno | Musí obsahovat id_token přihlášení OpenID Connect. Může také obsahovat další response_types, například code nebo token. |
| scope | Doporučené | Specifikace OpenID Connect vyžaduje obor openid, který se v uživatelském rozhraní pro vyjádření souhlasu překládá na oprávnění Přihlásit se. Tento a další obory OIDC se v koncovém bodu verze 1.0 ignorují, ale stále se jedná o osvědčený postup pro klienty kompatibilní se standardy. |
| Nonce | vyžadováno | Hodnota zahrnutá v požadavku vygenerovaná aplikací, která je zahrnutá ve výsledném id_token požadavku jako deklarace identity. Aplikace pak může tuto hodnotu ověřit, aby zmírnila útoky na přehrání tokenů. Hodnota je obvykle náhodný jedinečný řetězec nebo IDENTIFIKÁTOR GUID, který lze použít k identifikaci původu požadavku. |
| redirect_uri | Doporučené | Redirect_uri vaší aplikace, kde může aplikace odesílat a přijímat odpovědi na ověřování. Musí přesně odpovídat některému z redirect_uris, které jste zaregistrovali na portálu, s výjimkou toho, že musí být zakódovaná adresa URL. Pokud uživatelský agent chybí, náhodně se odešle zpět do některého z identifikátorů URI pro přesměrování zaregistrovaných pro aplikaci. Maximální délka je 255 bajtů. |
| response_mode | optional | Určuje metodu, která se má použít k odeslání výsledné authorization_code zpět do aplikace. Podporované hodnoty jsou form_post pro post formuláře HTTP a fragment pro fragment adresy URL. U webových aplikací doporučujeme zajistit response_mode=form_post nejbezpečnější přenos tokenů do vaší aplikace. Výchozí hodnota pro jakýkoli tok, včetně id_token, je fragment. |
| state | Doporučené | Hodnota zahrnutá v požadavku, která je vrácena 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 na padělání požadavků mezi weby. Stav se také používá ke kódování informací o stavu uživatele v aplikaci před provedením žádosti o ověření, jako je stránka nebo zobrazení, na které se uživatel nacházel. |
| Výzva | optional | Označuje typ požadované interakce uživatele. V současné době jsou platné pouze hodnoty "login", "none" a "consent".
prompt=login vynutí, aby uživatel zadal své přihlašovací údaje pro tento požadavek a neguje jednotné přihlašování.
prompt=none je pravý opak – zajišťuje, že se uživateli nezobrazí žádná interaktivní výzva. Pokud požadavek nejde dokončit bez upozornění prostřednictvím jednotného přihlašování, koncový bod vrátí chybu.
prompt=consent aktivuje dialogové okno souhlasu OAuth po přihlášení uživatele a požádá ho, aby aplikaci udělil oprávnění. |
| login_hint | optional | Dá se použít k předvyplnění pole uživatelského jména nebo e-mailové adresy na přihlašovací stránce uživatele, pokud jeho uživatelské jméno znáte předem. Aplikace často používají tento parametr při opětovném ověřování, protože už pomocí deklarace identity extraholy uživatelské jméno z předchozího přihlášení preferred_username . |
V tomto okamžiku se uživateli zobrazí výzva k zadání přihlašovacích údajů a dokončení ověřování.
Ukázková odpověď
Ukázková odpověď odeslaná uživateli redirect_uri zadanému v žádosti o přihlášení po ověření uživatele může vypadat takto:
POST / HTTP/1.1
Host: localhost:12345
Content-Type: application/x-www-form-urlencoded
id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNB...&state=12345
| Parametr | Popis |
|---|---|
| id_token | Hodnota id_token , kterou aplikace požadovala. Můžete použít id_token k ověření identity uživatele a zahájení relace s uživatelem. |
| state | Hodnota zahrnutá v požadavku, která je také vrácena v odpovědi tokenu. Náhodně vygenerovaná jedinečná hodnota se obvykle používá k prevenci útoků padělání požadavků napříč weby. Stav se používá také ke kódování informací o stavu uživatele v aplikaci před provedením požadavku na ověření, jako je stránka nebo zobrazení, na které se uživatel nacházel. |
Chybová odpověď
Chybové odpovědi mohou být také odeslány do redirect_uri aplikace, aby je aplikace správně zpracovávala:
POST / HTTP/1.1
Host: localhost:12345
Content-Type: application/x-www-form-urlencoded
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 který lze 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í. |
Kódy chyb pro chyby koncového bodu autorizace
Následující tabulka popisuje různé kódy chyb, které mohou být vráceny error v parametru chybové odpovědi.
| Kód chyby | Description | Akce klienta |
|---|---|---|
| invalid_request | Chyba protokolu, například chybějící požadovaný parametr. | Opravte požadavek a odešlete ho znovu. Jedná se o chybu při vývoji, která se obvykle zachytí během počátečního testování. |
| unauthorized_client | Klientská aplikace nemá oprávnění požadovat autorizační kód. | K tomu obvykle dochází v případě, že klientská aplikace není zaregistrovaná v Azure AD nebo není přidána do Azure AD tenanta uživatele. Aplikace může uživatele vyzvat k instalaci aplikace a jejímu přidání do Azure AD. |
| access_denied | Vlastník prostředku zamítl souhlas | Klientská aplikace může uživatele upozornit, že nemůže pokračovat, pokud uživatel nevyhovuje. |
| unsupported_response_type | Autorizační server nepodporuje typ odpovědi v požadavku. | Opravte požadavek a odešlete ho znovu. Jedná se o chybu při vývoji, která se obvykle zachytí během počátečního testování. |
| server_error | Na serveru došlo k neočekávané chybě. | Zkuste požadavek zopakovat. Tyto chyby můžou být důsledkem dočasných podmínek. Klientská aplikace může uživateli vysvětlit, že její odpověď je zpožděná kvůli dočasné chybě. |
| temporarily_unavailable | Server je dočasně příliš zaneprázdněn, aby požadavek vyřídil. | Zkuste požadavek zopakovat. Klientská aplikace může uživateli vysvětlit, že její odpověď je zpožděná kvůli dočasnému stavu. |
| invalid_resource | Cílový prostředek je neplatný, protože neexistuje, Azure AD ho nemůže najít nebo není správně nakonfigurovaný. | To znamená, že prostředek, pokud existuje, nebyl v tenantovi nakonfigurovaný. Aplikace může uživatele vyzvat k instalaci aplikace a jejímu přidání do Azure AD. |
Ověření id_token
Pouhé přijetí id_token příkazu nestačí k ověření uživatele. Musíte ověřit podpis a deklarace identity podle id_token požadavků vaší aplikace. Koncový bod Azure AD používá k podepisování tokenů a ověření jejich platnosti webové tokeny JSON (JWT) a kryptografii s veřejnými klíči.
Můžete se rozhodnout ověřit v klientském id_token kódu, ale běžným postupem je odeslání id_token na back-endový server a provedení ověření tam.
V závislosti na vašem scénáři můžete také chtít ověřit další deklarace identity. Mezi běžná ověření patří:
- Ujistěte se, že se uživatel nebo organizace zaregistrovali k aplikaci.
- Ujistěte se, že uživatel má správnou autorizaci nebo oprávnění pomocí
widsdeklarací identity neboroles. - Zajištění určité síly ověřování, jako je například vícefaktorové ověřování.
Jakmile ověříte id_token, můžete zahájit relaci s uživatelem a pomocí deklarací identity v objektu id_token získat informace o uživateli ve vaší aplikaci. Tyto informace lze použít k zobrazení, záznamům, přizpůsobení atd. Další informace o id_tokens deklarací identity a najdete v tématu id_tokens AAD.
Odeslání žádosti o odhlášení
Pokud chcete odhlásit uživatele z aplikace, nestačí vymazat soubory cookie aplikace nebo jinak ukončit relaci s uživatelem. Uživatele musíte také přesměrovat na pro end_session_endpoint odhlášení. Pokud se vám to nepodaří, uživatel se bude moct znovu přihlásit k vaší aplikaci, aniž by musel znovu zadat svoje přihlašovací údaje, protože bude mít platnou relaci jednotného přihlašování s koncovým bodem Azure AD.
Uživatele můžete jednoduše přesměrovat na end_session_endpoint seznam uvedený v dokumentu metadat OpenID Connect:
GET https://login.microsoftonline.com/common/oauth2/logout?
post_logout_redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
| Parametr | Typ | Description |
|---|---|---|
| post_logout_redirect_uri | Doporučené | Adresa URL, na kterou by měl být uživatel přesměrován po úspěšném odhlášení. Tato adresa URL se musí shodovat s jedním z identifikátorů URI přesměrování zaregistrovaných pro vaši aplikaci na portálu pro registraci aplikací. Pokud post_logout_redirect_uri neobsahuje, zobrazí se uživateli obecná zpráva. |
Jednotné odhlašování
Když přesměrujete uživatele na end_session_endpoint, Azure AD vymaže relaci uživatele z prohlížeče. Uživatel ale může být stále přihlášený k jiným aplikacím, které k ověřování používají Azure AD. Pokud chcete těmto aplikacím umožnit současné odhlášení uživatele, odešle Azure AD požadavek HTTP GET všem zaregistrovaným LogoutUrl aplikacím, ke kterým je uživatel aktuálně přihlášený. Aplikace musí na tento požadavek reagovat vymazáním všech relací, které uživatele identifikují, a vrácením 200 odpovědi. Pokud chcete ve své aplikaci podporovat jednotné odhlášení, musíte ho LogoutUrl implementovat do kódu aplikace. Můžete nastavit hodnotu LogoutUrl z Azure Portal:
- Přihlaste se k webu Azure Portal.
- Zvolte službu Active Directory kliknutím na svůj účet v pravém horním rohu stránky.
- V levém navigačním panelu zvolte Azure Active Directory, pak zvolte Registrace aplikací a vyberte svou aplikaci.
- Klikněte na Nastavení, potom na Vlastnosti a najděte textové pole Adresa URL pro odhlášení .
Získání tokenu
Mnoho webových aplikací musí nejen přihlásit uživatele, ale také přistupovat k webové službě jménem tohoto uživatele pomocí OAuth. Tento scénář kombinuje OpenID Connect pro ověřování uživatelů a současně získává metodu authorization_code , která se dá použít k access_tokens použití toku autorizačního kódu OAuth.
Získání přístupových tokenů
Pokud chcete získat přístupové tokeny, musíte výše uvedenou žádost o přihlášení upravit:
// Line breaks for legibility only
GET https://login.microsoftonline.com/{tenant}/oauth2/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e // Your registered Application ID
&response_type=id_token+code
&redirect_uri=http%3A%2F%2Flocalhost%3a12345 // Your registered Redirect Uri, url encoded
&response_mode=form_post // `form_post' or 'fragment'
&scope=openid
&resource=https%3A%2F%2Fservice.contoso.com%2F // The identifier of the protected resource (web API) that your application needs access to
&state=12345 // Any value, provided by your app
&nonce=678910 // Any value, provided by your app
Zahrnutím oborů oprávnění do požadavku a použitím response_type=code+id_tokenauthorize příkazu zajistí koncový bod, že uživatel udělil souhlas s oprávněními ovanými v parametru scope dotazu, a vrátí aplikaci autorizační kód pro výměnu za přístupový token.
Úspěšná odpověď
Úspěšná odpověď odeslaná pomocí redirect_uri vypadá response_mode=form_posttakto:
POST /myapp/ HTTP/1.1
Host: localhost
Content-Type: application/x-www-form-urlencoded
id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNB...&code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...&state=12345
| Parametr | Popis |
|---|---|
| id_token | Hodnota id_token , kterou aplikace požadovala. Můžete použít id_token k ověření identity uživatele a zahájení relace s uživatelem. |
| kód | Authorization_code, kterou aplikace požadovala. Aplikace může pomocí autorizačního kódu požádat o přístupový token pro cílový prostředek. Authorization_codes jsou krátkodobé a jejich platnost obvykle vyprší přibližně po 10 minutách. |
| 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, jestli jsou hodnoty stavu v požadavku a odpovědi identické. |
Chybová odpověď
Chybové odpovědi mohou být také odeslány do redirect_uri aplikace, aby je aplikace správně zpracovávala:
POST /myapp/ HTTP/1.1
Host: localhost
Content-Type: application/x-www-form-urlencoded
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 který lze 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í. |
Popis možných kódů chyb a jejich doporučené akce klienta najdete v tématu Kódy chyb pro chyby koncového bodu autorizace.
Jakmile získáte autorizaci code a id_token, můžete uživatele přihlásit a získat jeho jménem přístupové tokeny . Pokud chcete uživatele přihlásit, musíte ověřit id_token přesně tak, jak je popsáno výše. Pokud chcete získat přístupové tokeny, můžete postupovat podle kroků popsaných v části "Použití autorizačního kódu k vyžádání přístupového tokenu" v naší dokumentaci k toku kódu OAuth.
Další kroky
- Přečtěte si další informace o přístupových tokenech.
- Přečtěte si další informace o deklarací
id_tokenidentity a .