A Microsoft Identitásplatform és az OAuth 2.0 hitelesítési kódfolyamat

Az OAuth 2.0 engedélyezési kód megadásának típusa vagy hitelesítési kódfolyama lehetővé teszi, hogy az ügyfélalkalmazás jogosult hozzáférést kapjon a védett erőforrásokhoz, például a webes API-khoz. A hitelesítési kódfolyamathoz olyan felhasználói ügynök szükséges, amely támogatja az engedélyezési kiszolgálóról (a Microsoft Identitásplatform) való visszairányítást az alkalmazásba. Például egy olyan webböngésző, asztali vagy mobilalkalmazás, amelyet egy felhasználó üzemeltet az alkalmazásba való bejelentkezéshez és az adataik eléréséhez.

Ez a cikk csak a folyamat végrehajtásához szükséges nyers HTTP-kérések manuális létrehozásakor és kiállításakor szükséges alacsony szintű protokolladatokat ismerteti, amelyeket nem ajánlunk. Ehelyett használja a Microsoft által létrehozott és támogatott hitelesítési kódtárat a biztonsági jogkivonatok lekéréséhez és a védett webes API-k meghívásához az alkalmazásokban.

A hitelesítési kódfolyamatot támogató alkalmazások

A Kódcsere ellenőrző kulcsával (PKCE) és az OpenID Connecttel (OIDC) párosított hitelesítési kódfolyamat használatával szerezze be a hozzáférési jogkivonatokat és az azonosító jogkivonatokat az alábbi típusú alkalmazásokban:

• Egyoldalas webalkalmazás (SPA)
• Standard (kiszolgálóalapú) webalkalmazás
• Asztali és mobilalkalmazások

Protokoll részletei

Az OAuth 2.0 engedélyezési kódfolyamatát az OAuth 2.0 specifikációjának 4.1. szakasza ismerteti. Az OAuth 2.0 engedélyezési kód folyamatot használó alkalmazások megszereznek egy access_token-t, amelyet belefoglaltak olyan kérelmekbe, amelyek a Microsoft identitásplatform által védett erőforrásokra (általában API-kra) irányulnak. Az alkalmazások frissítési mechanizmussal új azonosítókat és hozzáférési jogkivonatokat is kérhetnek a korábban hitelesített entitásokhoz.

Ez az ábra a hitelesítési folyamat magas szintű nézetét mutatja be:

Átirányítási URI-k egyoldalas alkalmazásokhoz (SPA)

Az auth kódfolyamatot használó SLA-k átirányítási URI-i speciális konfigurációt igényelnek.

• Adjon hozzá egy átirányítási URI-t , amely támogatja a hitelesítési kódfolyamatot a PKCE-vel és a forrásközi erőforrás-megosztással (CORS): Kövesse az átirányítási URI lépéseit : MSAL.js 2.0 hitelesítésű kódfolyamattal.
• Frissítsen egy átirányítási URI-t: Az átirányítási URI type beállítása spa értékűre a Microsoft Entra Felügyeleti központ alkalmazásjegyzék-szerkesztőjével.

Az spa átirányítás típusa visszamenőlegesen kompatibilis az implicit folyamattal. Az implicit folyamatot jogkivonatok lekérésére jelenleg használó alkalmazások probléma nélkül áttérhetnek az spa átirányítási URI típusra, és folytathatják az implicit folyamatot. A visszamenőleges kompatibilitás ellenére javasoljuk, hogy használja a hitelesítési kódfolyamot a PKCE-vel az SLA-khoz.

Ha az engedélyezési kódfolyamatot anélkül próbálja meg használni, hogy beállítja a CORS-t az átirányítási URI-hoz, a következő hibaüzenet jelenik meg a konzolon:

access to XMLHttpRequest at 'https://login.microsoftonline.com/common/oauth2/v2.0/token' from origin 'yourApp.com' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.

Ha igen, keresse fel az alkalmazásregisztrációt, és frissítse az alkalmazás átirányítási URI-ját a spa típus használatára.

Az alkalmazások nem használhatnak spa átirányítási URI-t az SPA-n kívüli folyamatok esetén, például natív alkalmazások vagy ügyfél hitelesítési folyamatok esetében. A biztonság és az ajánlott eljárások érdekében a Microsoft identitásplatform hibaüzenetet ad vissza, ha megpróbál fejléc nélkül használni egy spa átirányítási URI-t Origin. Hasonlóképpen, a Microsoft Identitásplatform is megakadályozza az ügyfél hitelesítő adatainak használatát az összes folyamatban egy fejléc jelenlétébenOrigin, hogy a titkos kulcsok ne legyenek használatban a böngészőben.

