Microsoft Identitásplatform OAuth 2.0 engedélyezési kódfolyama

Az OAuth 2.0 engedélyezési kódengedély az eszközön telepített alkalmazásokban használható a védett erőforrásokhoz, például webes API-khoz való hozzáféréshez. Az OAuth 2.0 Microsoft Identitásplatform implementációja lehetővé teszi a bejelentkezés és az API-hozzáférés hozzáadását a mobil- és asztali alkalmazásokhoz.

Ez a cikk azt ismerteti, hogyan programolhat közvetlenül a protokollon az alkalmazásban bármilyen nyelv használatával. Ha lehetséges, javasoljuk, hogy a támogatott Microsoft Authentication Libraries (MSAL) használatával szerezzen be jogkivonatokat, és hívja meg a biztonságos webes API-kat. Emellett az MSAL-t tartalmazó mintaalkalmazásokat is nézze meg.

Az OAuth 2.0 engedélyezési kódfolyamot a OAuth 2.0 specifikáció 4.1-es szakaszában ismertetjük. A hitelesítéshez és engedélyezéshez használható az alkalmazástípusok többségében, beleértve az egyoldalas alkalmazásokat, a webalkalmazásokatés a natív módon telepített alkalmazásokat. A folyamat lehetővé teszi, hogy az alkalmazások biztonságosan szerezzenek be access_tokens-t, amely az Microsoft Identitásplatform által védett erőforrások eléréséhez használható, valamint frissítési jogkivonatokat a access_tokens és azonosító jogkivonatok lekérte a bejelentkezett felhasználóhoz.

Tipp

Próbálja meg a kérést a Postmanben is lefutni
Próbálja meg végrehajtani ezt a kérést és még sok minden más a Postmanben – ne felejtse el lecserélni a jogkivonatokat és az azonosítókat!

Protokolldiagram

Magas szinten az alkalmazás teljes hitelesítési folyamatának egy kicsit így kell néz ki:

OAuth-hitelesítési kód Flow

Átirányítási URI beállítása szükséges az egyoldalas alkalmazásokhoz

Az egyoldalas alkalmazások engedélyezési kódfolyamához további beállításokra van szükség. Kövesse az egyoldalas alkalmazás létrehozására vonatkozó utasításokat, hogy megfelelően megjelölje az átirányítási URI-t engedélyezettként a CORS-hoz. Ha frissíteni szeretné egy meglévő átirányítási URI-t a CORS engedélyezéséhez, nyissa meg a jegyzékszerkesztőt, és állítsa az átirányítási URI mezőjét a következőre a type spa replyUrlsWithType szakaszban: . A Hitelesítés lap "Web" szakaszában az átirányítási URI-t is választhatja, és kiválaszthatja azokat az URI-kat, amelyekre az engedélyezési kódfolyamot használni szeretné.

Az spa átirányítás típusa visszamenőlegesen kompatibilis az implicit folyamatokkal. A jogkivonatok lekért implicit folyamatával jelenleg az alkalmazások probléma nélkül továbbléphet az átirányítási URI-típusra, és folytathatja spa az implicit folyamat használatának folytatását.

Ha az engedélyezési kódfolyamot próbálja használni, és a következő hibaüzenet jelenik meg:

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.

Ezután látogasson el az alkalmazásregisztrációba, és frissítse az alkalmazás átirányítási URI-ját a spa beíráshoz.

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őadat-folyamatokkal. A biztonság és az ajánlott eljárások biztosítása érdekében a Microsoft Identity platform hibaüzenetet ad vissza, ha fejléc nélküli átirányítási spa URI-t próbál Origin használni. Hasonlóképpen, a Microsoft Identity platform megakadályozza az ügyfél-hitelesítő adatok használatát (az OBO-folyamatban, az ügyfél-hitelesítő adatok folyamatában és a hitelesítési kódfolyamban) fejlécek nélkül, hogy a titkos kódok ne legyenek használatban a Origin böngészőben.

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

Az engedélyezési kódfolyam azzal kezdődik, hogy az ügyfél a végpontra irányítja a /authorize felhasználót. Ebben a kérésben az ügyfél a , és engedélyeket openid offline_access kéri a https://graph.microsoft.com/mail.read felhasználótól. Egyes engedélyek rendszergazdai korlátozás alá vannak korlátozva, például adatok írása egy szervezet címtárába a Directory.ReadWrite.All használatával. Ha az alkalmazás hozzáférést kér ezen engedélyek egyikéhez egy szervezeti felhasználótól, a felhasználó egy hibaüzenetet kap, amely szerint nem jogosult az alkalmazás engedélyeinek igénylésére. A rendszergazda által korlátozott hatókörök hozzáférésének kérelmezését közvetlenül egy globális rendszergazdától kell igényelni. További információkért olvassa el a Rendszergazda által korlátozott engedélyek című témakört.

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

