Microsoft identity platform a tok autorizačního kódu OAuth 2.0

Udělení autorizačního kódu OAuth 2.0 je možné použít v aplikacích nainstalovaných na zařízení k získání přístupu k chráněným prostředkům, jako jsou webová rozhraní API. Pomocí Microsoft identity platform OAuth 2.0 a Open ID Připojení (OIDC) můžete do mobilních a desktopových aplikací přidat přihlášení a přístup přes rozhraní API.

Tento článek popisuje, jak programovat přímo pomocí protokolu v aplikaci pomocí libovolného jazyka. Pokud je to možné, doporučujeme k získání tokenů a volání zabezpečených webových rozhraní API použít podporované knihovny msal (Microsoft Authentication Libraries). Podívejte se také na ukázkové aplikace, které používají MSAL.

Tok autorizačního kódu OAuth 2.0 je popsaný v části 4.1 specifikace OAuth 2.0. S OIDC se používá k ověřování a autorizaci ve většině typů aplikací, včetně jedno stránek, webových aplikací a nativně nainstalovaných aplikací. Tok umožňuje aplikacím bezpečně získat access_tokens, které je možné použít pro přístup k prostředkům zabezpečeným službou Microsoft identity platform, a také aktualizovat tokeny pro získání dalších tokenů access_tokens a tokenů ID pro přihlášeného uživatele.

Diagram protokolu

Na vysoké úrovni celý tok ověřování pro aplikaci vypadá trochu takhle:

Nastavení identifikátoru URI přesměrování vyžadované pro jedno stránkované aplikace

Tok autorizačního kódu pro jedno stránkovací aplikace vyžaduje další nastavení. Pokud chcete správně označit identifikátor URI přesměrování jako povolený pro CORS, postupujte podle pokynů pro vytvoření jedno stránkové aplikace. Pokud chcete aktualizovat existující identifikátor URI přesměrování pro povolení CORS, otevřete editor manifestu a v části nastavte pole pro identifikátor URI přesměrování type spa na replyUrlsWithType . Můžete také kliknout na identifikátor URI přesměrování v části Web na kartě Ověřování a vybrat identifikátory URI, na které chcete migrovat pomocí toku autorizačního kódu.

Typ spa přesměrování je zpětně kompatibilní s implicitním tokem. Aplikace, které k získání tokenů aktuálně používají implicitní tok, mohou přejít na typ identifikátoru URI přesměrování bez problémů a spa pokračovat v používání implicitního toku.

Pokud se pokusíte použít tok autorizačního kódu a zobrazí se 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.

Pak přejděte do registrace aplikace a aktualizujte identifikátor URI přesměrování, aby aplikace napište spa .

Aplikace nemohou identifikátor URI pro přesměrování používat s toky mimo spa, například nativní aplikace spa nebo toky přihlašovacích údajů klienta. V zájmu zajištění zabezpečení a osvědčených postupů vrátí platforma Microsoft Identity platform chybu, pokud se pokusíte použít identifikátor spa URI přesměrování bez Origin hlavičky. Podobně microsoft Identity Platform také brání použití přihlašovacích údajů klienta (v toku OBO, toku přihlašovacích údajů klienta a toku ověřovacího kódu) v přítomnosti hlavičky, aby se zajistilo, že se tajné kódy v prohlížeči nebudou Origin používat.

Žádost o autorizační kód

Tok autorizačního kódu začíná tím, že klient nasměruje uživatele do koncového /authorize bodu. V tomto požadavku si klient vyžádá od uživatele openid offline_access oprávnění , a https://graph.microsoft.com/mail.read . 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 jednomu z těchto oprávnění od uživatele organizace, uživateli se zobrazí chybová zpráva s oznámením, že nemá oprávnění udělit souhlas s oprávněními vaší aplikace. Pokud chcete požádat o přístup k oborům omezeným na správce, měli byste si je vyžádat přímo od globálního správce. Další informace najdete v informacích o oprávněních omezených správcem.

// Line breaks for legibility only

