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ódfolyamatot használó alkalmazások a Microsoft Identitásplatform (általában API-k) által védett erőforrásokra irányuló kérelmekbe való belefoglalást kérnekaccess_token. 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.
- Átirányítási URI frissítése: Állítsa be az átirányítási URI-t
typespaa 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/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.
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 nem SPA-folyamatokkal, például natív alkalmazásokkal vagy ügyfél hitelesítő adatokkal. A biztonság és az ajánlott eljárások biztosítása érdekében a Microsoft Identitásplatform hibaüzenetet ad vissza, ha fejléc nélkül Origin próbál átirányítási URI-t használnispa. 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
| Paraméter | Kötelező/nem kötelező | Leírás |
|---|---|---|
tenant |
kötelező | A {tenant} kérés elérési útjának értéke határozza meg, hogy ki jelentkezhet be az alkalmazásba. Az érvényes értékek a common, organizationsés consumersa bérlőazonosítók. Olyan vendégforgatókönyvek esetén, amikor egy felhasználót egy bérlőről egy másik bérlőbe ír alá, meg kell adnia a bérlőazonosítót, hogy bejelentkeztethesse őket az erőforrás-bérlőbe. További információ: Végpontok. |
client_id |
kötelező | Az alkalmazás (ügyfél) azonosítója, amelyet a Microsoft Entra felügyeleti központ – Alkalmazásregisztrációk alkalmazáshoz rendelt felhasználói felület. |
response_type |
kötelező | Az engedélyezési kód folyamatának tartalmaznia code kell. A hibrid folyamatot is belefoglalhatja id_token vagy token használhatja. |
redirect_uri |
kötelező | Az redirect_uri alkalmazás, ahol a hitelesítési válaszokat elküldheti és fogadhatja az alkalmazás. Ennek pontosan meg kell egyeznie a Microsoft Entra felügyeleti központban regisztrált átirányítási URI-k egyikével, kivéve, hogy URL-kóddal kell rendelkeznie. Natív és mobilalkalmazások esetén használja az egyik ajánlott értéket: https://login.microsoftonline.com/common/oauth2/nativeclient beágyazott böngészőt használó alkalmazásokhoz vagy http://localhost rendszerböngészőket használó alkalmazásokhoz. |
scope |
kötelező | Azoknak a hatóköröknek a szóközzel tagolt listája, amelyeket a felhasználónak engedélyeznie kell. /authorize A kérelem lábához ez a paraméter több erőforrást is lefedhet. Ez az érték lehetővé teszi, hogy az alkalmazás jóváhagyást kapjon több meghívni kívánt webes API-hoz. |
response_mode |
ajánlott | Meghatározza, hogy az identitásplatform hogyan adja vissza a kért jogkivonatot az alkalmazásnak. Támogatott értékek: - query: Hozzáférési jogkivonat kérésekor alapértelmezés. A kódot lekérdezési sztringparaméterként adja meg az átirányítási URI-n. A query paraméter nem támogatott, ha azonosító jogkivonatot kér az implicit folyamat használatával. - fragment: Alapértelmezett, ha az implicit folyamat használatával kér egy azonosító jogkivonatot. Akkor is támogatott, ha csak egy kódot kér.- form_post: Végrehajt egy POST-et, amely tartalmazza a kódot az átirányítási URI-nak. Kód kérése esetén támogatott. |
state |
ajánlott | A kérésben szereplő érték, amelyet a jogkivonat válasza is visszaad. Tetszőleges tartalom sztringje lehet. A véletlenszerűen generált egyedi érték általában a helyek közötti hamisítási támadások megelőzésére szolgál. Az érték a felhasználó állapotával kapcsolatos információkat is kódolhatja az alkalmazásban a hitelesítési kérés előtt. Kódolhatja például azt a lapot vagy nézetet, amelyen voltak. |
prompt |
választható | A szükséges felhasználói beavatkozás típusát jelzi. Az érvényes értékek a következőklogin: , noneconsentés select_account.- prompt=login kényszeríti a felhasználót, hogy adja meg a hitelesítő adatait a kéréshez, és ne kapcsolja be az egyszeri bejelentkezést.- prompt=none az ellenkezője. Biztosítja, hogy a felhasználó ne jelenjen meg interaktív üzenettel. Ha a kérés nem hajtható végre csendben egyszeri bejelentkezéssel, a Microsoft Identitásplatform hibát interaction_required ad vissza.- prompt=consent aktiválja az OAuth hozzájárulási párbeszédpanelt, miután a felhasználó bejelentkezett, és megkéri a felhasználót, hogy adjon engedélyeket az alkalmazásnak.- prompt=select_account megszakítja az egyszeri bejelentkezést, így a fiókválasztási felület felsorolja az összes fiókot a munkamenetben, vagy bármely megjegyezett fiókot, vagy egy másik fiók teljes használatára vonatkozó lehetőséget. |
login_hint |
választható | Ezzel a paraméterlel előre kitöltheti a felhasználó bejelentkezési oldalának felhasználónevét és e-mail-címét. Az alkalmazások az újrahitelesítés során használhatják ezt a paramétert, miután már kinyerték az login_hint opcionális jogcímet egy korábbi bejelentkezésből. |
domain_hint |
választható | Ha tartalmazza, az alkalmazás kihagyja az e-mail-alapú felderítési folyamatot, amelyen a felhasználó végighalad a bejelentkezési oldalon, ami kissé leegyszerűsített felhasználói élményt eredményez. Például elküldheti őket az összevont identitásszolgáltatónak. Az alkalmazások ezt a paramétert az újrahitelesítés során használhatják egy korábbi bejelentkezésből kinyerve tid . |
code_challenge |
ajánlott /kötelező | Az engedélyezési kód megadásának védelmére szolgál a Code Exchange -hez (PKCE) készült Proof Key használatával. Kötelező, ha code_challenge_method szerepel benne. További információ: PKCE RFC. Ez a paraméter mostantól minden alkalmazástípushoz ajánlott, mind a nyilvános, mind a bizalmas ügyfelek számára, és a Microsoft Identitásplatform megköveteli az engedélyezési kódfolyamatot használó egyoldalas alkalmazásokhoz. |
code_challenge_method |
ajánlott /kötelező | A paraméter kódolásához code_verifier code_challenge használt módszer. Ennek kell lennieS256, de a specifikáció lehetővé teszi annak használatátplain, ha az ügyfél nem tudja támogatni az SHA256-ot. Ha ki van zárva, akkor a rendszer egyszerű szövegnek számít, code_challenge ha code_challenge szerepel benne. A Microsoft Identitásplatform támogatja mind plain a S256. További információ: PKCE RFC. Ez a paraméter az engedélyezési kódfolyamatot használó egyoldalas alkalmazásokhoz szükséges. |
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 következő használatával response_mode=query:
GET http://localhost?
code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&state=12345
| Paraméter | Leírás |
|---|---|
code |
Az authorization_code alkalmazás által kért. Az alkalmazás az engedélyezési kód használatával kérheti le a hozzáférési jogkivonatot a célerőforráshoz. Az engedélyezési kódok rövid élettartamúak. Általában körülbelül 10 perc elteltével lejárnak. |
state |
Ha egy state paraméter szerepel a kérelemben, akkor ugyanaz az érték jelenik meg a válaszban. Az alkalmazásnak ellenőriznie kell, hogy a kérés és a válasz állapotértékei azonosak-e. |
Akkor is kaphat azonosító jogkivonatot, ha kér egyet, és az implicit engedélyezé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
A hibaválaszokat is elküldheti a rendszer, redirect_uri hogy az alkalmazás megfelelően kezelje őket:
GET http://localhost?
error=access_denied
&error_description=the+user+canceled+the+authentication
| Paraméter | Leírás |
|---|---|
error |
Hibakódsztring, amely a hibák típusainak besorolására és a hibákra való reagálásra használható. A hiba ezen része azért van megadva, hogy az alkalmazás megfelelően reagáljon a hibára, de nem magyarázza meg részletesen, hogy miért történt hiba. |
error_description |
Egy adott hibaüzenet, amely segíthet a fejlesztőknek a hitelesítési hiba okának azonosításában. A hiba ezen része a hiba okával kapcsolatos legtöbb hasznos információt tartalmazza. |
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.
| Hibakód | Leírás | Ügyfélművelet |
|---|---|---|
invalid_request |
Protokollhiba, például hiányzó kötelező paraméter. | Javítsa ki és küldje el újra a kérést. Ez a hiba általában a kezdeti tesztelés során észlelt fejlesztési hiba. |
unauthorized_client |
Az ügyfélalkalmazás nem kérhet engedélyezési kódot. | Ez a hiba általában akkor fordul elő, ha az ügyfélalkalmazás nincs regisztrálva a Microsoft Entra-azonosítóban, vagy nem kerül a felhasználó Microsoft Entra-bérlőjére. Az alkalmazás megkérheti a felhasználót az alkalmazás telepítésére és a Microsoft Entra-azonosítóhoz való hozzáadására vonatkozó utasítással. |
access_denied |
Az erőforrás tulajdonosa megtagadta a hozzájárulást | Az ügyfélalkalmazás értesítheti a felhasználót, hogy csak akkor folytathatja a műveletet, ha a felhasználó beleegyezik. |
unsupported_response_type |
Az engedélyezési kiszolgáló nem támogatja a kérés választípusát. | Javítsa ki és küldje el újra a kérést. Ez a hiba általában a kezdeti tesztelés során észlelt fejlesztési hiba. A hibrid folyamatban ez a hiba azt jelzi, hogy engedélyeznie kell az azonosító jogkivonat implicit engedélyezési beállítását az ügyfélalkalmazás-regisztrációban. |
server_error |
A kiszolgáló váratlan hibát észlelt. | Ismételje meg a kérést. Ezek a hibák átmeneti feltételekből adódhatnak. Az ügyfélalkalmazás elmagyarázhatja a felhasználónak, hogy a válasza ideiglenes hibára késik. |
temporarily_unavailable |
A kiszolgáló átmenetileg túl elfoglalt a kérés kezeléséhez. | Ismételje meg a kérést. Az ügyfélalkalmazás elmagyarázhatja a felhasználónak, hogy a válasza egy ideiglenes feltétel miatt késik. |
invalid_resource |
A célerőforrás érvénytelen, mert nem létezik, a Microsoft Entra-azonosító nem találja, vagy nincs megfelelően konfigurálva. | Ez a hiba azt jelzi, hogy az erőforrás , ha létezik, nem lett konfigurálva a bérlőben. Az alkalmazás megkérheti a felhasználót az alkalmazás telepítésére és a Microsoft Entra-azonosítóhoz való hozzáadására vonatkozó utasítással. |
login_required |
Túl sok vagy nem található felhasználó. | Az ügyfél csendes hitelesítést kért (prompt=none), de egyetlen felhasználó nem található. Ez a hiba azt jelentheti, hogy több felhasználó is aktív a munkamenetben, vagy nincs felhasználó. Ez a hiba figyelembe veszi a kiválasztott bérlőt. Ha például két Aktív Microsoft Entra-fiók és egy Microsoft-fiók van kiválasztva, consumers a csendes hitelesítés működik. |
interaction_required |
A kérés felhasználói beavatkozást igényel. | Egy másik hitelesítési lépésre vagy hozzájárulásra van szükség. Próbálkozzon újra a kéréssel prompt=none. |
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 folyamatot gyakran használják webalkalmazásokban egy felhasználó lapjának megjelenítésére anélkül, hogy blokkolná a kód beváltását, különösen ASP.NET. 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
| Frissített paraméter | Kötelező/nem kötelező | Leírás |
|---|---|---|
response_type |
kötelező | A hozzáadás id_token azt jelzi a kiszolgálónak, hogy az alkalmazás egy azonosító jogkivonatot szeretne a végpont válaszában /authorize . |
scope |
kötelező | Az azonosító jogkivonatok esetében ezt a paramétert frissíteni kell, hogy tartalmazza az azonosító jogkivonat hatóköreit: openid és opcionálisan profile és email. |
nonce |
kötelező | Az alkalmazás által létrehozott kérelemben szereplő érték, amely az eredményként id_token kapott jogcímben szerepel. Az alkalmazás ezután ellenőrizheti ezt az értéket a jogkivonatok visszajátszási támadásainak csökkentése érdekében. Az érték általában véletlenszerű, egyedi sztring, amely a kérés eredetének azonosítására használható. |
response_mode |
ajánlott | Megadja azt a metódust, amellyel az eredményül kapott jogkivonatot vissza kell küldeni az alkalmazásnak. Az alapértelmezett érték query csak egy engedélyezési kódra vonatkozik, de fragment ha a kérelem tartalmaz egy id_token response_type , az OpenID-specifikációban megadott értéket. Javasoljuk, hogy az alkalmazásokat használja form_post, különösen átirányítási URI-ként való használat http://localhost esetén. |
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
Ez a példa egy sikeres választ mutat be a következő használatával response_mode=fragment:
GET https://login.microsoftonline.com/common/oauth2/nativeclient#
code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&id_token=eYj...
&state=12345
| Paraméter | Leírás |
|---|---|
code |
Az alkalmazás által kért engedélyezési kód. Az alkalmazás az engedélyezési kód használatával kérheti le a hozzáférési jogkivonatot a célerőforráshoz. Az engedélyezési kódok rövid élettartamúak, általában körülbelül 10 perc elteltével lejárnak. |
id_token |
A felhasználó azonosító jogkivonata, amelyet az implicit támogatással adnak ki. Egy különleges c_hash jogcímet tartalmaz, amely ugyanazon kérelem kivonata code . |
state |
Ha egy state paraméter szerepel a kérelemben, akkor ugyanaz az érték jelenik meg a válaszban. Az alkalmazásnak ellenőriznie kell, hogy a kérés és a válasz állapotértékei azonosak-e. |
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 jogkivonat kérése client_secret
Most, hogy beszerzett egy authorization_code , a felhasználó által megadott engedélyt, beválthatja az code erőforrásra access_token . Váltsa be a code következőt a POST végpontra /token küldött kéréssel:
// 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.
| Paraméter | Kötelező/nem kötelező | Leírás |
|---|---|---|
tenant |
kötelező | A {tenant} kérés elérési útjának értéke határozza meg, hogy ki jelentkezhet be az alkalmazásba. Az érvényes értékek a common, organizationsés consumersa bérlőazonosítók. További információ: Végpontok. |
client_id |
kötelező | Az alkalmazás (ügyfél) azonosítója, amelyet a Microsoft Entra Felügyeleti központ – Alkalmazásregisztrációk alkalmazáshoz rendelt lap. |
scope |
választható | A hatókörök szóközzel elválasztott listája. A hatóköröknek egyetlen erőforrásból kell származnia, az OIDC-hatókörökkel (profile, , openid). email További információ: Engedélyek és hozzájárulás a Microsoft Identitásplatform. Ez a paraméter egy Microsoft-bővítmény az engedélyezési kód folyamatához, amely lehetővé teszi az alkalmazások számára, hogy deklarálják a jogkivonathoz szükséges erőforrást a jogkivonat beváltása során. |
code |
kötelező | A authorization_code folyamat első szakaszában beszerzett. |
redirect_uri |
kötelező | Ugyanaz redirect_uri az érték, amelyet a authorization_code. |
grant_type |
kötelező | Az engedélyezési kód folyamatának kell lennie authorization_code . |
code_verifier |
ajánlott | Ugyanaz code_verifier , mint a authorization_code beszerzéséhez. Kötelező, ha a PKCE-t az engedélyezési kód megadására vonatkozó kérelemben használták. További információ: PKCE RFC. |
client_secret |
bizalmas webalkalmazásokhoz szükséges | Az alkalmazásregisztrációs portálon az alkalmazásregisztrációs portálon létrehozott alkalmazáskulcs. Ne használja az alkalmazás titkos kódját natív vagy egyoldalas alkalmazásokban, mert client_secret nem lehet megbízhatóan tárolni az eszközöket vagy weblapokat. Ez szükséges a webalkalmazásokhoz és a webes API-khoz, amelyek biztonságosan tárolhatják a client_secret kiszolgálóoldalon. Az összes paraméterhez hasonlóan az ügyfél titkos kódjának URL-kódolásúnak kell lennie az elküldés előtt. Ezt a lépést az SDK végzi. Az URI kódolásával kapcsolatos további információkért tekintse meg az URI Általános szintaxis specifikációját. Az RFC 6749-es verziójában a hitelesítő adatok megadása helyett az alapszintű hitelesítési minta is támogatott. |
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
| Paraméter | Kötelező/nem kötelező | Leírás |
|---|---|---|
tenant |
kötelező | A {tenant} kérés elérési útjának értéke határozza meg, hogy ki jelentkezhet be az alkalmazásba. Az érvényes értékek a common, organizationsés consumersa bérlőazonosítók. További részletekért lásd : Végpontok. |
client_id |
kötelező | Az alkalmazás (ügyfél) azonosítója, amelyet a Microsoft Entra Felügyeleti központ – Alkalmazásregisztrációk alkalmazáshoz rendelt lap. |
scope |
választható | A hatókörök szóközzel elválasztott listája. A hatóköröknek egyetlen erőforrásból kell származnia, az OIDC-hatókörökkel (profile, , openid). email További információkért tekintse meg az engedélyeket, a hozzájárulásokat és a hatóköröket. Ez a paraméter egy Microsoft-bővítmény az engedélyezési kód folyamatához. Ez a bővítmény lehetővé teszi az alkalmazások számára, hogy deklarálják azt az erőforrást, amelyhez a jogkivonatot használni szeretnék a jogkivonat beváltása során. |
code |
kötelező | A authorization_code folyamat első szakaszában beszerzett. |
redirect_uri |
kötelező | Ugyanaz redirect_uri az érték, amelyet a authorization_code. |
grant_type |
kötelező | Az engedélyezési kód folyamatának kell lennie authorization_code . |
code_verifier |
ajánlott | Ugyanaz code_verifier , mint a authorization_code. Kötelező, ha a PKCE-t az engedélyezési kód megadására vonatkozó kérelemben használták. További információ: PKCE RFC. |
client_assertion_type |
bizalmas webalkalmazásokhoz szükséges | Az értéket úgy kell beállítani, hogy urn:ietf:params:oauth:client-assertion-type:jwt-bearer tanúsítvány-hitelesítő adatokat használjon. |
client_assertion |
bizalmas webalkalmazásokhoz szükséges | Egy JSON webes jogkivonat (JWT), amelyet létre kell hoznia és alá kell írnia az alkalmazás hitelesítő adataiként regisztrált tanúsítvánnyal. A tanúsítvány hitelesítő adatairól a tanúsítvány regisztrálásának módjáról és az állítás formátumáról olvashat. |
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 jogkivonat-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..."
}
| Paraméter | Leírás |
|---|---|
access_token |
A kért hozzáférési jogkivonat. Az alkalmazás ezzel a jogkivonattal hitelesítheti magát a védett erőforráson, például egy webes API-val. |
token_type |
A jogkivonat típusértékét jelzi. A Microsoft Entra ID által támogatott egyetlen típus a Bearer. |
expires_in |
Mennyi ideig érvényes a hozzáférési jogkivonat másodpercben. |
scope |
Azok a hatókörök, amelyekre érvényes access_token . Opcionális. Ez a paraméter nem szabványos, és ha nincs megadva, a jogkivonat a folyamat kezdeti szakaszában kért hatókörökhöz tartozik. |
refresh_token |
OAuth 2.0 frissítési jogkivonat. Az alkalmazás ezt a jogkivonatot használhatja más hozzáférési jogkivonatok beszerzésére az aktuális hozzáférési jogkivonat lejárta után. A frissítési jogkivonatok hosszú élettartamúak. Hosszabb ideig fenntarthatják az erőforrásokhoz való hozzáférést. A hozzáférési jogkivonat frissítésével kapcsolatos további információkért tekintse meg a hozzáférési jogkivonat frissítését a cikk későbbi részében. Megjegyzés: Csak akkor van megadva, ha offline_access a hatókört kérték. |
id_token |
Egy JSON webes jogkivonat. Az alkalmazás dekódolhatja ennek a jogkivonatnak a szegmenseit, hogy információt kérjen a bejelentkezett felhasználóról. Az alkalmazás gyorsítótárazza és megjeleníti az értékeket, a bizalmas ügyfelek pedig ezt a jogkivonatot használhatják az engedélyezéshez. A id_tokens kapcsolatos további információkért lásd a id_token reference. Megjegyzés: Csak akkor van megadva, ha openid a hatókört kérték. |
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"
}
| Paraméter | Leírás |
|---|---|
error |
Hibakódsztring, amely a hibák típusainak besorolására és a hibákra való reagálásra használható. |
error_description |
Egy adott hibaüzenet, amely segíthet a fejlesztőknek a hitelesítési hiba okának azonosításában. |
error_codes |
Az STS-specifikus hibakódok listája, amelyek segíthetnek a diagnosztikában. |
timestamp |
A hiba előfordulásának időpontja. |
trace_id |
A kérés egyedi azonosítója, amely segíthet a diagnosztikában. |
correlation_id |
A kérés egyedi azonosítója, amely segíthet az összetevők közötti diagnosztikában. |
Jogkivonatvégpontok hibáinak hibakódjai
| Hibakód | Leírás | Ügyfélművelet |
|---|---|---|
invalid_request |
Protokollhiba, például hiányzó kötelező paraméter. | Javítsa ki a kérést vagy az alkalmazásregisztrációt, és küldje el újra a kérést. |
invalid_grant |
Az engedélyezési kód vagy A PKCE-kód ellenőrzője érvénytelen vagy lejárt. | Próbálkozzon egy új kéréssel a /authorize végponthoz, és ellenőrizze, hogy a code_verifier paraméter helyes volt-e. |
unauthorized_client |
A hitelesített ügyfél nem jogosult erre az engedélyezési engedélyezési típusra. | Ez a hiba általában akkor fordul elő, ha az ügyfélalkalmazás nincs regisztrálva a Microsoft Entra-azonosítóban, vagy nem kerül a felhasználó Microsoft Entra-bérlőjére. Az alkalmazás megkérheti a felhasználót az alkalmazás telepítésére és a Microsoft Entra-azonosítóhoz való hozzáadására vonatkozó utasítással. |
invalid_client |
Az ügyfélhitelesítés nem sikerült. | Az ügyfél hitelesítő adatai érvénytelenek. A javításhoz az alkalmazásadminisztrátor frissíti a hitelesítő adatokat. |
unsupported_grant_type |
Az engedélyezési kiszolgáló nem támogatja az engedélyezési engedélyezési típust. | Módosítsa a támogatási típust a kérelemben. Ez a hibatípus csak a fejlesztés során fordulhat elő, és az első tesztelés során észlelhető. |
invalid_resource |
A célerőforrás érvénytelen, mert nem létezik, a Microsoft Entra-azonosító nem találja, vagy nincs megfelelően konfigurálva. | Ez a kód azt jelzi, hogy az erőforrás , ha létezik, nem lett konfigurálva a bérlőben. Az alkalmazás megkérheti a felhasználót az alkalmazás telepítésére és a Microsoft Entra-azonosítóhoz való hozzáadására vonatkozó utasítással. |
interaction_required |
Nem szabványos, mivel az OIDC-specifikáció csak a végponton kéri ezt a /authorize kódot. A kérés felhasználói beavatkozást igényel. Például egy másik hitelesítési lépésre van szükség. |
Próbálkozzon újra a /authorize kéréssel ugyanazokkal a hatókörökkel. |
temporarily_unavailable |
A kiszolgáló átmenetileg túl elfoglalt a kérés kezeléséhez. | Kis késés után próbálkozzon újra a kéréssel. Az ügyfélalkalmazás elmagyarázhatja a felhasználónak, hogy a válasza egy ideiglenes feltétel miatt késik. |
consent_required |
A kéréshez felhasználói hozzájárulás szükséges. Ez a hiba nem szabványos. Általában csak a /authorize végponton adja vissza OIDC-specifikációnként. Akkor lett visszaadva, amikor egy scope paramétert használtak a kód beváltásához, amelyet az ügyfélalkalmazás nem kérhet le. |
Az ügyfélnek vissza kell küldenie a felhasználót a /authorize végpontra a megfelelő hatókörrel a hozzájárulás aktiválásához. |
invalid_scope |
Az alkalmazás által kért hatókör érvénytelen. | Frissítse a scope paraméter értékét egy érvényes értékre a hitelesítési kérelemben. |
Feljegyzés
Az egyoldalas alkalmazások hibaüzenetet invalid_request kaphatnak, amely azt jelzi, hogy a többoldalas jogkivonat beváltása csak az "egyoldalas alkalmazás" ügyféltípus esetében engedélyezett. Ez azt jelzi, hogy a jogkivonat kéréséhez használt átirányítási URI nem lett átirányítási URI-ként spa megjelölve. Tekintse át a folyamat engedélyezésének alkalmazásregisztrációs lépéseit .
A hozzáférési jogkivonat használata
Most, hogy sikeresen beszerezte a jogkivonatot access_token, használhatja a jogkivonatot a webes API-kra irányuló kérelmekben a fejlécbe Authorization való beleszámítva:
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. Adja meg ahelyett, refresh_token hogy a code. 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 jogkivonatainak frissítése nem rendelkezik megadott élettartamokkal. 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. A régi frissítési jogkivonat elvetése várható. 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."
Fontos
A regisztrált átirányítási URI-nak spaküldött frissítési jogkivonatok esetében a frissítési jogkivonat 24 óra elteltével lejár. A kezdeti frissítési jogkivonattal beszerzett további frissítési jogkivonatok a lejárati időt is átviszik, ezért az alkalmazásoknak fel kell készülniük az engedélyezési kód folyamatának interaktív hitelesítéssel történő újrafuttatására, hogy 24 óránként új frissítési jogkivonatot kapjanak. A felhasználóknak nem kell megadniuk a hitelesítő adataikat, és általában nem is látnak felhasználói élményt, csak az alkalmazás újratöltését. A böngészőnek meg kell látogatnia a bejelentkezési oldalt egy felső szintű keretben a bejelentkezési munkamenet megtekintéséhez. Ez a harmadik féltől származó cookie-kat letiltó böngészők adatvédelmi funkcióinak köszönhető.
// 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
| Paraméter | Típus | Leírás |
|---|---|---|
tenant |
kötelező | A {tenant} kérés elérési útjának értéke határozza meg, hogy ki jelentkezhet be az alkalmazásba. Az érvényes értékek a common, organizationsés consumersa bérlőazonosítók. További információ: Végpontok. |
client_id |
kötelező | Az alkalmazás (ügyfél) azonosítója, amelyet a Microsoft Entra felügyeleti központ – Alkalmazásregisztrációk alkalmazáshoz rendelt felhasználói felület. |
grant_type |
kötelező | Az engedélyezési kód folyamatának ezen szakaszához kell lennie refresh_token . |
scope |
választható | A hatókörök szóközzel elválasztott listája. Az ebben a lábban kért hatóköröknek meg kell egyenrangúnak lenniük az eredeti authorization_code kérelemlábban kért hatókörök egy részhalmazával vagy egy részhalmazával. Ha a kérelemben megadott hatókörök több erőforrás-kiszolgálóra is kiterjednek, akkor a Microsoft Identitásplatform az első hatókörben megadott erőforrás jogkivonatát adja vissza. További információ: Engedélyek és hozzájárulás a Microsoft Identitásplatform. |
refresh_token |
kötelező | A refresh_token folyamat második szakaszában beszerzett. |
client_secret |
webalkalmazásokhoz szükséges | Az alkalmazásregisztrációs portálon az alkalmazásregisztrációs portálon létrehozott alkalmazáskulcs. Nem szabad natív alkalmazásokban használni, mert client_secret az eszközök nem tárolhatók megbízhatóan. Ez szükséges a webalkalmazásokhoz és a webes API-khoz, amelyek biztonságosan tárolhatják a client_secret kiszolgálóoldalon. Ennek a titkos kódnak URL-kódolásúnak kell lennie. További információkért tekintse meg az URI általános szintaxisának specifikációját. |
Sikeres válasz
Ez a példa egy sikeres jogkivonat-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..."
}
| Paraméter | Leírás |
|---|---|
access_token |
A kért hozzáférési jogkivonat. Az alkalmazás ezzel a jogkivonattal hitelesítheti magát a védett erőforráson, például egy webes API-val. |
token_type |
A jogkivonat típusértékét jelzi. A Microsoft Entra ID által támogatott egyetlen típus a Bearer. |
expires_in |
Mennyi ideig érvényes a hozzáférési jogkivonat másodpercben. |
scope |
Azok a hatókörök, amelyekre érvényes access_token . |
refresh_token |
Új OAuth 2.0 frissítési jogkivonat. Cserélje le a régi frissítési jogkivonatot erre az újonnan beszerzett frissítési jogkivonatra, hogy a frissítési jogkivonatok a lehető leghamarabb érvényesek maradjanak. Megjegyzés: Csak akkor van megadva, ha offline_access a hatókört kérték. |
id_token |
Egy aláíratlan JSON-webjogkivonat. Az alkalmazás dekódolhatja ennek a jogkivonatnak a szegmenseit, hogy információt kérjen a bejelentkezett felhasználóról. Az alkalmazás gyorsítótárazhatja az értékeket, és megjelenítheti őket, de nem támaszkodhat rájuk semmilyen engedélyezési vagy biztonsági határ esetén. További információid_token: Microsoft Identitásplatform azonosító jogkivonatok. Megjegyzés: Csak akkor van megadva, ha openid a hatókört kérték. |
Figyelmeztetés
Ne kísérelje meg a jogkivonatok érvényesítését vagy olvasását a kódban a nem birtokolt API-k esetében, beleértve az ebben a példában szereplő jogkivonatokat is. A Microsoft-szolgáltatások jogkivonatai olyan speciális formátumot használhatnak, amely nem érvényesíthető JWT-ként, és titkosíthatók a fogyasztói (Microsoft-fiók) felhasználók számára is. Bár a jogkivonatok olvasása hasznos hibakeresési és tanulási eszköz, ne vegyen fel függőségeket a kódban, és ne feltételezze a nem ön által vezérelt API-khoz tartozó jogkivonatokat.
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"
}
| Paraméter | Leírás |
|---|---|
error |
Hibakódsztring, amely a hibák típusainak besorolására és a hibákra való reagálásra használható. |
error_description |
Egy adott hibaüzenet, amely segíthet a fejlesztőknek a hitelesítési hibák kiváltó okának azonosításában. |
error_codes |
Az STS-specifikus hibakódok listája, amelyek segíthetnek a diagnosztikában. |
timestamp |
A hiba előfordulásának időpontja. |
trace_id |
A kérés egyedi azonosítója, amely segíthet a diagnosztikában. |
correlation_id |
A kérés egyedi azonosítója, amely segíthet az összetevők közötti diagnosztikában. |
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.