Engedélyezési kód kérése

Az engedélyezési kód folyamata azzal kezdődik, hogy az ügyfél a végponthoz irányítja a felhasználót /authorize . Ebben a példakérésben az ügyfél a felhasználótól kéri a openid, offline_accessés https://graph.microsoft.com/mail.read az engedélyeket.

Egyes engedélyek rendszergazdai korlátozással vannak korlátozva, például adatok írása a szervezet címtárába a használatával Directory.ReadWrite.All. Ha az alkalmazás hozzáférést kér egy szervezeti felhasználótól ezen engedélyek egyikéhez, a felhasználó hibaüzenetet kap, amely szerint nem jogosult az alkalmazás engedélyeinek jóváhagyására. Ha hozzáférést szeretne kérni a rendszergazda által korlátozott hatókörökhöz, közvetlenül egy globális rendszergazdától kell kérnie őket. További információ: Rendszergazda által korlátozott engedélyek.

Ha másként nincs megadva, az opcionális paraméterekhez nincs alapértelmezett érték. A kérések alapértelmezett viselkedése azonban kihagyja az opcionális paramétereket. Az alapértelmezett viselkedés az egyetlen jelenlegi felhasználó bejelentkezése, a fiókválasztó megjelenítése több felhasználó esetén, vagy a bejelentkezési oldal megjelenítése, ha nincsenek bejelentkezve felhasználók.

// 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

Ezen a ponton a rendszer felkéri a felhasználót, hogy adja meg a hitelesítő adatait, és fejezze be a hitelesítést. A Microsoft Identitásplatform azt is biztosítja, hogy a felhasználó hozzájárult a scope lekérdezési paraméterben megadott engedélyekhez. Ha a felhasználó egyik engedélyhez sem járult hozzá, megkéri a felhasználót, hogy járuljon hozzá a szükséges engedélyekhez. További információ: Engedélyek és hozzájárulás a Microsoft Identitásplatform.

Miután a felhasználó hitelesíti és hozzájárulást ad, a Microsoft Identitásplatform a megadott redirect_uriidőpontban választ ad vissza az alkalmazásra a paraméterben response_mode megadott módszerrel.

Sikeres válasz

Ez a példa egy sikeres választ mutat be a(z) response_mode=query használata után.

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

Akkor is kaphat azonosító jogkivonatot, ha kér egyet, és az implicit hozzáférés engedélyezve van az alkalmazásregisztrációban. Ezt a viselkedést néha hibrid folyamatnak is nevezik. Olyan keretrendszerek használják, mint a ASP.NET.

Hibaválasz

Hibajelentések is elküldhetők a redirect_uri-nek, hogy az alkalmazás megfelelően kezelhesse őket.

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

Az engedélyezési végpont hibáinak hibakódjai

Az alábbi táblázat a hibaválasz paraméterében error visszaadható különböző hibakódokat ismerteti.

Azonosító jogkivonat kérése vagy hibrid folyamat

Ha szeretné megtudni, hogy ki a felhasználó az engedélyezési kód beváltása előtt, gyakran előfordul, hogy az alkalmazások is kérnek azonosító jogkivonatot, amikor az engedélyezési kódot kérik. Ezt a megközelítést hibrid folyamatnak nevezzük, mivel az OIDC-t az OAuth2 engedélyezési kódfolyamattal keveri.

A hibrid áramlást gyakran használják webalkalmazásokban egy felhasználó oldalának megjelenítésére anélkül, hogy blokkolná a kód beváltását, különösen az ASP.NET-ben. A modellben az egyoldalas és a hagyományos webalkalmazások is kihasználják a kisebb késést.

A hibrid folyamat megegyezik a korábban ismertetett engedélyezési kódfolyamattal, de három kiegészítéssel. Ezen kiegészítések mindegyike szükséges az azonosító jogkivonatának lekéréséhez: új hatókörök, új response_type és új nonce lekérdezési paraméter.

// 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

A válasz mód használata fragment problémákat okoz az olyan webalkalmazások esetében, amelyek beolvasják a kódot az átirányításból. A böngészők nem adják át a töredéket a webkiszolgálónak. Ilyen helyzetekben az alkalmazásoknak válasz form_post móddal kell biztosítaniuk, hogy az összes adat a kiszolgálóra legyen elküldve.

Sikeres válasz

Az alábbi példa egy sikeres választ mutat be a response_mode=fragment használatával.

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

Kód beváltása hozzáférési jogkivonathoz

