Autorizace přístupu k webovým aplikacím Azure Active Directory s využitím toku poskytování kódů OAuth 2.0
Upozornění
Tento obsah je určený pro starší koncový bod Azure AD verze 1.0. Pro nové projekty použijte Microsoft identity platform.
Poznámka
Pokud serveru neřeknete, jaký prostředek chcete volat, pak server neaktivuje zásady podmíněného přístupu pro tento prostředek. Pokud tedy chcete mít trigger MFA, budete muset do adresy URL zahrnout prostředek.
Azure Active Directory (Azure AD) používá standard OAuth 2.0 za účelem umožnění autorizace přístupu k webovým aplikacím a webovým rozhraním API v tenantovi Azure AD. Tato příručka je nezávislá na jazyce a popisuje, jak odesílat a přijímat zprávy HTTP bez použití některé z našich opensourcových knihoven.
Tok autorizačního kódu OAuth 2.0 je popsaný v části 4.1 specifikace OAuth 2.0. Používá se k ověřování a autorizaci ve většině typů aplikací, včetně webových aplikací a nativně nainstalovaných aplikací.
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 autorizace OAuth 2.0
Na vysoké úrovni celý tok autorizace pro aplikaci vypadá trochu takto:
Žádost o autorizační kód
Tok autorizačního kódu začíná tím, že klient nasměruje uživatele na /authorize koncový bod. V tomto požadavku klient určí oprávnění, která musí od uživatele získat. Koncový bod autorizace OAuth 2.0 pro vašeho tenanta získáte tak, že v Azure Portal vyberete Registrace aplikací > Koncové body.
// Line breaks for legibility only
https://login.microsoftonline.com/{tenant}/oauth2/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&response_type=code
&redirect_uri=http%3A%2F%2Flocalhost%3A12345
&response_mode=query
&resource=https%3A%2F%2Fservice.contoso.com%2F
&state=12345
| 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. Na bočním panelu služeb klikněte na Azure Active Directory, klikněte na Registrace aplikací a zvolte aplikaci. |
| response_type | vyžadováno | Musí obsahovat code tok autorizačního kódu. |
| 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. Pro nativní & mobilní aplikace byste měli použít výchozí hodnotu https://login.microsoftonline.com/common/oauth2/nativeclient. |
| response_mode | optional | Určuje metodu, která se má použít k odeslání výsledného tokenu zpět do aplikace. Může to být query, fragmentnebo form_post.
query poskytuje kód jako parametr řetězce dotazu na identifikátor URI přesměrování. Pokud požadujete token ID pomocí implicitního toku, nemůžete použít query , jak je uvedeno ve specifikaci OpenID. Pokud požadujete pouze kód, můžete použít query, fragmentnebo form_post.
form_post spustí post obsahující kód na identifikátor URI přesměrování. Výchozí hodnota je query pro tok kódu. |
| state | Doporučené | 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 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. |
| prostředek | Doporučené | Identifikátor URI ID aplikace cílového webového rozhraní API (zabezpečený prostředek) Pokud chcete najít identifikátor URI ID aplikace, klikněte v Azure Portal na Azure Active Directory, klikněte na Registrace aplikací, otevřete stránku Nastavení aplikace a pak klikněte na Vlastnosti. Může to být také externí prostředek, jako je https://graph.microsoft.com. To se vyžaduje v jedné z žádostí o autorizaci nebo token. Pokud chcete zajistit méně výzev k ověření, umístěte ho do žádosti o autorizaci, aby se zajistilo, že se od uživatele dostane souhlas. |
| scope | Ignorovány | U aplikací v1 Azure AD musí být obory staticky nakonfigurované v Azure Portal v části Nastavení aplikací Požadovaná oprávnění. |
| Výzva | optional | Uveďte typ požadované interakce uživatele. Platné hodnoty jsou: přihlášení: Uživateli by se měla zobrazit výzva k opětovnému ověření. select_account: Uživateli se zobrazí výzva k výběru účtu a přeruší se jednotné přihlašování. Uživatel může vybrat existující přihlášený účet, zadat své přihlašovací údaje pro zapamatovaný účet nebo se rozhodnout použít úplně jiný účet. souhlas: Souhlas uživatele byl udělen, ale je potřeba ho aktualizovat. Uživatel by měl být vyzván k vyjádření souhlasu. admin_consent: Správce by měl být vyzván k vyjádření souhlasu jménem všech uživatelů v organizaci. |
| login_hint | optional | Dá se použít k předvyplnění pole uživatelské jméno a e-mailová adresa přihlašovací stránky uživatele, pokud znáte jeho uživatelské jméno předem. Aplikace často používají tento parametr při opětovném ověřování, protože už pomocí deklarace identity extrahují uživatelské jméno z předchozího přihlášení preferred_username . |
| domain_hint | optional | Poskytuje nápovědu k tenantovi nebo doméně, které by měl uživatel použít k přihlášení. Hodnota domain_hint je registrovaná doména tenanta. Pokud je tenant federovaný do místního adresáře, AAD přesměruje na zadaný federační server tenanta. |
| code_challenge_method | Doporučené | Metoda použitá ke kódování parametru code_verifiercode_challenge . Může to být jedna z plain nebo S256. Pokud je vyloučeno, předpokládá se, code_challenge že se jedná o prostý text, pokud code_challenge je zahrnut. Azure AAD v1.0 podporuje i plainS256. Další informace najdete v dokumentu RFC pkce. |
| code_challenge | Doporučené | Slouží k zabezpečení udělení autorizačního kódu prostřednictvím ověřovacího klíče pro code Exchange (PKCE) z nativního nebo veřejného klienta. Povinné, pokud code_challenge_method je součástí. Další informace najdete v dokumentu RFC pkce. |
Poznámka
Pokud je uživatel součástí organizace, může správce organizace jménem uživatele vyjádřit souhlas nebo odmítnout, případně mu povolit souhlas. Uživatel má možnost vyjádřit souhlas pouze v případech, kdy to správce povolí.
V tomto okamžiku se uživateli zobrazí výzva k zadání přihlašovacích údajů a vyjádření souhlasu s oprávněními požadovanými aplikací v Azure Portal. Jakmile se uživatel ověří a udělí souhlas, Azure AD odešle vaší aplikaci odpověď na redirect_uri adresu ve vaší žádosti s kódem.
Úspěšná odpověď
Úspěšná odpověď může vypadat takto:
GET HTTP/1.1 302 Found
Location: http://localhost:12345/?code= AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrqqf_ZT_p5uEAEJJ_nZ3UmphWygRNy2C3jJ239gV_DBnZ2syeg95Ki-374WHUP-i3yIhv5i-7KU2CEoPXwURQp6IVYMw-DjAOzn7C3JCu5wpngXmbZKtJdWmiBzHpcO2aICJPu1KvJrDLDP20chJBXzVYJtkfjviLNNW7l7Y3ydcHDsBRKZc3GuMQanmcghXPyoDg41g8XbwPudVh7uCmUponBQpIhbuffFP_tbV8SNzsPoFz9CLpBCZagJVXeqWoYMPe2dSsPiLO9Alf_YIe5zpi-zY4C3aLw5g9at35eZTfNd0gBRpR5ojkMIcZZ6IgAA&session_state=7B29111D-C220-4263-99AB-6F6E135D75EF&state=D79E5777-702E-4260-9A62-37F75FF22CCE
| Parametr | Popis |
|---|---|
| admin_consent | Hodnota je True, pokud správce souhlasil s výzvou k žádosti o souhlas. |
| kód | Autorizační kód, který aplikace požadovala. Aplikace může použít autorizační kód k vyžádání přístupového tokenu pro cílový prostředek. |
| session_state | Jedinečná hodnota, která identifikuje aktuální relaci uživatele. Tato hodnota je identifikátor GUID, ale měla by být považována za neprůhlednou hodnotu, která je předána bez kontroly. |
| state | Pokud je v požadavku zahrnut parametr stavu, měla by se v odpovědi zobrazit stejná hodnota. Před použitím odpovědi je vhodné, aby aplikace ověřila, že hodnoty stavu v požadavku a odpovědi jsou identické. To pomáhá detekovat útoky CSRF (Cross-Site Request Forgery) na klienta. |
Odpověď na chybu
Chybové odpovědi mohou být také odeslány do aplikace redirect_uri , aby je aplikace zvládla odpovídajícím způsobem.
GET http://localhost:12345/?
error=access_denied
&error_description=the+user+canceled+the+authentication
| Parametr | Popis |
|---|---|
| error | Hodnota kódu chyby definovaná v části 5.2 autorizační architektury OAuth 2.0. Další tabulka popisuje kódy chyb, které Azure AD vrátí. |
| error_description | Podrobnější popis chyby Tato zpráva není určená pro koncové uživatele. |
| state | Hodnota stavu je náhodně vygenerovaná nepoužitá hodnota, která se odešle v požadavku a vrátí se v odpovědi, aby se zabránilo útokům csrf (cross-site request forgery). |
Kódy chyb pro chyby koncového bodu autorizace
Následující tabulka popisuje různé kódy chyb, které lze vrátit v error parametru chybové odpovědi.
| Kód chyby | Description | Akce klienta |
|---|---|---|
| invalid_request | Chyba protokolu, například chybějící požadovaný parametr | Opravte a znovu odešlete požadavek. Jedná se o chybu vývoje, která se obvykle zachytí během počátečního testování. |
| unauthorized_client | Klientská aplikace nemá oprávnění vyžádat si autorizační kód. | K tomu obvykle dochází, když klientská aplikace není zaregistrovaná v Azure AD nebo není přidána do Azure AD tenanta uživatele. Aplikace může uživatele vyzvat s pokyny k instalaci aplikace a jejímu přidání do Azure AD. |
| access_denied | Vlastník prostředku odmítl souhlas | Klientská aplikace může uživatele upozornit, že nemůže pokračovat, pokud uživatel nesvolí. |
| unsupported_response_type | Autorizační server nepodporuje typ odpovědi v požadavku. | Opravte a znovu odešlete požadavek. Jedná se o chybu vývoje, která se obvykle zachytí během počátečního testování. |
| server_error | Server zjistil neočekávanou chybu. | 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 na zpracování požadavku. | 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 s pokyny k instalaci aplikace a jejímu přidání do Azure AD. |
Použití autorizačního kódu k vyžádání přístupového tokenu
Teď, když jste získali autorizační kód a uživatel vám udělil oprávnění, můžete kód pro přístupový token uplatnit pro požadovaný prostředek odesláním požadavku POST do koncového /token bodu:
// Line breaks for legibility only
POST /{tenant}/oauth2/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code
&client_id=2d4d11a2-f814-46a7-890a-274a72a7309e
&code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrqqf_ZT_p5uEAEJJ_nZ3UmphWygRNy2C3jJ239gV_DBnZ2syeg95Ki-374WHUP-i3yIhv5i-7KU2CEoPXwURQp6IVYMw-DjAOzn7C3JCu5wpngXmbZKtJdWmiBzHpcO2aICJPu1KvJrDLDP20chJBXzVYJtkfjviLNNW7l7Y3ydcHDsBRKZc3GuMQanmcghXPyoDg41g8XbwPudVh7uCmUponBQpIhbuffFP_tbV8SNzsPoFz9CLpBCZagJVXeqWoYMPe2dSsPiLO9Alf_YIe5zpi-zY4C3aLw5g9at35eZTfNd0gBRpR5ojkMIcZZ6IgAA
&redirect_uri=https%3A%2F%2Flocalhost%3A12345
&resource=https%3A%2F%2Fservice.contoso.com%2F
&client_secret=p@ssw0rd
//NOTE: client_secret only required for web apps
| 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. ID aplikace se zobrazí v nastavení registrace aplikace. |
| grant_type | vyžadováno | Musí být authorization_code pro tok autorizačního kódu. |
| kód | vyžadováno | Hodnota authorization_code , kterou jste získali v předchozí části |
| redirect_uri | vyžadováno | Zaregistrovaný redirect_uriv klientské aplikaci. |
| client_secret | požadováno pro webové aplikace, není povoleno pro veřejné klienty | Tajný kód aplikace, který jste vytvořili v Azure Portal pro vaši aplikaci v části Klíče. Nelze ho použít v nativní aplikaci (veřejném klientovi), protože client_secrets nelze spolehlivě uložit na zařízeních. Vyžaduje se pro webové aplikace a webová rozhraní API (všechna důvěrná klienti), která mají možnost bezpečně ukládat client_secret data na straně serveru. Před odesláním by client_secret měla být zakódovaná adresa URL. |
| prostředek | Doporučené | Identifikátor URI ID aplikace cílového webového rozhraní API (zabezpečený prostředek). Identifikátor URI ID aplikace najdete tak, že v Azure Portal kliknete na Azure Active Directory, kliknete na Registrace aplikací, otevřete stránku Nastavení aplikace a pak kliknete na Vlastnosti. Může to být také externí prostředek, jako je https://graph.microsoft.com. To se vyžaduje v jednom z požadavků na autorizaci nebo token. Pokud chcete zajistit méně výzev k ověření, umístěte ho do žádosti o autorizaci, aby se zajistilo, že uživatel obdrží souhlas. Pokud se v žádosti o autorizaci i v požadavku na token musí parametry prostředku shodovat. |
| code_verifier | optional | Stejný code_verifier, který byl použit k získání authorization_code. Vyžaduje se, pokud se pkce použila v žádosti o udělení autorizačního kódu. Další informace najdete v dokumentu PKCE RFC. |
Identifikátor URI ID aplikace najdete tak, že v Azure Portal kliknete na Azure Active Directory, kliknete na Registrace aplikací, otevřete stránku Nastavení aplikace a pak kliknete na Vlastnosti.
Úspěšná odpověď
Azure AD po úspěšné odpovědi vrátí přístupový token. Aby se minimalizovala síťová volání z klientské aplikace a související latence, měla by klientská aplikace ukládat přístupové tokeny do mezipaměti po dobu životnosti tokenů, která je určena v odpovědi OAuth 2.0. K určení životnosti tokenu použijte hodnoty parametru expires_in nebo expires_on .
Pokud prostředek webového rozhraní API vrátí invalid_token kód chyby, může to znamenat, že prostředek zjistil, že vypršela platnost tokenu. Pokud se hodiny klienta a prostředku liší (označuje se jako nerovnoměrná distribuce času), prostředek může považovat token za vypršení platnosti před vymazáním tokenu z mezipaměti klienta. Pokud k tomu dojde, vymažte token z mezipaměti, i když je ještě v vypočítané době životnosti.
Úspěšná odpověď by mohla vypadat takto:
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1THdqcHdBSk9NOW4tQSJ9.eyJhdWQiOiJodHRwczovL3NlcnZpY2UuY29udG9zby5jb20vIiwiaXNzIjoiaHR0cHM6Ly9zdHMud2luZG93cy5uZXQvN2ZlODE0NDctZGE1Ny00Mzg1LWJlY2ItNmRlNTdmMjE0NzdlLyIsImlhdCI6MTM4ODQ0MDg2MywibmJmIjoxMzg4NDQwODYzLCJleHAiOjEzODg0NDQ3NjMsInZlciI6IjEuMCIsInRpZCI6IjdmZTgxNDQ3LWRhNTctNDM4NS1iZWNiLTZkZTU3ZjIxNDc3ZSIsIm9pZCI6IjY4Mzg5YWUyLTYyZmEtNGIxOC05MWZlLTUzZGQxMDlkNzRmNSIsInVwbiI6ImZyYW5rbUBjb250b3NvLmNvbSIsInVuaXF1ZV9uYW1lIjoiZnJhbmttQGNvbnRvc28uY29tIiwic3ViIjoiZGVOcUlqOUlPRTlQV0pXYkhzZnRYdDJFYWJQVmwwQ2o4UUFtZWZSTFY5OCIsImZhbWlseV9uYW1lIjoiTWlsbGVyIiwiZ2l2ZW5fbmFtZSI6IkZyYW5rIiwiYXBwaWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctODkwYS0yNzRhNzJhNzMwOWUiLCJhcHBpZGFjciI6IjAiLCJzY3AiOiJ1c2VyX2ltcGVyc29uYXRpb24iLCJhY3IiOiIxIn0.JZw8jC0gptZxVC-7l5sFkdnJgP3_tRjeQEPgUn28XctVe3QqmheLZw7QVZDPCyGycDWBaqy7FLpSekET_BftDkewRhyHk9FW_KeEz0ch2c3i08NGNDbr6XYGVayNuSesYk5Aw_p3ICRlUV1bqEwk-Jkzs9EEkQg4hbefqJS6yS1HoV_2EsEhpd_wCQpxK89WPs3hLYZETRJtG5kvCCEOvSHXmDE6eTHGTnEgsIk--UlPe275Dvou4gEAwLofhLDQbMSjnlV5VLsjimNBVcSRFShoxmQwBJR_b2011Y5IuD6St5zPnzruBbZYkGNurQK63TJPWmRd3mbJsGM0mf3CUQ",
"token_type": "Bearer",
"expires_in": "3600",
"expires_on": "1388444763",
"resource": "https://service.contoso.com/",
"refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4rTfgV29ghDOHRc2B-C_hHeJaJICqjZ3mY2b_YNqmf9SoAylD1PycGCB90xzZeEDg6oBzOIPfYsbDWNf621pKo2Q3GGTHYlmNfwoc-OlrxK69hkha2CF12azM_NYhgO668yfcUl4VBbiSHZyd1NVZG5QTIOcbObu3qnLutbpadZGAxqjIbMkQ2bQS09fTrjMBtDE3D6kSMIodpCecoANon9b0LATkpitimVCrl-NyfN3oyG4ZCWu18M9-vEou4Sq-1oMDzExgAf61noxzkNiaTecM-Ve5cq6wHqYQjfV9DOz4lbceuYCAA",
"scope": "https%3A%2F%2Fgraph.microsoft.com%2Fmail.read",
"id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctODkwYS0yNzRhNzJhNzMwOWUiLCJpc3MiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC83ZmU4MTQ0Ny1kYTU3LTQzODUtYmVjYi02ZGU1N2YyMTQ3N2UvIiwiaWF0IjoxMzg4NDQwODYzLCJuYmYiOjEzODg0NDA4NjMsImV4cCI6MTM4ODQ0NDc2MywidmVyIjoiMS4wIiwidGlkIjoiN2ZlODE0NDctZGE1Ny00Mzg1LWJlY2ItNmRlNTdmMjE0NzdlIiwib2lkIjoiNjgzODlhZTItNjJmYS00YjE4LTkxZmUtNTNkZDEwOWQ3NGY1IiwidXBuIjoiZnJhbmttQGNvbnRvc28uY29tIiwidW5pcXVlX25hbWUiOiJmcmFua21AY29udG9zby5jb20iLCJzdWIiOiJKV3ZZZENXUGhobHBTMVpzZjd5WVV4U2hVd3RVbTV5elBtd18talgzZkhZIiwiZmFtaWx5X25hbWUiOiJNaWxsZXIiLCJnaXZlbl9uYW1lIjoiRnJhbmsifQ."
}
| Parametr | Popis |
|---|---|
| access_token | Požadovaný přístupový token. Jedná se o neprůzrůzný řetězec – závisí na tom, co prostředek očekává, že obdrží, a není určený pro to, aby se na něj klient díval. Aplikace může tento token použít k ověření vůči zabezpečenému prostředku, jako je webové rozhraní API. |
| token_type | Označuje hodnotu typu tokenu. Jediný typ, který Azure AD podporuje, je Bearer. Další informace o nosných tokenech najdete v tématu OAuth2.0 Authorization Framework: Použití nosných tokenů (RFC 6750). |
| expires_in | Jak dlouho je přístupový token platný (v sekundách) |
| expires_on | Čas vypršení platnosti přístupového tokenu. Datum je reprezentováno jako počet sekund od 1970-01-01T0:0:0Z UTC do času vypršení platnosti. Tato hodnota se používá k určení doby života tokenů uložených v mezipaměti. |
| prostředek | Identifikátor URI ID aplikace webového rozhraní API (zabezpečený prostředek) |
| scope | Oprávnění zosobnění udělená klientské aplikaci. Výchozí oprávnění je user_impersonation. Vlastník zabezpečeného prostředku může v Azure AD zaregistrovat další hodnoty. |
| refresh_token | Obnovovací token OAuth 2.0. Aplikace může tento token použít k získání dalších přístupových tokenů po vypršení platnosti aktuálního přístupového tokenu. Obnovovací tokeny jsou dlouhodobé a je možné je použít k uchovávání přístupu k prostředkům po delší dobu. |
| id_token | Nepodepsaný webový token JSON (JWT) představující token ID. Aplikace může dekódovat segmenty tohoto tokenu base64Url a vyžádat si informace o přihlášených uživatelích. Aplikace může hodnoty ukládat do mezipaměti a zobrazovat je, ale neměla by se na ně spoléhat kvůli autorizaci nebo hranicím zabezpečení. |
Další informace o webových tokenech JSON najdete ve specifikaci konceptu JWT IETF. Další informace o id_tokensnástroji najdete v toku OpenID Connect verze 1.0.
Chybová odpověď
Chyby koncového bodu vystavování tokenů jsou kódy chyb HTTP, protože klient volá koncový bod vystavování tokenů přímo. Kromě stavového kódu HTTP vrací koncový bod vystavení tokenu Azure AD také dokument JSON s objekty, které popisují chybu.
Ukázková chybová odpověď by mohla vypadat takto:
{
"error": "invalid_grant",
"error_description": "AADSTS70002: Error validating credentials. AADSTS70008: The provided authorization code or refresh token is expired. Send a new interactive authorization request for this user and resource.\r\nTrace ID: 3939d04c-d7ba-42bf-9cb7-1e5854cdce9e\r\nCorrelation ID: a8125194-2dc8-4078-90ba-7b6592a7f231\r\nTimestamp: 2016-04-11 18:00:12Z",
"error_codes": [
70002,
70008
],
"timestamp": "2016-04-11 18:00:12Z",
"trace_id": "3939d04c-d7ba-42bf-9cb7-1e5854cdce9e",
"correlation_id": "a8125194-2dc8-4078-90ba-7b6592a7f231"
}
| 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í. |
| error_codes | Seznam kódů chyb specifických pro službu STS, které vám můžou pomoct při diagnostice. |
| časové razítko | Čas, kdy došlo k chybě. |
| trace_id | Jedinečný identifikátor požadavku, který může pomoct s diagnostikou. |
| correlation_id | Jedinečný identifikátor požadavku, který může pomoct při diagnostice napříč komponentami. |
Stavové kódy HTTP
Následující tabulka uvádí stavové kódy HTTP, které koncový bod vystavování tokenů vrací. V některých případech je kód chyby dostatečný k popisu odpovědi, ale pokud dojde k chybám, musíte parsovat doprovodný dokument JSON a prozkoumat jeho kód chyby.
| Kód HTTP | Popis |
|---|---|
| 400 | Výchozí kód HTTP. Používá se ve většině případů a obvykle je způsoben poškozeným požadavkem. Opravte požadavek a odešlete ho znovu. |
| 401 | Ověření se nezdařilo. V požadavku například chybí parametr client_secret. |
| 403 | Autorizace se nezdařila. Uživatel například nemá oprávnění pro přístup k prostředku. |
| 500 | Ve službě došlo k vnitřní chybě. Zkuste požadavek zopakovat. |
Kódy chyb pro chyby koncového bodu tokenu
| Kód chyby | Description | Akce klienta |
|---|---|---|
| invalid_request | Chyba protokolu, například chybějící požadovaný parametr | Oprava a opětovné odeslání požadavku |
| invalid_grant | Autorizační kód je neplatný nebo vypršela jeho platnost. | Zkuste nový požadavek na koncový bod./authorize |
| unauthorized_client | Ověřený klient nemá oprávnění používat tento typ udělení autorizace. | K tomu obvykle dochází, když klientská aplikace není zaregistrovaná v Azure AD nebo není přidána do Azure AD tenanta uživatele. Aplikace může uživatele vyzvat s pokyny k instalaci aplikace a jejímu přidání do Azure AD. |
| invalid_client | Ověřování klienta se nezdařilo. | Přihlašovací údaje klienta nejsou platné. Pro opravu správce aplikace aktualizuje přihlašovací údaje. |
| unsupported_grant_type | Autorizační server nepodporuje typ udělení autorizace. | Změňte typ udělení v žádosti. K tomuto typu chyby by mělo dojít pouze během vývoje a mělo by být zjištěno během počátečního testování. |
| 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 s pokyny k instalaci aplikace a jejímu přidání do Azure AD. |
| interaction_required | Požadavek vyžaduje interakci uživatele. Vyžaduje se například další krok ověřování. | Místo neinteraktivního požadavku zkuste to znovu s interaktivní žádostí o autorizaci pro stejný prostředek. |
| temporarily_unavailable | Server je dočasně příliš zaneprázdněn na zpracování požadavku. | 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. |
Použití přístupového tokenu pro přístup k prostředku
Teď, když jste úspěšně získali access_token, můžete token použít v požadavcích na webová rozhraní API tak, že ho zahrnete do Authorization hlavičky. Specifikace RFC 6750 vysvětluje, jak používat nosné tokeny v požadavcích HTTP pro přístup k chráněným prostředkům.
Ukázkový požadavek
GET /data HTTP/1.1
Host: service.contoso.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1THdqcHdBSk9NOW4tQSJ9.eyJhdWQiOiJodHRwczovL3NlcnZpY2UuY29udG9zby5jb20vIiwiaXNzIjoiaHR0cHM6Ly9zdHMud2luZG93cy5uZXQvN2ZlODE0NDctZGE1Ny00Mzg1LWJlY2ItNmRlNTdmMjE0NzdlLyIsImlhdCI6MTM4ODQ0MDg2MywibmJmIjoxMzg4NDQwODYzLCJleHAiOjEzODg0NDQ3NjMsInZlciI6IjEuMCIsInRpZCI6IjdmZTgxNDQ3LWRhNTctNDM4NS1iZWNiLTZkZTU3ZjIxNDc3ZSIsIm9pZCI6IjY4Mzg5YWUyLTYyZmEtNGIxOC05MWZlLTUzZGQxMDlkNzRmNSIsInVwbiI6ImZyYW5rbUBjb250b3NvLmNvbSIsInVuaXF1ZV9uYW1lIjoiZnJhbmttQGNvbnRvc28uY29tIiwic3ViIjoiZGVOcUlqOUlPRTlQV0pXYkhzZnRYdDJFYWJQVmwwQ2o4UUFtZWZSTFY5OCIsImZhbWlseV9uYW1lIjoiTWlsbGVyIiwiZ2l2ZW5fbmFtZSI6IkZyYW5rIiwiYXBwaWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctODkwYS0yNzRhNzJhNzMwOWUiLCJhcHBpZGFjciI6IjAiLCJzY3AiOiJ1c2VyX2ltcGVyc29uYXRpb24iLCJhY3IiOiIxIn0.JZw8jC0gptZxVC-7l5sFkdnJgP3_tRjeQEPgUn28XctVe3QqmheLZw7QVZDPCyGycDWBaqy7FLpSekET_BftDkewRhyHk9FW_KeEz0ch2c3i08NGNDbr6XYGVayNuSesYk5Aw_p3ICRlUV1bqEwk-Jkzs9EEkQg4hbefqJS6yS1HoV_2EsEhpd_wCQpxK89WPs3hLYZETRJtG5kvCCEOvSHXmDE6eTHGTnEgsIk--UlPe275Dvou4gEAwLofhLDQbMSjnlV5VLsjimNBVcSRFShoxmQwBJR_b2011Y5IuD6St5zPnzruBbZYkGNurQK63TJPWmRd3mbJsGM0mf3CUQ
Odpověď na chybu
Zabezpečené prostředky, které implementují RFC 6750, vydávají stavové kódy HTTP. Pokud požadavek neobsahuje přihlašovací údaje pro ověřování nebo chybí token, odpověď obsahuje hlavičku WWW-Authenticate . Když požadavek selže, server prostředků odpoví stavovým kódem HTTP a kódem chyby.
Následuje příklad neúspěšné odpovědi, když požadavek klienta neobsahuje nosný token:
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer authorization_uri="https://login.microsoftonline.com/contoso.com/oauth2/authorize", error="invalid_token", error_description="The access token is missing.",
Parametry chyby
| Parametr | Popis |
|---|---|
| authorization_uri | Identifikátor URI (fyzický koncový bod) autorizačního serveru. Tato hodnota se také používá jako vyhledávací klíč k získání dalších informací o serveru z koncového bodu zjišťování. Klient musí ověřit, že autorizační server je důvěryhodný. Pokud je prostředek chráněný Azure AD, stačí ověřit, že adresa URL začíná |
| error | Hodnota kódu chyby definovaná v části 5.2 autorizační architektury OAuth 2.0. |
| error_description | Podrobnější popis chyby Tato zpráva není určená pro koncové uživatele. |
| resource_id | Vrátí jedinečný identifikátor prostředku. Klientská aplikace může tento identifikátor použít jako hodnotu parametru resource , když požaduje token pro prostředek. Je důležité, aby klientská aplikace tuto hodnotu ověřila, jinak by škodlivá služba mohla vyvolat útok na zvýšení oprávnění . Doporučenou strategií prevence útoku je ověřit, jestli |
Kódy chyb schématu nosné
Specifikace RFC 6750 definuje následující chyby pro prostředky, které v odpovědi používají hlavičku WWW-Authenticate a schéma bearer.
| Stavový kód HTTP | Kód chyby | Description | Akce klienta |
|---|---|---|---|
| 400 | invalid_request | Požadavek není ve správném formátu. Může například chybět parametr nebo použít stejný parametr dvakrát. | Opravte chybu a zkuste požadavek zopakovat. K tomuto typu chyby by mělo dojít pouze během vývoje a mělo by se zjistit při počátečním testování. |
| 401 | invalid_token | Přístupový token chybí, je neplatný nebo je odvolán. Hodnota parametru error_description poskytuje další podrobnosti. | Vyžádejte si nový token z autorizačního serveru. Pokud nový token selže, došlo k neočekávané chybě. Odešlete uživateli chybovou zprávu a zkuste to znovu po náhodných zpožděních. |
| 403 | insufficient_scope | Přístupový token neobsahuje oprávnění zosobnění potřebná pro přístup k prostředku. | Odešlete do koncového bodu autorizace novou žádost o autorizaci. Pokud odpověď obsahuje parametr scope, použijte hodnotu oboru v požadavku na prostředek. |
| 403 | insufficient_access | Předmět tokenu nemá oprávnění potřebná pro přístup k prostředku. | Požádejte uživatele, aby použil jiný účet nebo požádal o oprávnění k zadanému prostředku. |
Aktualizace přístupových tokenů
Přístupové tokeny jsou krátkodobé a pokud chcete pokračovat v přístupu k prostředkům, musíte je po vypršení jejich platnosti aktualizovat. Můžete aktualizovat odesláním dalšího POST požadavku do koncového code/token bodu, ale tentokrát místo refresh_token .access_token Obnovovací tokeny jsou platné pro všechny prostředky, ke kterým už byl vašemu klientovi udělen souhlas s přístupem . Proto je možné použít obnovovací token vydaný na žádost resource=https://graph.microsoft.com pro k vyžádání nového přístupového tokenu pro resource=https://contoso.com/api.
Obnovovací tokeny nemají zadané životnosti. Životnost obnovovacích tokenů je obvykle poměrně dlouhá. V některých případech však platnost tokenů aktualizace vyprší, jsou odvolány nebo chybí dostatečná oprávnění pro požadovanou akci. Vaše aplikace musí správně očekávat chyby vracené koncovým bodem vystavování tokenu a zpracovávat je.
Když obdržíte odpověď s chybou obnovovacího tokenu, zahoďte aktuální obnovovací token a požádejte o nový autorizační kód nebo přístupový token. Zejména při použití obnovovacího tokenu v toku udělení autorizačního kódu platí, že pokud obdržíte odpověď s interaction_required kódy chyb nebo invalid_grant , zahoďte obnovovací token a požádejte o nový autorizační kód.
Ukázkový požadavek na koncový bod specifický pro tenanta (můžete také použít společný koncový bod) o získání nového přístupového tokenu pomocí obnovovacího tokenu vypadá takto:
// Line breaks for legibility only
POST /{tenant}/oauth2/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&refresh_token=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq...
&grant_type=refresh_token
&resource=https%3A%2F%2Fservice.contoso.com%2F
&client_secret=JqQX2PNo9bpM0uEihUPzyrh // NOTE: Only required for web apps
Úspěšná odpověď
Úspěšná odpověď tokenu bude vypadat takto:
{
"token_type": "Bearer",
"expires_in": "3600",
"expires_on": "1460404526",
"resource": "https://service.contoso.com/",
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1THdqcHdBSk9NOW4tQSJ9.eyJhdWQiOiJodHRwczovL3NlcnZpY2UuY29udG9zby5jb20vIiwiaXNzIjoiaHR0cHM6Ly9zdHMud2luZG93cy5uZXQvN2ZlODE0NDctZGE1Ny00Mzg1LWJlY2ItNmRlNTdmMjE0NzdlLyIsImlhdCI6MTM4ODQ0MDg2MywibmJmIjoxMzg4NDQwODYzLCJleHAiOjEzODg0NDQ3NjMsInZlciI6IjEuMCIsInRpZCI6IjdmZTgxNDQ3LWRhNTctNDM4NS1iZWNiLTZkZTU3ZjIxNDc3ZSIsIm9pZCI6IjY4Mzg5YWUyLTYyZmEtNGIxOC05MWZlLTUzZGQxMDlkNzRmNSIsInVwbiI6ImZyYW5rbUBjb250b3NvLmNvbSIsInVuaXF1ZV9uYW1lIjoiZnJhbmttQGNvbnRvc28uY29tIiwic3ViIjoiZGVOcUlqOUlPRTlQV0pXYkhzZnRYdDJFYWJQVmwwQ2o4UUFtZWZSTFY5OCIsImZhbWlseV9uYW1lIjoiTWlsbGVyIiwiZ2l2ZW5fbmFtZSI6IkZyYW5rIiwiYXBwaWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctODkwYS0yNzRhNzJhNzMwOWUiLCJhcHBpZGFjciI6IjAiLCJzY3AiOiJ1c2VyX2ltcGVyc29uYXRpb24iLCJhY3IiOiIxIn0.JZw8jC0gptZxVC-7l5sFkdnJgP3_tRjeQEPgUn28XctVe3QqmheLZw7QVZDPCyGycDWBaqy7FLpSekET_BftDkewRhyHk9FW_KeEz0ch2c3i08NGNDbr6XYGVayNuSesYk5Aw_p3ICRlUV1bqEwk-Jkzs9EEkQg4hbefqJS6yS1HoV_2EsEhpd_wCQpxK89WPs3hLYZETRJtG5kvCCEOvSHXmDE6eTHGTnEgsIk--UlPe275Dvou4gEAwLofhLDQbMSjnlV5VLsjimNBVcSRFShoxmQwBJR_b2011Y5IuD6St5zPnzruBbZYkGNurQK63TJPWmRd3mbJsGM0mf3CUQ",
"refresh_token": "AwABAAAAv YNqmf9SoAylD1PycGCB90xzZeEDg6oBzOIPfYsbDWNf621pKo2Q3GGTHYlmNfwoc-OlrxK69hkha2CF12azM_NYhgO668yfcUl4VBbiSHZyd1NVZG5QTIOcbObu3qnLutbpadZGAxqjIbMkQ2bQS09fTrjMBtDE3D6kSMIodpCecoANon9b0LATkpitimVCrl PM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4rTfgV29ghDOHRc2B-C_hHeJaJICqjZ3mY2b_YNqmf9SoAylD1PycGCB90xzZeEDg6oBzOIPfYsbDWNf621pKo2Q3GGTHYlmNfwoc-OlrxK69hkha2CF12azM_NYhgO668yfmVCrl-NyfN3oyG4ZCWu18M9-vEou4Sq-1oMDzExgAf61noxzkNiaTecM-Ve5cq6wHqYQjfV9DOz4lbceuYCAA"
}
| Parametr | Popis |
|---|---|
| token_type | Typ tokenu. Jediná podporovaná hodnota je nosná. |
| expires_in | Zbývající životnost tokenu v sekundách. Typická hodnota je 3600 (jedna hodina). |
| expires_on | Datum a čas vypršení platnosti tokenu. Datum je reprezentováno jako počet sekund od 1970-01-01T0:0:0Z UTC do doby vypršení platnosti. |
| prostředek | Identifikuje zabezpečený prostředek, ke kterému lze přístupový token použít pro přístup. |
| scope | Oprávnění zosobnění udělená nativní klientské aplikaci Výchozí oprávnění je user_impersonation. Vlastník cílového prostředku může v Azure AD zaregistrovat alternativní hodnoty. |
| access_token | Nový přístupový token, který byl požadován. |
| refresh_token | Nový refresh_token OAuth 2.0, který lze použít k vyžádání nových přístupových tokenů, když vyprší platnost tokenu v této odpovědi. |
Odpověď na chybu
Ukázková odpověď na chybu může vypadat takto:
{
"error": "invalid_resource",
"error_description": "AADSTS50001: The application named https://foo.microsoft.com/mail.read was not found in the tenant named 295e01fc-0c56-4ac3-ac57-5d0ed568f872. This can happen if the application has not been installed by the administrator of the tenant or consented to by any user in the tenant. You might have sent your authentication request to the wrong tenant.\r\nTrace ID: ef1f89f6-a14f-49de-9868-61bd4072f0a9\r\nCorrelation ID: b6908274-2c58-4e91-aea9-1f6b9c99347c\r\nTimestamp: 2016-04-11 18:59:01Z",
"error_codes": [
50001
],
"timestamp": "2016-04-11 18:59:01Z",
"trace_id": "ef1f89f6-a14f-49de-9868-61bd4072f0a9",
"correlation_id": "b6908274-2c58-4e91-aea9-1f6b9c99347c"
}
| Parametr | Popis |
|---|---|
| error | Řetězec kódu chyby, který lze použít ke klasifikaci typů chyb, ke kterým dochází, a lze ho 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í. |
| error_codes | Seznam kódů chyb specifických pro službu STS, které můžou pomoct při diagnostice. |
| časové razítko | Čas, kdy došlo k chybě. |
| trace_id | Jedinečný identifikátor požadavku, který může pomoct s diagnostikou. |
| correlation_id | Jedinečný identifikátor požadavku, který může pomoct při diagnostice napříč komponentami. |
Popis kódů chyb a doporučené akce klienta najdete v tématu Kódy chyb pro chyby koncového bodu tokenu.
Další kroky
Další informace o koncovém bodu Azure AD v1.0 a o tom, jak přidat ověřování a autorizaci do webových aplikací a webových rozhraní API, najdete v tématu ukázkové aplikace.