Tipp

Kattintson az alábbi hivatkozásra a kérés végrehajtásához! A bejelentkezést követően a böngészőnek át kell irányítania a címet http://localhost/myapp/ a code címsorba. https://login.microsoftonline.com/common/oauth2/v2.0/authorize...

Paraméter Kötelező/nem kötelező Description
tenant kötelező A kérés elérési útján található érték segítségével szabályozható, hogy ki {tenant} jelentkezhet be az alkalmazásba. Az engedélyezett értékek a common , organizations , és consumers bérlőazonosítók. További részletekért lásd a protokollok alapjait. Kritikus fontosságú, hogy olyan vendégforgatókönyvek esetén, amikor egy felhasználót az egyik bérlőből egy másik bérlőbe jelentkeztet be, meg kell adnia a bérlőazonosítót, hogy megfelelően bejelentkeztetje őket az erőforrás-bérlőbe.
client_id kötelező Az alkalmazás (ügyfél) azonosítója, Azure Portal – Alkalmazásregisztrációk alkalmazáshoz rendelt felhasználói élményt.
response_type kötelező Tartalmaznia kell code az engedélyezési kódfolyamhoz. A hibrid folyamatot is tartalmazhatja, vagy id_token ha a hibrid folyamatot token használja.
redirect_uri kötelező Az redirect_uri, ahol az alkalmazás elküldheti és megkaphatja a hitelesítési válaszokat. Pontosan meg kell egyeznie a portálon redirect_uris megadott url-címek egyikével, azzal a kivételvel, hogy URL-kódolásúnak kell lennie. Natív & esetén használja az ajánlott értékek valamelyikét – (beágyazott böngészőt használó alkalmazások esetén) vagy (rendszerböngészőt használó https://login.microsoftonline.com/common/oauth2/nativeclient http://localhost alkalmazások esetén).
scope kötelező Azon hatókörök szóközrel elválasztott listája, amelyekhez a felhasználó beleegyezését szeretné adni. A kérés első szakasza több erőforrást is lefedhet, így az alkalmazás több meghívni kívánt /authorize webes API-hoz is engedélyt kaphat.
response_mode Ajánlott Megadja a metódust, amely alapján az eredményül kapott jogkivonatot vissza kell küldeni az alkalmazásnak. A következők egyike lehet:

- query
- fragment
- form_post

query A lekérdezési sztring paraméterként biztosítja a kódot az átirányítási URI-ján. Ha az implicit folyamattal kér azonosító jogkivonatot, a nem használható az query OpenID specifikációban megadottak szerint. Ha csak a kódot kéri, használhatja a query , fragment vagy a form_post kódot. form_post végrehajt egy POST-et, amely tartalmazza a kódot az átirányítási URI-hoz.
state Ajánlott A kérésben szereplő érték, amely szintén a jogkivonat válaszában lesz visszaadva. Bármilyen kívánt tartalom sztringe lehet. A véletlenszerűen generált egyedi érték általában a webhelyközi kérések hamisítási támadásának megakadályozására használatos. Az érték a felhasználó alkalmazásbeli állapotára vonatkozó információkat is kódolhatja a hitelesítési kérelem beeste előtt, például az oldalt vagy a megtekintést, ahol voltak.
prompt választható A szükséges felhasználói beavatkozás típusát jelzi. Jelenleg az egyetlen érvényes érték a login , none , és consent select_account .

- prompt=login A kényszeríti a felhasználót, hogy a kéréshez adja meg a hitelesítő adatait, és ezzel ne adjon meg egyszeri bejelentkezést.
- prompt=none ennek az ellenkezője – ez biztosítja, hogy a felhasználó számára ne jelennek meg interaktív kérések. Ha a kérést nem lehet csendesen végrehajtani egyszeri bejelentkezésen keresztül, a Microsoft Identitásplatform hibát interaction_required fog visszaadni.
- prompt=consent A elindítja az OAuth-jóváhagyási párbeszédpanelt, miután a felhasználó bejelentkezik, és megkéri a felhasználót, hogy adjon engedélyeket az alkalmazásnak.
- prompt=select_account A megszakítja az egyszeri bejelentkezést, így a fiókválasztási folyamat felsorolja az összes fiókot akár munkamenetben, akár meg nem ett fiókként, vagy választhat egy másik fiók használatát.
login_hint Választható Ezzel a paraméterrel előre kitöltheti a felhasználó bejelentkezési oldalának felhasználónevét és e-mail-címét, ha előre ismeri a felhasználónevet. Az alkalmazások gyakran ezt a paramétert használják az újrahitelesítés során, miután már kinyerték a választható jogcímet login_hint egy korábbi bejelentkezésből.
domain_hint választható Ha tartalmazza, akkor kihagyja a felhasználó által a bejelentkezési oldalon végigvezetett e-mail-alapú felderítési folyamatot, ami egy kissé hatékonyabb felhasználói élményt biztosít – például elküldi azokat az összevont identitásszolgáltatónak. Az alkalmazások gyakran használják ezt a paramétert az újrahitelesítés során a kinyerésével tid egy korábbi bejelentkezésből.
code_challenge ajánlott/kötelező Az engedélyezési kód a Code Exchange (PKCE) hitelesítési kulcsán keresztüli jogosultságok biztonságossá Exchange használható. Kötelező, code_challenge_method ha szerepel benne. További információ: PKCE RFC. Ez mostantól minden alkalmazástípushoz (nyilvános és bizalmas ügyfelekhez) ajánlott, és az engedélyezési kódfolyamot használó egyoldalas Microsoft Identitásplatform számára szükséges.
code_challenge_method ajánlott/kötelező A paraméter paraméterének code_verifier kódolásához code_challenge használt metódus. Ennek a típusúnak kell lennie, de a specifikáció lehetővé teszi a használatát, ha az ügyfél valamilyen okból nem tudja támogatni S256 az plain SHA256-ot.

Ha ki van zárva, a rendszer azt feltételezi, hogy az egyszerű code_challenge szöveg, code_challenge ha szerepel benne. A Microsoft Identitásplatform támogatja a és a plain et S256 is. További információ: PKCE RFC. Ez az engedélyezési kódfolyamot használó egyoldalas alkalmazások esetén szükséges.

Ezen a ponton a rendszer megkéri a felhasználót, hogy adja meg a hitelesítő adatait, és töltse ki a hitelesítést. A Microsoft Identitásplatform arról is gondoskodik, hogy a felhasználó elfogadja a lekérdezési paraméterben megadott scope engedélyeket. Ha a felhasználó nem járult hozzá ezekhez az engedélyekhez, a rendszer megkéri a felhasználót, hogy járulja hozzá a szükséges engedélyekhez. Az engedélyek, a jóváhagyások ésa több-bérlős alkalmazások részleteit itt talál.

Miután a felhasználó hitelesítést és jóváhagyást adott, a Microsoft Identitásplatform választ ad vissza az alkalmazásnak a jelzett értéken a paraméterben redirect_uri megadott response_mode metódussal.

Sikeres válasz

A használatával a sikeres response_mode=query válasz a következő:

GET http://localhost?
code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&state=12345
Paraméter Leírás
code Az authorization_code alkalmazás által kért összes kérelem. Az alkalmazás az engedélyezési kóddal hozzáférési jogkivonatot kérhet a célerőforráshoz. Authorization_codes rövid életűek, általában körülbelül 10 perc után lejárnak.
state Ha egy állapotparaméter szerepel a kérésben, ugyaneznek az értéknek kell megjelennie 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 igényel egyet, és az implicit engedély engedélyezve van az alkalmazásregisztrációban. Ezt néha "hibrid folyamatnak" isnevezik, és olyan keretrendszerek használják, mint a ASP.NET.

Hibaválasz

Hibaválaszokat is elküldhet a redirect_uri számára, hogy az alkalmazás megfelelően tudja kezelni őket:

GET http://localhost?
error=access_denied
&error_description=the+user+canceled+the+authentication
Paraméter Leírás
error Hibakód-sztring, amely a előforduló hibák típusainak besorolására használható, és felhasználható a hibákra való reagálásra.
error_description Egy adott hibaüzenet, amely segíthet a fejlesztőknek azonosítani a hitelesítési hibák kiváltó okát.

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

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

Hibakód Description Ügyfél művelet
invalid_request Protokollhiba, például hiányzó kötelező paraméter. Javítsa ki és újra a kérést. Ez egy fejlesztési hiba, amely általában a kezdeti tesztelés során jelenik meg.
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 az Azure AD-ban, vagy nincs hozzáadva a felhasználó Azure AD-bérlőjéhez. Az alkalmazás útmutatást tud kérni a felhasználótól az alkalmazás telepítéséhez és az Azure AD-hez való hozzáadásához.
access_denied Erőforrás-tulajdonos megtagadott beleegyezése Az ügyfélalkalmazás értesítheti a felhasználót, hogy nem folytathatja a műveletet, ha a felhasználó nem járul hozzá.
unsupported_response_type Az engedélyezési kiszolgáló nem támogatja a kérés választípusát. Javítsa ki és újra a kérést. Ez egy fejlesztési hiba, amely általában a kezdeti tesztelés során jelenik meg. Ha a hibrid folyamatbanlátható, azt jelzi, hogy engedélyeznie kell az azonosító jogkivonat implicit engedélybeállítását az ügyfélalkalmazás-regisztráción.
server_error A kiszolgáló váratlan hibát észlelt. Próbálja újra a kérést. Ezek a hibák ideiglenes feltételeket eredményezhetnek. Az ügyfélalkalmazás elmagyarázhatja a felhasználónak, hogy a válasza egy átmeneti hibára késik.
temporarily_unavailable A kiszolgáló átmenetileg elfoglalt a kérés kezeléséhez. Próbálja újra a kérést. Az ügyfélalkalmazás elmagyarázhatja a felhasználónak, hogy a válasza egy ideiglenes állapot miatt késik.
invalid_resource A célerőforrás érvénytelen, mert nem létezik, az Azure AD nem találja, vagy nincs megfelelően konfigurálva. Ez a hiba azt jelzi, hogy az erőforrás (ha létezik) nincs konfigurálva a bérlőben. Az alkalmazás útmutatást tud kérni a felhasználótól az alkalmazás telepítéséhez és az Azure AD-hez való hozzáadásához.
login_required Túl sok vagy nem található felhasználó Az ügyfél csendes hitelesítést () kért, de egyetlen felhasználó prompt=none nem található. Ez azt jelentheti, hogy több felhasználó aktív a munkamenetben, vagy nincs felhasználó. Ez figyelembe veszi a kiválasztott bérlőt (például ha két aktív Azure AD-fiók és egy Microsoft-fiók van kiválasztva, a csendes consumers hitelesítés működni fog).
interaction_required A kéréshez felhasználói beavatkozás szükséges. További hitelesítési lépésre vagy jóváhagyásra van szükség. Próbálja újra a kérést a prompt=none nélkül.

Azonosító jogkivonat kérése is (hibrid folyamat)

Ha meg szeretne ismerkedni a felhasználóval az engedélyezési kód beváltása előtt, az alkalmazások gyakran azonosító jogkivonatot is kérnek az engedélyezési kód lekérésekor. Ezt hibrid folyamatnak nevezzük, mert az implicit engedélyezést az engedélyezési kódfolyammal keveri. A hibrid folyamatot gyakran használják olyan webalkalmazásokban, amelyek a kódbeváltás blokkolása nélkül szeretnék renderelni a ASP.NET. Ebben a modellben mind az egyoldalas, mind a hagyományos webalkalmazások esetében előnyös a késés csökkentése.

A hibrid folyamat megegyezik a korábban ismertetett hitelesítési kódfolyammal, de három kiegészítéssel, amelyek mind szükségesek az azonosító jogkivonat kéréséhez: új hatókörök, új response_type és egy új lekérdezési nonce paraméter.

// 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
Frissített paraméter Kötelező/nem kötelező Leírás
response_type Kötelező A összeadása jelzi a kiszolgálón, hogy az alkalmazás azonosító jogkivonatot szeretne a végpont id_token /authorize válaszában.
scope Kötelező Azonosító jogkivonatok esetén a-t frissíteni kell, hogy tartalmazza az azonosító jogkivonat-hatókörét – openid és opcionálisan profile és email .
nonce Kötelező A kérelemben szereplő, az alkalmazás által generált érték, amelyet az eredményül kapott id_token fog tartalmazni jogcímként. Az alkalmazás ezután ellenőrizheti ezt az értéket a jogkivonat-visszajátszásos támadások mérséklése érdekében. Az érték általában egy véletlenszerű, egyedi sztring, amely a kérés eredetének azonosítására használható.
response_mode Ajánlott Megadja a metódust, amely alapján az eredményül kapott jogkivonatot vissza kell küldeni az alkalmazásnak. Alapértelmezés szerint csak egy engedélyezési kódhoz, de ha a kérelem tartalmaz egy query fragment response_type id_token. Az alkalmazások használata azonban form_post ajánlott, különösen átirányítási http://localhost URI-ként való használat esetén.

A válasz módként való használata problémákat okoz a webalkalmazások számára, amelyek az átirányításból olvassák a kódot, mivel a böngészők nem ják meg a fragment töredéket a webkiszolgálónak. Ilyen esetekben az alkalmazásoknak a válasz mód használatával kell biztosítaniuk, hogy minden adat form_post a kiszolgálóra legyen küldve.

Sikeres válasz

A használatával a sikeres response_mode=fragment válasz a következő:

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óddal hozzáférési jogkivonatot kérhet a célerőforráshoz. Az engedélyezési kódok rövid életűek, általában körülbelül 10 perc után lejárnak.
id_token A felhasználó azonosító jogkivonata, implicit engedély használatával kibocsátva. Egy speciális jogcímet tartalmaz, amely a kivonata ugyanabban a c_hash code kérésben.
state Ha egy állapotparaméter szerepel a kérésben, ugyaneznek az értéknek kell megjelennie 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él választhat az ügyfélkulcsok (a Microsoft Identitásplatform által létrehozott szimmetrikus megosztott titkos kulcsok) és a tanúsítvány hitelesítő adatainak (afejlesztő által feltöltött aszimmetrikus kulcsok) használata között. A legjobb biztonság érdekében javasoljuk a tanúsítvány hitelesítő adatainak használatát. A nyilvános ügyfelek (natív alkalmazások és egylapos alkalmazások) nem használhatnak titkos kódokat vagy tanúsítványokat az engedélyezési kód beváltása során – mindig győződjön meg arról, hogy az átirányítási URI-k megfelelően jelzik az alkalmazás típusát, és egyediek.

Hozzáférési jogkivonat kérése client_secret

Most, hogy beszerezte a authorization_code és a felhasználó engedélyt kapott rá, beválthatja az azonosítót code a access_token kívánt erőforrásra. Ehhez egy kérést kell küldenie a POST /token végpontnak:

// 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.
Paraméter Kötelező/nem kötelező Description
tenant kötelező A kérés elérési útján található érték segítségével szabályozható, hogy ki {tenant} jelentkezhet be az alkalmazásba. Az engedélyezett értékek a common , organizations , és consumers bérlőazonosítók. További részletekért lásd a protokollok alapjait.
client_id kötelező Az alkalmazáshoz rendelt Azure Portal Alkalmazásregisztrációk (ügyfél) azonosítója.
scope választható A hatókörök szóközrel elválasztott listája. A hatóköröknek egyetlen erőforrásból, valamint OIDC-hatókörökből ( profile , , ) kell openid email lennie. A hatókörök részletesebb magyarázatát az engedélyeket, a hozzájárulásokat és a hatóköröket lásd:. Ez egy Microsoft-bővítmény az engedélyezési kódfolyamhoz, amely lehetővé teszi az alkalmazások számára, hogy deklarálják az erőforrást, amely számára a jogkivonat beváltása során a jogkivonatot szeretnék.
code kötelező A authorization_code első lépésében beszerzett authorization_code.
redirect_uri kötelező Ugyanaz a redirect_uri érték, amely a authorization_code.
grant_type kötelező Az engedélyezési authorization_code kódfolyamhoz kell, hogy legyen.
code_verifier Ajánlott A code_verifier beszerzéséhez használt authorization_code. Kötelező, ha a PKCE-t használták az engedélyezési kód engedélyezési kérésében. További információ: PKCE RFC.
client_secret bizalmas webalkalmazások esetén szükséges Az alkalmazásregisztrációs portálon az alkalmazásregisztrációs portálon létrehozott titkos alkalmazás titkos. Ne használja az alkalmazás titkos adatokat egy natív alkalmazásban vagy egyoldalas alkalmazásban, mert a client_secrets nem tárolhatók megbízhatóan eszközökön vagy weboldalakon. Olyan webalkalmazások és webes API-k esetében szükséges, amelyek képesek biztonságosan tárolni a client_secret a kiszolgálóoldalon. Mint minden itt tárgyalt paraméter esetében, az ügyfél titkos kódját is URL-kódolásúnak kell lennie az elküldjük, amit általában az SDK hajt végre. Az URI-kódolással kapcsolatos további információkért lásd az URI általános szintaxis specifikációját. Az RfC 6749 szabvány szerint az Alapszintű hitelesítési minta is támogatja a hitelesítő adatok megadását az Authorization fejlécben.

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

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
Paraméter Kötelező/nem kötelező Description
tenant kötelező A kérés elérési útján található értékkel szabályozható, hogy ki {tenant} jelentkezhet be az alkalmazásba. Az engedélyezett értékek a common , organizations , és consumers bérlőazonosítók. További részletekért lásd a protokollok alapjait.
client_id kötelező Az alkalmazáshoz rendelt Azure Portal Alkalmazásregisztrációk (ügyfél) azonosítója.
scope választható A hatókörök szóközrel elválasztott listája. A hatóköröknek egyetlen erőforrásból, valamint OIDC-hatókörökből ( profile , , ) kell openid email lennie. A hatókörök részletesebb magyarázatát az engedélyeket, a hozzájárulásokat és a hatóköröket lásd:. Ez egy Microsoft-bővítmény az engedélyezési kódfolyamhoz, amely lehetővé teszi az alkalmazások számára, hogy deklarálják az erőforrást, amely számára a jogkivonat beváltása során a jogkivonatot szeretnék.
code kötelező A authorization_code első lépésében beszerzett authorization_code.
redirect_uri kötelező Ugyanaz a redirect_uri érték, amely a authorization_code.
grant_type kötelező Az engedélyezési authorization_code kódfolyamhoz kell, hogy legyen.
code_verifier Ajánlott A code_verifier beszerzéséhez használt authorization_code. Kötelező, ha a PKCE-t használták az engedélyezési kód engedélyezési kérésében. További információ: PKCE RFC.
client_assertion_type bizalmas webalkalmazások esetén szükséges A tanúsítvány hitelesítő adatainak használata érdekében az értéket értékre urn:ietf:params:oauth:client-assertion-type:jwt-bearer kell állítani.
client_assertion bizalmas webalkalmazások esetén szükséges Egy helyességi feltételt (egy JSON webes jogkivonatot), amely az alkalmazás hitelesítő adataiként regisztrált tanúsítvánnyal hozható létre és írható alá. A tanúsítvány hitelesítő adataival kapcsolatos információkért olvassa el, hogyan regisztrálhatja a tanúsítványt és a helyességi feltétel formátumát.

Figyelje meg, hogy a paraméterek ugyanazok, mint a közös titkos ként megadott kérés esetében, azzal a kivételsel, hogy a paramétert két paraméter váltja client_secret fel: egy client_assertion_type és client_assertion .

Sikeres válasz

A sikeres jogkivonatválasz a következő lesz:

{
    "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 biztonságos erőforrással, például egy webes API-val.
token_type A jogkivonat típusának értékét jelzi. Az Azure AD csak a Bearer típust támogatja
expires_in A hozzáférési jogkivonat érvényességének ideje (másodpercben).
scope A hatókörök, amelyekre access_token érvényes. Nem kötelező – ez nem szabványos, és ha nincs megadva, a jogkivonat a folyamat kezdeti szakaszában kért hatókörökre fog kiterjedni.
refresh_token OAuth 2.0 frissítési jogkivonat. Az alkalmazás ezzel a jogkivonattal további hozzáférési jogkivonatokat szerezhet be az aktuális hozzáférési jogkivonat lejárta után. Refresh_tokens hosszú életűek, és használhatók az erőforrásokhoz való hozzáférés hosszabb ideig tartó megőrzésére. A hozzáférési jogkivonatok frissítésének további részleteiért tekintse meg az alábbi szakaszt.
Megjegyzés: Csak akkor van megtéve, offline_access ha a hatókört kérelmezték.
id_token Egy JSON-webtoken (JWT). Az alkalmazás képes dekódolni a jogkivonat szegmenseket, 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 felhasználhatjak engedélyezésre. További információ a id_tokens: id_token reference .
Megjegyzés: Csak akkor van megtéve, openid ha a hatókört kérelmezték.

Hibaválasz

A hibaválaszok a következőnek fognak kinézni:

{
  "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"
}
Paraméter Leírás
error Hibakód-sztring, amely a előforduló hibák típusainak besorolására használható, és a hibákra való reagálásra használható.
error_description Egy adott hibaüzenet, amely segíthet a fejlesztőknek azonosítani a hitelesítési hibák kiváltó okát.
error_codes Az STS-specifikus hibakódok listája, amelyek segíthetnek a diagnosztikában.
timestamp A hiba beesésének ideje.
trace_id A kérelem 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égpont-hibák hibakódjai

Hibakód Description Ügyfél mű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 újrakérte 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áljon ki egy új kérést a végpontra, és ellenőrizze, hogy a code_verifier /authorize 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 általában akkor fordul elő, ha az ügyfélalkalmazás nincs regisztrálva az Azure AD-ban, vagy nincs hozzáadva a felhasználó Azure AD-bérlőjéhez. Az alkalmazás útmutatást tud kérni a felhasználótól az alkalmazás telepítéséhez és az Azure AD-hez való hozzáadásához.
invalid_client Az ügyfél-hitelesítés sikertelen volt. Az ügyfél hitelesítő adatai nem érvényesek. A probléma megoldásához az alkalmazás rendszergazdája 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 kérelemben a engedély típusát. Ez a hibatípus csak a fejlesztés során fordul elő, és a kezdeti tesztelés során észlelni kell.
invalid_resource A célerőforrás érvénytelen, mert nem létezik, az Azure AD nem találja, vagy nincs megfelelően konfigurálva. Ez azt jelzi, hogy az erőforrás (ha létezik) nincs konfigurálva a bérlőben. Az alkalmazás útmutatást tud kérni a felhasználótól az alkalmazás telepítéséhez és az Azure AD-hez való hozzáadásához.
interaction_required Nem szabványos, mivel az OIDC-specifikáció ezt csak a végponton /authorize hívja meg. A kéréshez felhasználói beavatkozás szükséges. Például egy további hitelesítési lépésre van szükség. Próbálja meg újra /authorize a kérést ugyanazokkal a hatókörökrel.
temporarily_unavailable A kiszolgáló átmenetileg túl elfoglalt a kérés kezeléséhez. Kis késleltetés után próbálja újra 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.
consent_required A kérelemhez felhasználói jóváhagyás szükséges. Ez a hiba nem szabványos, mivel általában csak a végponton, /authorize OIDC-specifikációk szerint jelenik meg. Akkor ad vissza, ha a kódbeváltási folyamat egy olyan paramétert használt, amely kéréséhez az ügyfélalkalmazás scope nem rendelkezik engedéllyel. Az ügyfélnek vissza kell küldenie a felhasználót a megfelelő hatókörrel a végpontra a /authorize hozzájárulás aktiválása érdekében.
invalid_scope Az alkalmazás által kért hatókör érvénytelen. Frissítse a hitelesítési kérelem hatókörparaméterének értékét egy érvényes értékre.

Megjegyzés

Az egyoldalas alkalmazások hibaüzenetet kaphatnak, amely szerint az eredetközi jogkivonatok beváltása csak az "egyoldalas invalid_request alkalmazás" ügyféltípus esetében engedélyezett. Ez azt jelzi, hogy a jogkivonat kérésére használt átirányítási URI nincs megjelölve átirányítási spa URI-ként. A folyamat engedélyezéséhez tekintse át az alkalmazásregisztráció lépéseit.

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

Most, hogy sikeresen beszerezte az -t, a tokent a webes API-khoz való kérések során használhatja, ha a fejlécbe is access_token Authorization beveszi:

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

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

Access_tokens rövid életűek, és a lejáratuk után frissítenie kell őket az erőforrásokhoz való hozzáférés folytatásához. Ezt úgy teheti meg, ha egy másik kérést nyújt be a végpontnak, ezúttal a helyett a et POST /token refresh_token code használhatja. A frissítési jogkivonatok minden olyan engedélyre érvényesek, amelyekhez az ügyfél már megkapta a hozzájárulást, így a kérésére kiadott frissítési jogkivonat felhasználható új hozzáférési jogkivonat kérésére scope=mail.read scope=api://contoso.com/api/UseResource a számára.

A webalkalmazások és a natív alkalmazások frissítési jogkivonatai nem meghatározott élettartamokkal vannak megadva. A frissítési jogkivonatok élettartama általában viszonylag hosszú. Bizonyos esetekben azonban a frissítési jogkivonatok lejárnak, meg vannak vonva, vagy nem rendelkeznek megfelelő jogosultságokkal a kívánt művelethez. Az alkalmazásnak megfelelően kell számítania és kezelnie a jogkivonat-kiállítási végpont által visszaadott hibákat. Az egyoldalas alkalmazások azonban egy 24 órás élettartamú jogkivonatot szereznek be, amely minden nap új hitelesítést igényel. Ez az iframe-ben csendes módban is elérhető, ha a harmadik féltől származó cookie-k engedélyezve vannak, de ezt egy legfelső szintű keretben (teljes oldalnavigációs vagy előugró ablakban) kell tenni olyan böngészőkben, amelyekben nincsenek harmadik féltől származó cookie-k, például a Safari.

Bár az új hozzáférési jogkivonatok beszerzésekor a rendszer nem vonja vissza a frissítési jogkivonatokat, el kell vesse a régi frissítési jogkivonatot. Az OAuth 2.0 specifikációja a következő: "Az engedélyezési kiszolgáló új frissítési jogkivonatot ad ki, amely 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

Aként regisztrált átirányítási URI-nak küldött frissítési jogkivonatok 24 óra után spa lejárnak. A kezdeti frissítési jogkivonattal beszerzett további frissítési jogkivonatok a lejárati időt is át fogják vinni, ezért az alkalmazásoknak elő kell készíteniük az engedélyezési kódfolyam újrafuttatását interaktív hitelesítéssel, hogy 24 óránként új frissítési jogkivonatot szerezzenek be. A felhasználóknak nem kell megadniuk a hitelesítő adataikat, és általában nem is látnak felhasználói felületeket, csak az alkalmazás újratöltését – de a böngészőnek meg kell jelennie a bejelentkezési oldalon egy felső szintű keretben, hogy meg tudja jelenni a bejelentkezési munkamenetet. Ezt a böngészők adatvédelmi funkciói jelentik, amelyek letiltják a harmadik féltől származó cookie-kat.


// 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
Paraméter Típus Description
tenant kötelező A kérés elérési útján található értékkel szabályozható, hogy ki {tenant} jelentkezhet be az alkalmazásba. Az engedélyezett értékek a common , organizations , és consumers bérlőazonosítók. További részletekért lásd a protokollok alapjait.
client_id kötelező Az alkalmazás (ügyfél) azonosítója, Azure Portal – Alkalmazásregisztrációk alkalmazáshoz rendelt felhasználói élményt.
grant_type kötelező Az engedélyezési refresh_token kód ezen szakaszának kell lennie.
scope választható A hatókörök szóközrel elválasztott listája. Az ebben a lábban kért hatóköröknek egyenértékűnek kell lenniük a kérelem eredeti részében lekért hatókörök authorization_code részvel. Ha a kérésben megadott hatókörök több erőforrás-kiszolgálóra is kiterjednek, akkor a Microsoft Identitásplatform visszaad egy jogkivonatot az első hatókörben megadott erőforráshoz. A hatókörök részletesebb magyarázatát az engedélyeket, a hozzájárulásokat és a hatóköröket lásd:.
refresh_token kötelező A refresh_token a folyamat második lábában beszerzett refresh_token.
client_secret webalkalmazások esetén szükséges Az alkalmazásregisztrációs portálon az alkalmazásregisztrációs portálon létrehozott titkos alkalmazás titkos. Nem használható natív alkalmazásokban, mert a client_secrets nem tárolhatók megbízhatóan az eszközökön. Olyan webalkalmazások és webes API-k esetében szükséges, amelyek képesek biztonságosan tárolni a client_secret a kiszolgálóoldalon. Ennek a titkos kódnak URL-kódolásúnak kell lennie. További információkért lásd az URI általános szintaxis specifikációját.

Sikeres válasz

A sikeres jogkivonatválasz a következő lesz:

{
    "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 biztonságos erőforrással, például egy webes API-val.
token_type A jogkivonat típusának értékét jelzi. Az Azure AD csak a Bearer típust támogatja
expires_in A hozzáférési jogkivonat érvényességének ideje (másodpercben).
scope A hatókörök, amelyekre access_token érvényes.
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ő legnagyobb ideig érvényesek maradjanak.
Megjegyzés: Csak akkor van megtéve, offline_access ha a hatókört kérelmezték.
id_token Aláíratlan JSON-webtoken (JWT). Az alkalmazás képes dekódolni a jogkivonat szegmenseket, 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, de nem támaszkodhat rájuk semmilyen engedélyezési vagy biztonsági határ esetén. További információ a id_tokens: id_token reference .
Megjegyzés: Csak akkor van megtéve, openid ha a hatókört kérelmezték.

Figyelmeztetés

Ne kísérelje meg érvényesíteni vagy beolvasni a jogkivonatokat olyan API-knál, amelyek nem a tulajdonában vannak, beleértve a példában a jogkivonatokat is a kódban. A Microsoft-szolgáltatások olyan speciális formátumot használhatnak, amely nem JWT-ként lesz érvényesítve, és a fogyasztó (Microsoft-fiók) felhasználók számára is titkosítható. Bár a jogkivonatok olvasása hasznos hibakeresési és tanulási eszköz, ne vegye fel a függőségeket a kódban, és ne feltételezz konkrét jogkivonatokat, amelyek nem egy Ön által vezérelt API-hoz valók.

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: 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"
}
Paraméter Leírás
error Hibakód-sztring, amely a előforduló hibák típusainak besorolására használható, és a hibákra való reagálásra használható.
error_description Egy adott hibaüzenet, amely segíthet a fejlesztőknek azonosítani a hitelesítési hibák kiváltó okát.
error_codes Az STS-specifikus hibakódok listája, amelyek segíthetnek a diagnosztikában.
timestamp A hiba beesésének ideje.
trace_id A kérelem 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 leírását és a javasolt ügyfél-műveletet lásd: Jogkivonatvégpont-hibák hibakódjai.