Minden bizalmas ügyfélnek lehetősége van az ügyfél titkos kulcsainak vagy tanúsítványának hitelesítő adatainak használatára. A szimmetrikus megosztott titkos kulcsokat a Microsoft Identitásplatform hozza létre. A tanúsítvány hitelesítő adatai a fejlesztő által feltöltött aszimmetrikus kulcsok. További információ: Microsoft Identitásplatform alkalmazáshitelesítési tanúsítvány hitelesítő adatai.

A legjobb biztonság érdekében javasoljuk a tanúsítvány hitelesítő adatainak használatát. A natív alkalmazásokat és egyoldalas alkalmazásokat tartalmazó nyilvános ügyfelek nem használhatnak titkos kódokat vagy tanúsítványokat egy engedélyezési kód beváltásakor. Mindig győződjön meg arról, hogy az átirányítási URI-k tartalmazzák az alkalmazás típusát, és egyediek.

Hozzáférési token igénylése a client_secret használatával

Most, hogy már beszerezett egy authorization_code-t, és a felhasználó engedélyt adott, beválthatja a code-t egy access_token-re az erőforráshoz. Küldjön egy POST kérést a /token végpontra a code beváltásához.

// 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.

Hozzáférési jogkivonat kérése tanúsítvány-hitelesítő adatokkal

// 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

A paraméterek megegyeznek a megosztott titkos kód kérésével, azzal a kivételrel, hogy a client_secret paramétert két paraméter váltja fel: a client_assertion_type és client_assertion.

Sikeres válasz

Ez a példa egy sikeres token-választ mutat be:

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

Hibaválasz

Ez a példa egy hibaválasz:

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

Token-végpont hibakódjai

A hozzáférési jogkivonat használata

Most, hogy sikeresen beszerezte a tokent access_token, használhatja a tokent a webes API-kra irányuló kérelmekben a fejlécbe Authorization történő beillesztéssel.

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

A hozzáférési jogkivonat frissítése

A hozzáférési jogkivonatok rövid élettartamúak. A lejáratuk után frissítse őket, hogy továbbra is hozzáférhessenek az erőforrásokhoz. Ezt úgy teheti meg, hogy egy másik POST kérést küld a /token végpontnak. A refresh_token-t adja meg a code helyett. A frissítési jogkivonatok minden olyan engedélyre érvényesek, amelyekhez az ügyfél már kapott hozzájárulást. Egy kérelemre scope=mail.read kiadott frissítési jogkivonat például használható új hozzáférési jogkivonat scope=api://contoso.com/api/UseResourceigénylésére.

A webalkalmazások és natív alkalmazások frissítő jogkivonatai nem rendelkeznek megadott élettartammal. A frissítési jogkivonatok élettartama általában viszonylag hosszú. Bizonyos esetekben azonban a frissítési jogkivonatok lejárnak, visszavonják vagy nem rendelkeznek megfelelő jogosultságokkal a művelethez. Az alkalmazásnak a jogkivonat kiállítási végpontja által visszaadott hibákat kell várnia és kezelnie. Az egyoldalas alkalmazások egy 24 órás élettartamú jogkivonatot kapnak, amely minden nap új hitelesítést igényel. Ez a művelet csendesen elvégezhető egy iframe-ben, ha a harmadik féltől származó cookie-k engedélyezve vannak. Ezt egy legfelső szintű keretben kell elvégezni, akár teljes oldalú navigációban, akár előugró ablakban, külső cookie-kat nem tartalmazó böngészőkben, például a Safariban.

A frissítési jogkivonatok nem lesznek visszavonva új hozzáférési jogkivonatok beszerzésekor. Elvárás, hogy dobd el a régi frissítési token-t. Az OAuth 2.0 specifikációja a következőt mondja: "Az engedélyezési kiszolgáló új frissítési jogkivonatot bocsát ki, ebben az esetben az ügyfélnek el kell vetnie a régi frissítési jogkivonatot, és le kell cserélnie az új frissítési jogkivonatra. Az engedélyezési kiszolgáló visszavonhatja a régi frissítési jogkivonatot, miután új frissítési jogkivonatot adott ki az ügyfélnek."

// 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

Sikeres válasz

Ez a példa egy sikeres token választ mutat be.

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

Hibaválasz

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

A hibakódok és az ajánlott ügyfélművelet leírásáért tekintse meg a jogkivonatvégpontok hibáinak hibakódjait.

Következő lépések

• A kódolás megkezdéséhez tekintse át az MSAL JS-mintákat .
• Tudnivalók a jogkivonatok cseréjének forgatókönyveiről.