https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&response_type=code
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=query
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read%20api%3A%2F%2F
&state=12345
&code_challenge=YTFjNjI1OWYzMzA3MTI4ZDY2Njg5M2RkNmVjNDE5YmEyZGRhOGYyM2IzNjdmZWFhMTQ1ODg3NDcxY2Nl
&code_challenge_method=S256

V tomto okamžiku se uživateli zobrazí dotaz, jestli má zadat svoje přihlašovací údaje a dokončit ověření. Následující Microsoft identity platform také zajistí, že uživatel souhlasí s oprávněními uvedená v scope parametru dotazu. Pokud uživatel s žádným z těchto oprávnění nevysoudí souhlas, požádá ho o souhlas s požadovanými oprávněními. Podrobnosti o oprávněních, souhlasu a aplikacích s více tenanty najdete tady.

Jakmile se uživatel ověří a udělí souhlas, Microsoft identity platform vrátí vaší aplikaci odpověď na vyznačené adrese pomocí metody zadané redirect_uri v response_mode parametru .

Úspěšná odpověď

Úspěšná odpověď s response_mode=query použitím příkazu vypadá asi takhle:

GET http://localhost?
code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&state=12345

Token ID můžete získat také v případě, že si ho vyžádáte a při registraci aplikace máte implicitní udělení povolené. To se někdy označuje jako "hybridní tok"a používá se v architekturách, jako je ASP.NET.

Chybová odpověď

Chybové odpovědi je také možné odeslat do redirect_uri , aby je aplikace dokáže odpovídajícím způsobem zpracovat:

GET http://localhost?
error=access_denied
&error_description=the+user+canceled+the+authentication

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.

Vyžádání tokenu ID (hybridní tok)

Pokud chcete zjistit, kdo je uživatel před uplatněním autorizačního kódu, je běžné, že aplikace při žádosti o autorizační kód také žádají o token ID. To se nazývá hybridní tok, protože směšuje implicitní udělení s tokem autorizačního kódu. Hybridní tok se běžně používá ve webových aplikacích, které chtějí uživateli vykreslit stránku bez blokování při uplatnění kódu, zejména ASP.NET. Jedno stránkové aplikace i tradiční webové aplikace těží z nižší latence v tomto modelu.

Hybridní tok je stejný jako tok autorizačního kódu popsaný výše, ale se třemi doplňky, které jsou potřeba k vyžádání tokenu ID: nové obory, nový response_type a nový parametr nonce dotazu.

// Line breaks for legibility only

https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&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

Použití jako režimu odpovědi způsobí problémy webovým aplikacím, které čtou kód z přesměrování, protože prohlížeče fragment webovému serveru fragment předá. V takových situacích by aplikace měly používat režim odpovědi, aby se zajistilo, že se všechna data budou form_post na server odesílat.

Úspěšná odpověď

Úspěšná odpověď s response_mode=fragment použitím příkazu vypadá asi takhle:

GET https://login.microsoftonline.com/common/oauth2/nativeclient#
code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&id_token=eYj...
&state=12345

Uplatnění kódu pro přístupový token

