Microsoft Identity Platform a tok autorizačního kódu OAuth 2.0
Typ udělení autorizačního kódu OAuth 2.0 nebo tok ověřovacího kódu umožňuje klientské aplikaci získat autorizovaný přístup k chráněným prostředkům, jako jsou webová rozhraní API. Tok ověřovacího kódu vyžaduje uživatelský agent, který podporuje přesměrování z autorizačního serveru (Microsoft Identity Platform) zpět do vaší aplikace. Například webový prohlížeč, desktopová nebo mobilní aplikace provozovaná uživatelem, aby se přihlásil k aplikaci a přistupoval ke svým datům.
Tento článek popisuje podrobnosti protokolu nízké úrovně vyžadované pouze při ručním vytváření a vydávání nezpracovaných požadavků HTTP ke spuštění toku, které nedoporučujeme. Místo toho použijte integrovanou a podporovanou knihovnu ověřování Od Microsoftu k získání tokenů zabezpečení a volání chráněných webových rozhraní API ve vašich aplikacích.
Aplikace, které podporují tok ověřovacího kódu
Tok ověřovacího kódu spárovaný s ověřovacím klíčem pro výměnu kódu (PKCE) a OpenID Připojení (OIDC) k získání přístupových tokenů a tokenů ID v těchto typech aplikací:
- Jednostránkové webové aplikace (SPA)
- Standardní (serverová) webová aplikace
- Desktopové a mobilní aplikace
Podrobnosti protokolu
Tok autorizačního kódu OAuth 2.0 je popsaný v části 4.1 specifikace OAuth 2.0. Aplikace využívající tok autorizačního kódu OAuth 2.0 získávají access_token požadavky na prostředky chráněné platformou Microsoft Identity Platform (obvykle rozhraní API). Aplikace můžou také vyžadovat nové ID a přístupové tokeny pro dříve ověřené entity pomocí mechanismu aktualizace.
Tento diagram znázorňuje základní zobrazení toku ověřování:
Identifikátory URI pro přesměrování pro jednostránkové aplikace (SPA)
Identifikátory URI přesměrování pro spA, které používají tok ověřovacího kódu, vyžadují speciální konfiguraci.
- Přidejte identifikátor URI přesměrování, který podporuje tok ověřovacího kódu pomocí infrastruktury veřejných klíčů a sdílení prostředků mezi zdroji (CORS): Postupujte podle kroků v identifikátoru URI přesměrování: MSAL.js 2.0 s tokem ověřovacího kódu.
- Aktualizace identifikátoru URI přesměrování: Nastavte identifikátor URI
typespapřesměrování pomocí editoru manifestu aplikace v Centru pro správu Microsoft Entra.
spa Typ přesměrování je zpětně kompatibilní s implicitními toky. Aplikace, které v současné době používají implicitní tok k získání tokenů, můžou přejít na typ identifikátoru spa URI přesměrování bez problémů a pokračovat v používání implicitního toku.
Pokud se pokusíte použít tok autorizačního kódu bez nastavení CORS pro identifikátor URI přesměrování, zobrazí se v konzole tato chyba:
access to XMLHttpRequest at 'https://login.microsoftonline.com/common/v2.0/oauth2/token' from origin 'yourApp.com' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.
Pokud ano, navštivte registraci aplikace a aktualizujte identifikátor URI přesměrování aplikace tak, aby používal tento spa typ.
Aplikace nemůžou spa používat identifikátor URI přesměrování s toky mimo SPA, například nativní aplikace nebo toky přihlašovacích údajů klienta. K zajištění zabezpečení a osvědčených postupů vrátí platforma Microsoft Identity Platform chybu, pokud se pokusíte použít spa identifikátor URI přesměrování bez hlavičky Origin . Platforma Microsoft Identity Platform také zabraňuje použití přihlašovacích údajů klienta ve všech tocích v přítomnosti hlavičky Origin , aby se zajistilo, že se tajné kódy nepoužívají v prohlížeči.
Žádost o autorizační kód
Tok autorizačního kódu začíná klientem, který uživatele nasměruje na /authorize koncový bod. V této žádosti klient požádá openiduživatele , offline_accessa https://graph.microsoft.com/mail.read oprávnění od uživatele.
Některá oprávnění jsou omezená správcem, například zápis dat do adresáře organizace pomocí Directory.ReadWrite.All. Pokud vaše aplikace požádá o přístup k některému z těchto oprávnění od uživatele organizace, uživateli se zobrazí chybová zpráva s informací, že nemá oprávnění k vyjádření souhlasu s oprávněními vaší aplikace. Pokud chcete požádat o přístup k oborům omezeným správcem, měli byste je požádat přímo od globálního Správa istratoru. Další informace najdete v tématu Správa omezená oprávnění.
Pokud není uvedeno jinak, neexistují žádné výchozí hodnoty pro volitelné parametry. U požadavku, který vynechá volitelné parametry, ale existuje výchozí chování. Výchozí chování je buď přihlásit se k jedinému aktuálnímu uživateli, zobrazit výběr účtu, pokud existuje více uživatelů, nebo zobrazit přihlašovací stránku, pokud nejsou přihlášeni žádní uživatelé.
// Line breaks for legibility only
https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&response_type=code
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=query
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read
&state=12345
&code_challenge=YTFjNjI1OWYzMzA3MTI4ZDY2Njg5M2RkNmVjNDE5YmEyZGRhOGYyM2IzNjdmZWFhMTQ1ODg3NDcxY2Nl
&code_challenge_method=S256
| Parametr | Povinné nebo volitelné | Popis |
|---|---|---|
tenant |
povinné | {tenant} Hodnotu v cestě požadavku můžete použít k řízení, kdo se může přihlásit k aplikaci. Platné hodnoty jsou common, organizations, consumersa identifikátory tenanta. V případě scénářů hosta, ve kterých podepíšete uživatele z jednoho tenanta do jiného tenanta, musíte zadat identifikátor tenanta, aby se přihlásil k tenantovi prostředku. Další informace najdete v tématu Koncové body. |
client_id |
povinné | ID aplikace (klienta), které centrum pro správu Microsoft Entra – Registrace aplikací prostředí přiřazené k vaší aplikaci. |
response_type |
povinné | Musí obsahovat code tok autorizačního kódu. Může také zahrnovat id_token nebo token pokud používáte hybridní tok. |
redirect_uri |
povinné | Aplikace redirect_uri , 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 v Centru pro správu Microsoft Entra, s výjimkou adresy URL zakódované. Pro nativní a mobilní aplikace použijte jednu z doporučených hodnot: https://login.microsoftonline.com/common/oauth2/nativeclient pro aplikace používající vložené prohlížeče nebo http://localhost pro aplikace, které používají systémové prohlížeče. |
scope |
povinné | Seznam oborů oddělených mezerami, se kterými má uživatel souhlasit. /authorize Pro část požadavku může tento parametr pokrýt více prostředků. Tato hodnota umožňuje vaší aplikaci získat souhlas pro více webových rozhraní API, která chcete volat. |
response_mode |
Doporučené | Určuje, jak by platforma identit měla vrátit požadovaný token do vaší aplikace. Podporované hodnoty: - query: Výchozí hodnota při vyžádání přístupového tokenu. Poskytuje kód jako parametr řetězce dotazu na identifikátor URI přesměrování. Parametr query není podporován při vyžádání tokenu ID pomocí implicitního toku. - fragment: Výchozí nastavení při vyžádání tokenu ID pomocí implicitního toku. Podporuje se také v případě, že požadujete pouze kód.- form_post: Spustí POST obsahující kód na identifikátor URI přesměrování. Podporuje se při vyžádání kódu. |
state |
Doporučené | Hodnota zahrnutá v požadavku, která se také vrátí 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. Hodnota může také zakódovat informace o stavu uživatele v aplikaci před tím, než došlo k žádosti o ověření. Může například zakódovat stránku nebo zobrazení, na které byly. |
prompt |
optional | Určuje typ interakce uživatele, který je povinný. Platné hodnoty jsou login, none, consenta select_account.- 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 opak. Zajistí, že se uživateli nezobrazí žádná interaktivní výzva. Pokud požadavek nejde dokončit bezobslužně pomocí jednotného přihlašování, vrátí interaction_required platforma Microsoft Identity Platform chybu.- prompt=consent aktivuje dialogové okno souhlasu OAuth po přihlášení uživatele a požádá uživatele o udělení oprávnění aplikaci.- prompt=select_account přeruší jednotné přihlašování, které poskytuje možnosti výběru účtu se seznamem všech účtů buď v relaci, nebo v jakémkoli zapamatovaného účtu, nebo možnost zvolit, že chcete použít jiný účet úplně. |
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. Aplikace můžou tento parametr použít během opětovného ověření po extrakci login_hintvolitelné deklarace identity z dřívějšího přihlášení. |
domain_hint |
optional | V případě zahrnutí aplikace 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í. Můžete je například odeslat zprostředkovateli federované identity. Aplikace můžou tento parametr použít při opětovném ověření extrahováním tid z předchozího přihlášení. |
code_challenge |
doporučeno / povinné | Používá se k zabezpečení udělení autorizačního kódu pomocí ověřovacího klíče pro výměnu kódu (PKCE). Vyžaduje se, pokud code_challenge_method je zahrnuta. Další informace najdete v dokumentu PKCE RFC. Tento parametr se teď doporučuje pro všechny typy aplikací, veřejné i důvěrné klienty a vyžaduje platforma Microsoft Identity Platform pro jednostránka aplikace využívající tok autorizačního kódu. |
code_challenge_method |
doporučeno / povinné | Metoda používaná ke kódování parametru code_verifiercode_challenge . To by mělo být S256, ale specifikace umožňuje použití plain , pokud klient nemůže podporovat SHA256. Pokud je vyloučeno, předpokládá se, code_challenge že je zahrnutý prostý text code_challenge . Platforma Microsoft Identity Platform podporuje obojí plain i S256. Další informace najdete v dokumentu PKCE RFC. Tento parametr se vyžaduje pro jednostrákové aplikace používající tok autorizačního kódu. |
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é zajišťuje, aby uživatel souhlasil s oprávněními uvedenými v parametru scope dotazu. Pokud uživatel s žádným z těchto oprávnění nesouhlasí, požádá ho, aby udělil souhlas s požadovanými oprávněními. Další informace najdete v tématu Oprávnění a souhlas na platformě Microsoft Identity Platform.
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ěď
Tento příklad ukazuje úspěšnou odpověď pomocí response_mode=query:
GET http://localhost?
code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&state=12345
| Parametr | Popis |
|---|---|
code |
Aplikace authorization_code to požadovala. Aplikace může použít autorizační kód k vyžádání přístupového tokenu pro cílový prostředek. Autorizační kódy jsou krátkodobé. Obvykle vyprší po přibližně 10 minutách. |
state |
state Pokud je parametr součástí požadavku, 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é. |
Token ID můžete obdržet také v případě, že si ho vyžádáte a implicitní udělení povolíte v registraci vaší aplikace. Toto chování se někdy označuje jako hybridní tok. Používají ji architektury, jako je ASP.NET.
Chybná odpověď
Chybové odpovědi se můžou také odeslat do redirect_uri aplikace, aby je mohla správně zpracovat:
GET http://localhost?
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 a k reakci na chyby. Tato část chyby je k dispozici, aby aplikace na chybu správně reagovala, ale nevysvětluje podrobně, proč k chybě došlo. |
error_description |
Konkrétní chybová zpráva, která může vývojáři pomoct identifikovat příčinu chyby ověřování. Tato část chyby obsahuje většinu užitečných informací o tom, proč k chybě došlo. |
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 | Popis | Akce klienta |
|---|---|---|
invalid_request |
Chyba protokolu, například chybějící požadovaný parametr. | Opravte požadavek a odešlete ho znovu. Tato chyba je chyba vývoje obvykle zachycena během počátečního testování. |
unauthorized_client |
Klientská aplikace nemá oprávnění požadovat autorizační kód. | K této chybě obvykle dochází v případě, že klientská aplikace není zaregistrovaná v Microsoft Entra ID nebo není přidána do tenanta Microsoft Entra uživatele. Aplikace může vyzvat uživatele s pokyny k instalaci aplikace a jeho přidání do Microsoft Entra ID. |
access_denied |
Vlastník prostředku zamítl souhlas | Klientská aplikace může uživatele upozornit, že nemůže pokračovat, pokud uživatel nesouhlasí. |
unsupported_response_type |
Autorizační server nepodporuje typ odpovědi v požadavku. | Opravte požadavek a odešlete ho znovu. Tato chyba je chyba vývoje obvykle zachycena během počátečního testování. V hybridním toku tato chybová signály, že při registraci klientské aplikace musíte povolit implicitní udělení tokenu ID. |
server_error |
Server zjistil neočekávanou chybu. | Zkuste požadavek zopakovat. Tyto chyby můžou mít za následek dočasné podmínky. Klientská aplikace může uživateli vysvětlit, že jeho odpověď je zpožděná na dočasnou chybu. |
temporarily_unavailable |
Server je dočasně příliš zaneprázdněný pro zpracování požadavku. | Zkuste požadavek zopakovat. Klientská aplikace může uživateli vysvětlit, že jeho odpověď je zpožděná kvůli dočasné podmínce. |
invalid_resource |
Cílový prostředek je neplatný, protože neexistuje, id Microsoft Entra ho nemůže najít nebo není správně nakonfigurované. | Tato chyba označuje prostředek, pokud existuje, nebyl v tenantovi nakonfigurován. Aplikace může vyzvat uživatele s pokyny k instalaci aplikace a jeho přidání do Microsoft Entra ID. |
login_required |
Příliš mnoho uživatelů nebo žádných uživatelů se nenašlo. | Klient požadoval tiché ověřování (prompt=none), ale jeden uživatel nebyl nalezen. Tato chyba může znamenat, že v relaci je aktivních více uživatelů nebo žádní uživatelé. Tato chyba bere v úvahu zvoleného tenanta. Pokud jsou například aktivní dva účty Microsoft Entra a jeden účet Microsoft a consumers zvolí se tiché ověřování. |
interaction_required |
Požadavek vyžaduje interakci uživatele. | Vyžaduje se jiný krok ověřování nebo souhlas. Zkuste požadavek zopakovat bez prompt=none. |
Vyžádání tokenu ID nebo hybridního toku
Pokud chcete zjistit, kdo je uživatel před uplatněním autorizačního kódu, je běžné, že aplikace při vyžádání autorizačního kódu také požadují token ID. Tento přístup se nazývá hybridní tok , protože kombinuje OIDC s tokem autorizačního kódu OAuth2.
Hybridní tok se běžně používá ve webových aplikacích k vykreslení stránky pro uživatele bez blokování uplatnění kódu, zejména v ASP.NET. Jednostrákové aplikace i tradiční webové aplikace mají v tomto modelu nižší latenci.
Hybridní tok je stejný jako tok autorizačního kódu popsaný dříve, ale se třemi dodatky. Všechny tyto doplňky jsou potřeba k vyžádání tokenu ID: nové obory, nový response_type a nový nonce parametr dotazu.
// Line breaks for legibility only
https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&response_type=code%20id_token
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=fragment
&scope=openid%20offline_access%20https%3A%2F%2Fgraph.microsoft.com%2Fuser.read
&state=12345
&nonce=abcde
&code_challenge=YTFjNjI1OWYzMzA3MTI4ZDY2Njg5M2RkNmVjNDE5YmEyZGRhOGYyM2IzNjdmZWFhMTQ1ODg3NDcxY2Nl
&code_challenge_method=S256
| Aktualizovaný parametr | Povinné nebo volitelné | Popis |
|---|---|---|
response_type |
povinné | Přidání id_token indikuje na server, že aplikace by v odpovědi z koncového /authorize bodu chtěla token ID. |
scope |
povinné | U tokenů ID musí být tento parametr aktualizován tak, aby zahrnoval obory tokenů ID: openid a volitelně profile a email. |
nonce |
povinné | Hodnota zahrnutá v požadavku vygenerovaná aplikací, která je součástí výsledné id_token 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. |
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 autorizační kód, ale fragment pokud požadavek obsahuje id_tokenresponse_type hodnotu uvedenou ve specifikaci OpenID. Doporučujeme používat form_postaplikace , zejména při použití http://localhost jako identifikátor URI přesměrování. |
Použití fragment jako režimu odpovědi způsobuje problémy webových aplikací, které čtou kód z přesměrování. Prohlížeče nepřecházejí fragment na webový server. V těchto situacích by aplikace měly používat form_post režim odpovědi, aby se zajistilo, že se na server odešlou všechna data.
Úspěšná odpověď
Tento příklad ukazuje úspěšnou odpověď pomocí response_mode=fragment:
GET https://login.microsoftonline.com/common/oauth2/nativeclient#
code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&id_token=eYj...
&state=12345
| Parametr | Popis |
|---|---|
code |
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. Autorizační kódy jsou krátkodobé, obvykle vypršení platnosti po přibližně 10 minutách. |
id_token |
Token ID pro uživatele vystavený pomocí implicitního udělení. Obsahuje speciální c_hash deklaraci identity, která je hodnotou hash code ve stejném požadavku. |
state |
state Pokud je parametr součástí požadavku, 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é. |
Uplatnění kódu pro přístupový token
Všichni důvěrní klienti si vybrali použití tajných kódů klienta nebo přihlašovacích údajů certifikátu. Symetrické sdílené tajné kódy jsou generovány platformou Microsoft Identity Platform. Přihlašovací údaje certifikátu jsou asymetrickými klíči nahranými vývojářem. Další informace najdete v tématu Přihlašovací údaje ověřovacího certifikátu aplikace Microsoft Identity Platform.
Pro zajištění nejlepšího zabezpečení doporučujeme použít přihlašovací údaje certifikátu. Veřejné klienty, kteří zahrnují nativní aplikace a jednostráňové aplikace, nesmí při uplatnění autorizačního kódu používat tajné kódy ani certifikáty. Vždy se ujistěte, že identifikátory URI pro přesměrování obsahují typ aplikace a jsou jedinečné.
Vyžádání přístupového tokenu pomocí client_secret
Teď, když jste získali authorization_code oprávnění a udělil jim ho uživatel, můžete uplatnit code pro access_token prostředek. code Uplatnění žádosti odesláním POST žádosti do koncového /token bodu:
// Line breaks for legibility only
POST /{tenant}/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
client_id=11112222-bbbb-3333-cccc-4444dddd5555
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read
&code=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq3n8b2JRLk4OxVXr...
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&grant_type=authorization_code
&code_verifier=ThisIsntRandomButItNeedsToBe43CharactersLong
&client_secret=sampleCredentia1s // NOTE: Only required for web apps. This secret needs to be URL-Encoded.
| Parametr | Povinné nebo volitelné | Popis |
|---|---|---|
tenant |
povinné | {tenant} Hodnotu v cestě požadavku můžete použít k řízení, kdo se může přihlásit k aplikaci. Platné hodnoty jsou common, organizations, consumersa identifikátory tenanta. Další informace najdete v tématu Koncové body. |
client_id |
povinné | ID aplikace (klienta), které centrum pro správu Microsoft Entra – Registrace aplikací stránku přiřazenou k vaší aplikaci. |
scope |
optional | Seznam oborů oddělených mezerami. Obory musí být všechny z jednoho prostředku spolu s obory OIDC (profile, , openidemail). Další informace najdete v tématu Oprávnění a souhlas na platformě Microsoft Identity Platform. Tento parametr je rozšířením Microsoftu pro tok autorizačního kódu, jehož účelem je umožnit aplikacím deklarovat prostředek, pro který chce token během uplatnění tokenu. |
code |
povinné | To authorization_code , co jste získali v první noze toku. |
redirect_uri |
povinné | Stejná redirect_uri hodnota, která byla použita k získání authorization_code. |
grant_type |
povinné | Musí se jednat authorization_code o tok autorizačního kódu. |
code_verifier |
Doporučené | Totéž code_verifier , co bylo použito k získání authorization_code. Vyžaduje se, pokud se v žádosti o udělení autorizačního kódu použila infrastruktura veřejných klíčů. Další informace najdete v dokumentu PKCE RFC. |
client_secret |
vyžadováno pro důvěrné webové aplikace | Tajný kód aplikace, který jste vytvořili na portálu pro registraci aplikací pro vaši aplikaci. Nepoužívejte tajný kód aplikace v nativní nebo jednostráňové aplikaci, protože client_secret není možné spolehlivě ukládat na zařízeních nebo webových stránkách. Vyžaduje se pro webové aplikace a webová rozhraní API, která můžou bezpečně ukládat client_secret na straně serveru. Stejně jako všechny parametry musí být tajný klíč klienta před odesláním kódován adresou URL. Tento krok provádí sada SDK. Další informace o kódování identifikátorů URI najdete ve specifikaci obecné syntaxe identifikátoru URI. Model základního ověřování, který místo toho poskytuje přihlašovací údaje v autorizační hlavičce, se podporuje také podle dokumentu RFC 6749 . |
Vyžádání přístupového tokenu pomocí přihlašovacích údajů certifikátu
// Line breaks for legibility only
POST /{tenant}/oauth2/v2.0/token HTTP/1.1
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read
&code=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq3n8b2JRLk4OxVXr...
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&grant_type=authorization_code
&code_verifier=ThisIsntRandomButItNeedsToBe43CharactersLong
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNScUtqRlBuZDdSRnd2d1pJMCJ9.eyJ{a lot of characters here}M8U3bSUKKJDEg
| Parametr | Povinné nebo volitelné | Popis |
|---|---|---|
tenant |
povinné | {tenant} Hodnotu v cestě požadavku můžete použít k řízení, kdo se může přihlásit k aplikaci. Platné hodnoty jsou common, organizations, consumersa identifikátory tenanta. Další podrobnosti najdete v tématu Koncové body. |
client_id |
povinné | ID aplikace (klienta), které centrum pro správu Microsoft Entra – Registrace aplikací stránku přiřazenou k vaší aplikaci. |
scope |
optional | Seznam oborů oddělených mezerami. Obory musí být všechny z jednoho prostředku spolu s obory OIDC (profile, , openidemail). Další informace najdete v tématu oprávnění, souhlas a rozsahy. Tento parametr je rozšířením Microsoftu pro tok autorizačního kódu. Toto rozšíření umožňuje aplikacím deklarovat prostředek, pro který chce token během uplatnění tokenu. |
code |
povinné | To authorization_code , co jste získali v první noze toku. |
redirect_uri |
povinné | Stejná redirect_uri hodnota, která byla použita k získání authorization_code. |
grant_type |
povinné | Musí se jednat authorization_code o tok autorizačního kódu. |
code_verifier |
Doporučené | To samé code_verifier , které bylo použito k získání authorization_code. Vyžaduje se, pokud se v žádosti o udělení autorizačního kódu použila infrastruktura veřejných klíčů. Další informace najdete v dokumentu PKCE RFC. |
client_assertion_type |
vyžadováno pro důvěrné webové aplikace | Hodnota musí být nastavená tak, aby urn:ietf:params:oauth:client-assertion-type:jwt-bearer používala přihlašovací údaje certifikátu. |
client_assertion |
vyžadováno pro důvěrné webové aplikace | Kontrolní výraz, což je webový token JSON (JWT), který potřebujete vytvořit a podepsat pomocí certifikátu, který jste zaregistrovali jako přihlašovací údaje pro vaši aplikaci. Přečtěte si informace o přihlašovacích údaji certifikátu a zjistěte, jak zaregistrovat certifikát a formát kontrolního výrazu. |
Parametry jsou stejné jako požadavek sdíleným tajným kódem s tím rozdílem, že client_secret parametr je nahrazen dvěma parametry: a client_assertion_type a client_assertion.
Úspěšná odpověď
Tento příklad ukazuje úspěšnou odpověď tokenu:
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
"token_type": "Bearer",
"expires_in": 3599,
"scope": "https%3A%2F%2Fgraph.microsoft.com%2Fmail.read",
"refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
"id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctOD...",
}
| Parametr | Popis |
|---|---|
access_token |
Požadovaný přístupový token. Aplikace může tento token použít k ověření zabezpečeného prostředku, jako je webové rozhraní API. |
token_type |
Označuje hodnotu typu tokenu. Jediným typem, který Microsoft Entra ID podporuje, je Bearer. |
expires_in |
Jak dlouho je přístupový token platný v sekundách. |
scope |
Obory, pro které access_token platí. Nepovinné. Tento parametr není standardní a pokud tento parametr vynecháte, je token určený pro obory požadované na počáteční noze toku. |
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é. Můžou udržovat přístup k prostředkům po delší období. Další podrobnosti o aktualizaci přístupového tokenu najdete v části Aktualizace přístupového tokenu dále v tomto článku. Poznámka: Poskytuje se pouze v případě, že offline_access byl požadován rozsah. |
id_token |
Webový token JSON. 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 a důvěrní klienti můžou tento token použít k autorizaci. Další informace o id_tokens naleznete v tématu id_token reference. Poznámka: Poskytuje se pouze v případě, že openid byl požadován rozsah. |
Chybná odpověď
V tomto příkladu je odpověď chyba:
{
"error": "invalid_scope",
"error_description": "AADSTS70011: The provided value for the input parameter 'scope' is not valid. The scope https://foo.microsoft.com/mail.read is not valid.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: 2016-01-09 02:02:12Z",
"error_codes": [
70011
],
"timestamp": "2016-01-09 02:02:12Z",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
| Parametr | Popis |
|---|---|
error |
Řetězec kódu chyby, který lze použít ke klasifikaci typů chyb a k reakci na chyby. |
error_description |
Konkrétní chybová zpráva, která může vývojáři pomoct identifikovat příčinu chyby ověřování. |
error_codes |
Seznam kódů chyb specifických pro stS, které můžou pomoct s diagnostikou. |
timestamp |
Čas, kdy k chybě došlo. |
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 s diagnostikou napříč komponentami. |
Kódy chyb pro chyby koncového bodu tokenu
| Kód chyby | Popis | Akce klienta |
|---|---|---|
invalid_request |
Chyba protokolu, například chybějící požadovaný parametr. | Opravte žádost nebo registraci aplikace a znovu ji odešlete. |
invalid_grant |
Autorizační kód nebo ověřovatel kódu PKCE je neplatný nebo vypršela jeho platnost. | Vyzkoušejte nový požadavek na /authorize koncový bod a ověřte správnost parametru code_verifier . |
unauthorized_client |
Ověřený klient nemá oprávnění k použití tohoto typu udělení autorizace. | K této chybě obvykle dochází v případě, že klientská aplikace není zaregistrovaná v Microsoft Entra ID nebo není přidána do tenanta Microsoft Entra uživatele. Aplikace může vyzvat uživatele s pokyny k instalaci aplikace a jeho přidání do Microsoft Entra ID. |
invalid_client |
Ověření klienta se nezdařilo. | Přihlašovací údaje klienta nejsou platné. Pokud chcete tento problém vyřešit, aplikace Správa istrator aktualizuje přihlašovací údaje. |
unsupported_grant_type |
Autorizační server nepodporuje typ udělení autorizace. | Změňte typ grantu v žádosti. K tomuto typu chyby by mělo dojít pouze během vývoje a být zjištěn během počátečního testování. |
invalid_resource |
Cílový prostředek je neplatný, protože neexistuje, id Microsoft Entra ho nemůže najít nebo není správně nakonfigurované. | Tento kód označuje prostředek, pokud existuje, nebyl v tenantovi nakonfigurován. Aplikace může vyzvat uživatele s pokyny k instalaci aplikace a jeho přidání do Microsoft Entra ID. |
interaction_required |
Nestandardní, protože specifikace OIDC volá tento kód pouze na koncovém /authorize bodu. Požadavek vyžaduje interakci uživatele. Vyžaduje se například další krok ověřování. |
Opakujte /authorize požadavek se stejnými obory. |
temporarily_unavailable |
Server je dočasně příliš zaneprázdněný pro zpracování požadavku. | Zkuste požadavek zopakovat po malém zpoždění. Klientská aplikace může uživateli vysvětlit, že jeho odpověď je zpožděná kvůli dočasné podmínce. |
consent_required |
Žádost vyžaduje souhlas uživatele. Tato chyba není standardní. Obvykle se vrací pouze na /authorize koncový bod podle specifikací OIDC. Vráceno, když byl scope parametr použit v toku uplatnění kódu, že klientská aplikace nemá oprávnění k vyžádání. |
Klient by měl odeslat uživatele zpět do koncového /authorize bodu se správným oborem, aby se aktivoval souhlas. |
invalid_scope |
Rozsah požadovaný aplikací je neplatný. | Aktualizujte hodnotu parametru scope v požadavku na ověření na platnou hodnotu. |
Poznámka:
Jednostrákové aplikace můžou obdržet invalid_request chybu, která značí, že uplatnění tokenu mezi zdroji je povolené jenom pro typ klienta jednostrákovou aplikaci. To znamená, že identifikátor URI přesměrování použitý k vyžádání tokenu nebyl označen jako spa identifikátor URI přesměrování. Projděte si postup registrace aplikace, jak tento tok povolit.
Použití přístupového tokenu
Teď, když jste úspěšně získali access_tokentoken, můžete token použít v požadavcích na webová rozhraní API tak, že ho zahrnete do hlavičky Authorization :
GET /v1.0/me/messages
Host: https://graph.microsoft.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...
Aktualizace přístupového tokenu
Přístupové tokeny jsou krátkodobé. Aktualizujte je po vypršení platnosti a pokračujte v přístupu k prostředkům. Můžete to udělat odesláním další POST žádosti do koncového /token bodu. refresh_token Zadejte místo .code Obnovovací tokeny jsou platné pro všechna oprávnění, ke kterým už váš klient obdržel souhlas. Například obnovovací token vydaný na žádost scope=mail.read o použití k vyžádání nového přístupového tokenu pro scope=api://contoso.com/api/UseResource.
Obnovovací tokeny webových aplikací a nativních aplikací nemají zadané životnosti. Životnost obnovovacích tokenů je obvykle poměrně dlouhá. V některých případech však vyprší platnost obnovovacích tokenů, jsou odvolány nebo nemají dostatečná oprávnění pro akci. Vaše aplikace musí očekávat a zpracovat chyby vrácené koncovým bodem vystavení tokenu. Jednostrákové aplikace získávají token s 24hodinovou životností, což vyžaduje nové ověřování každý den. Tuto akci lze provést bezobslužně v prvku iframe, když jsou povolené soubory cookie třetích stran. Musí se provádět v rámečku nejvyšší úrovně, ať už v navigaci na celé stránce, nebo v automaticky otevíraných oknech v prohlížečích bez souborů cookie třetích stran, jako je Například Safari.
Obnovovací tokeny se při získávání nových přístupových tokenů neodvolá. Očekává se, že původní obnovovací token zahodíte. Specifikace OAuth 2.0 říká: "Autorizační server může vydat nový obnovovací token, v takovém případě musí klient zahodit starý obnovovací token a nahradit ho novým obnovovacím tokenem. Autorizační server může po vydání nového obnovovacího tokenu klientovi odvolat starý obnovovací token."
Důležité
U obnovovacích tokenů odeslaných na identifikátor URI přesměrování zaregistrovaný jako spavyprší platnost obnovovacího tokenu po 24 hodinách. Další obnovovací tokeny získané pomocí počátečního obnovovacího tokenu přenese tento čas vypršení platnosti, takže aplikace musí být připraveny znovu spustit tok autorizačního kódu pomocí interaktivního ověřování, aby získaly nový obnovovací token každých 24 hodin. Uživatelé nemusí zadávat svoje přihlašovací údaje a obvykle nevidí žádné uživatelské prostředí, pouze opětovné načtení aplikace. Prohlížeč musí navštívit přihlašovací stránku v rámci nejvyšší úrovně, aby se zobrazila relace přihlášení. Důvodem jsou funkce ochrany osobních údajů v prohlížečích, které blokují soubory cookie třetích stran.
// Line breaks for legibility only
POST /{tenant}/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read
&refresh_token=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq...
&grant_type=refresh_token
&client_secret=sampleCredentia1s // NOTE: Only required for web apps. This secret needs to be URL-Encoded
| 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. Platné hodnoty jsou common, organizations, consumersa identifikátory tenanta. Další informace najdete v tématu Koncové body. |
client_id |
povinné | ID aplikace (klienta), které centrum pro správu Microsoft Entra – Registrace aplikací prostředí přiřazené k vaší aplikaci. |
grant_type |
povinné | Musí být refresh_token pro tuto část toku autorizačního kódu. |
scope |
optional | Seznam oborů oddělených mezerami. Obory požadované v této noze musí být ekvivalentní nebo podmnožině oborů požadovaných v původní authorization_code noze požadavku. Pokud obory zadané v tomto požadavku zahrnují více serverů prostředků, vrátí platforma Microsoft Identity Platform token pro prostředek zadaný v prvním oboru. Další informace najdete v tématu Oprávnění a souhlas na platformě Microsoft Identity Platform. |
refresh_token |
povinné | Tok refresh_token , který jste získali ve druhé noze toku. |
client_secret |
vyžadováno pro webové aplikace | Tajný kód aplikace, který jste vytvořili na portálu pro registraci aplikací pro vaši aplikaci. Nemělo by se používat v nativní aplikaci, protože client_secret není možné spolehlivě ukládat na zařízeních. Vyžaduje se pro webové aplikace a webová rozhraní API, která můžou bezpečně ukládat client_secret na straně serveru. Tento tajný kód musí být zakódovaný v adrese URL. Další informace najdete ve specifikaci obecné syntaxe identifikátoru URI. |
Úspěšná odpověď
Tento příklad ukazuje úspěšnou odpověď tokenu:
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
"token_type": "Bearer",
"expires_in": 3599,
"scope": "https%3A%2F%2Fgraph.microsoft.com%2Fmail.read",
"refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
"id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctOD...",
}
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ěď
{
"error": "invalid_scope",
"error_description": "AADSTS70011: The provided value for the input parameter 'scope' is not valid. The scope https://foo.microsoft.com/mail.read is not valid.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: 2016-01-09 02:02:12Z",
"error_codes": [
70011
],
"timestamp": "2016-01-09 02:02:12Z",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
| Parametr | Popis |
|---|---|
error |
Řetězec kódu chyby, který lze použít ke klasifikaci typů chyb a 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 stS, které můžou pomoct s diagnostikou. |
timestamp |
Čas, kdy k chybě došlo. |
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 s diagnostikou napříč komponentami. |
Popis kódů chyb a doporučené akce klienta najdete v části Kódy chyb pro chyby koncového bodu tokenu.
Další kroky
- Projděte si ukázky MSAL JS a začněte psát kód.
- Seznamte se se scénáři výměny tokenů.