Všichni důvěrní klienti mají možnost používat tajné kódy klienta (symetrické sdílené tajné kódy generované službou Microsoft identity platform) a přihlašovací údaje certifikátu (asymetrické klíče nahrané vývojářem). Pro zajištění nejlepšího zabezpečení doporučujeme použít přihlašovací údaje certifikátu. Veřejní klienti (nativní aplikace a jedno stránkovací 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 přesměrování správně označují typ aplikace a jsou jedinečné.

Vyžádání přístupového tokenu pomocí client_secret

Teď, když jste získali authorization_code a uživateli jste udělili oprávnění, můžete uplatnit na požadovaný code access_token prostředek. To proveďte odesláním POST požadavku 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=6731de76-14a6-49ae-97bc-6eba6914391e
&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=JqQX2PNo9bpM0uEihUPzyrh    // NOTE: Only required for web apps. This secret needs to be URL-Encoded.

Vyžádání přístupového tokenu pomocí přihlašovacích údajů certifikátu

POST /{tenant}/oauth2/v2.0/token HTTP/1.1               // Line breaks for clarity
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&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

Všimněte si, že parametry jsou stejné jako v případě požadavku sdíleným tajným kódem s tím rozdílem, že parametr je nahrazen dvěma client_secret parametry: a a client_assertion_type client_assertion .

Úspěšná odpověď

Úspěšná odpověď tokenu bude vypadat asi takhle:

{
    "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...",
}

Chybová odpověď

Odpovědi na chyby budou vypadat asi takhle:

{
  "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: 255d1aef-8c98-452f-ac51-23d051240864\r\nCorrelation ID: fb3d2015-bc17-4bb9-bb85-30c5cf1aaaa7\r\nTimestamp: 2016-01-09 02:02:12Z",
  "error_codes": [
    70011
  ],
  "timestamp": "2016-01-09 02:02:12Z",
  "trace_id": "255d1aef-8c98-452f-ac51-23d051240864",
  "correlation_id": "fb3d2015-bc17-4bb9-bb85-30c5cf1aaaa7"
}

Kódy chyb koncového bodu tokenu

Použití přístupového tokenu

Teď, když jste úspěšně získali access_token , můžete token v žádosti do webových rozhraní API použít tak, že ho zahrnete do Authorization hlavičky:

GET /v1.0/me/messages
Host: https://graph.microsoft.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...

Aktualizace přístupového tokenu

Access_tokens jsou krátkodobé a po vypršení jejich platnosti je musíte aktualizovat, aby bylo možné pokračovat v přístupu k prostředkům. Můžete to udělat tak, že odešlete další POST požadavek na /token koncový bod a tentokrát zadáte refresh_token místo code . Aktualizační tokeny jsou platné pro všechna oprávnění, která klient již obdržel souhlas. proto je scope=mail.read možné pro vyžádání nového přístupového tokenu použít obnovovací token vydaný na žádost pro scope=api://contoso.com/api/UseResource .

Aktualizace tokenů pro webové aplikace a nativní aplikace nemají zadané doby života. Obvykle jsou životnosti aktualizačních tokenů poměrně dlouhé. V některých případech ale platnost tokenů aktualizace vyprší, odvolají se nebo nemají dostatečná oprávnění pro požadovanou akci. Vaše aplikace musí očekávat a zpracovat chyby vrácené koncovým bodem vystavení tokenu správně. Jednostránkové aplikace ale získají token se 24 hodinovou životností, který vyžaduje nové ověřování každý den. To se dá udělat v tichém režimu v elementu IFRAME, pokud jsou povolené soubory cookie třetích stran, ale je potřeba je udělat v prohlížečích bez souborů cookie třetích stran, jako je Safari.

I když se tokeny aktualizace neodvolává při použití k získání nových přístupových tokenů, očekává se, že se starý obnovovací token zruší. Specifikace OAuth 2,0 říká: "AUTORIZAČNÍ Server může vydat nový obnovovací token. v takovém případě musí klient zrušit starý obnovovací token a nahradit ho novým obnovovacím tokenem. Po vydání nového obnovovacího tokenu klientovi může autorizační Server odvolat starý obnovovací token. "

// 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=535fb089-9ff3-47b6-9bfb-4f1264799865
&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

Úspěšná odpověď

Úspěšná odpověď tokenu bude vypadat takto:

{
    "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...",
}

Chybová odezva

{
  "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: 255d1aef-8c98-452f-ac51-23d051240864\r\nCorrelation ID: fb3d2015-bc17-4bb9-bb85-30c5cf1aaaa7\r\nTimestamp: 2016-01-09 02:02:12Z",
  "error_codes": [
    70011
  ],
  "timestamp": "2016-01-09 02:02:12Z",
  "trace_id": "255d1aef-8c98-452f-ac51-23d051240864",
  "correlation_id": "fb3d2015-bc17-4bb9-bb85-30c5cf1aaaa7"
}

Popis chybových kódů a doporučené akce klienta najdete v tématu kódy chyb pro chyby koncového bodu tokenu.