Microsoft Identitásplatform és OAuth 2.0 implicit engedélyezési folyamat

  • Cikk

A Microsoft Identitásplatform támogatja az OAuth 2.0 implicit engedélyezési folyamatot az OAuth 2.0 specifikációjának megfelelően. Az implicit támogatás meghatározó jellemzője, hogy a jogkivonatok (azonosító jogkivonatok vagy hozzáférési jogkivonatok) a /token végpont helyett közvetlenül a /authorize végpontról lesznek visszaadva. Ezt gyakran használják az engedélyezési kódfolyamat részeként, úgynevezett "hibrid folyamatban" – az azonosító jogkivonat lekérése az /authorization kérelemben egy engedélyezési kóddal együtt.

Ez a cikk azt ismerteti, hogyan programozza közvetlenül az alkalmazás protokollját a Microsoft Entra ID-ból származó jogkivonatok lekéréséhez. Azt javasoljuk, hogy amikor lehetséges, inkább a támogatott Microsoft hitelesítési kódtárakat (MSAL) használja a tokenek beszerzéséhez és biztonságos webes API-k meghívásához. Tekintse meg az MSAL-t használó mintaalkalmazásokat is.

A hitelesítési kód folyamatának előnyben részesítése

A harmadik féltől származó cookie-k böngészőkből való eltávolításának tervével az implicit engedélyezési folyamat már nem megfelelő hitelesítési módszer. Az implicit folyamat csendes egyszeri bejelentkezési (SSO) funkciói nem működnek külső cookie-k nélkül, ezért az alkalmazások megszakadnak, amikor új jogkivonatot próbálnak beszerezni. Határozottan javasoljuk, hogy minden új alkalmazás használja az engedélyezési kódfolyamatot , amely mostantól támogatja az egyoldalas alkalmazásokat az implicit folyamat helyett. A meglévő egyoldalas alkalmazásoknak az engedélyezési kód folyamatára is át kell migrálniuk.

Megfelelő forgatókönyvek az OAuth2 implicit támogatásához

Az implicit támogatás csak a bejelentkezési folyamat kezdeti, interaktív részéhez megbízható, ahol a külső cookie-k hiánya nem befolyásolja az alkalmazást. Ez a korlátozás azt jelenti, hogy kizárólag a hibrid folyamat részeként kell használnia, ahol az alkalmazás kódot és jogkivonatot kér az engedélyezési végponttól. Hibrid folyamatban az alkalmazás egy olyan kódot kap, amely beváltható egy frissítési jogkivonatra, így biztosítva, hogy az alkalmazás bejelentkezési munkamenete az idő függvényében érvényes maradjon.

Protokolldiagram

Az alábbi ábra bemutatja, hogy a teljes implicit bejelentkezési folyamat hogyan néz ki, és az alábbi szakaszok részletesen ismertetik az egyes lépéseket.

Diagram showing the implicit sign-in flow

A bejelentkezési kérelem elküldése

Ha először be szeretné jelentkezni a felhasználót az alkalmazásba, elküldhet egy OpenID-Csatlakozás hitelesítési kérelmet, és lekérheti id_token a Microsoft Identitásplatform.

Fontos

Az azonosító jogkivonat és/vagy hozzáférési jogkivonat sikeres lekéréséhez az alkalmazásregisztrációnak a Microsoft Entra felügyeleti központban – Alkalmazásregisztrációk lapon engedélyezni kell a megfelelő implicit engedélyezési folyamatot. Ehhez válassza ki az azonosító jogkivonatokat és a hozzáférési jogkivonatokat az Implicit engedélyezési és hibrid folyamatok szakaszban. Ha nincs engedélyezve, a rendszer hibát unsupported_response ad vissza:

The provided value for the input parameter 'response_type' is not allowed for this client. Expected value is 'code'

// Line breaks for legibility only

https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&response_type=id_token
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&scope=openid
&response_mode=fragment
&state=12345
&nonce=678910
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 engedélyezett értékek a common, organizationsés consumersa bérlőazonosítók. További részletekért tekintse meg a protokoll alapjait. Kritikus fontosságú, hogy olyan vendégforgatókönyvek esetén, ahol 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 helyesen jelentkezzen be az erőforrás-bérlőbe.
client_id kötelező Az alkalmazás (ügyfél) azonosítója, amelyet a Microsoft Entra Felügyeleti központ Alkalmazásregisztrációk az alkalmazáshoz rendelt oldal.
response_type kötelező Az OpenID Csatlakozás bejelentkezéshez szerepelnie id_token kell. A következőt is tartalmazhatja: response_type. token Az itt való használat token lehetővé teszi, hogy az alkalmazás azonnal megkapja a hozzáférési jogkivonatot az engedélyezési végpontról anélkül, hogy egy második kérést kellene küldenie az engedélyezési végponthoz. Ha a token response_type használja, a scope paraméternek tartalmaznia kell egy hatókört, amely jelzi, hogy melyik erőforrásnak adja ki a jogkivonatot (például user.read a Microsoft Graphon). Emellett az engedélyezési kód megadására szolgáló kódot is tartalmazhat codetoken az engedélyezési kód folyamatában való használatra. Ezt a id_token+code választ néha hibrid folyamatnak is nevezik.
redirect_uri ajánlott Az alkalmazás átirányítási URI-ja, ahol az alkalmazás hitelesítési válaszokat küldhet és fogadhat. Pontosan meg kell egyeznie a portálon regisztrált átirányítási URI-k egyikével, kivéve, ha URL-kódolású.
scope kötelező A hatókörök szóközzel elválasztott listája. Az OpenID Csatlakozás (id_tokens) esetében tartalmaznia kell a hatókörtopenid, amely a hozzájárulás felhasználói felületén a "Bejelentkezés" engedélyre lefordítva jelenik meg. Szükség esetén a további felhasználói adatokhoz való hozzáféréshez szükséges hatóköröket és profile hatóköröket is meg kell adniaemail. Más hatóköröket is felvehet ebben a kérésben a különböző erőforrásokhoz való hozzájárulás kéréséhez, ha hozzáférési jogkivonatot kérnek.
response_mode választható Megadja azt a metódust, amellyel az eredményül kapott jogkivonatot vissza kell küldeni az alkalmazásnak. Alapértelmezés szerint csak egy hozzáférési jogkivonatot szeretne lekérdezni, de töredék, ha a kérés tartalmaz egy id_token.
state ajánlott A kérésben szereplő érték, amelyet a jogkivonat válaszában is visszaadunk. 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 állapot a felhasználó állapotával kapcsolatos információk kódolására is használható az alkalmazásban a hitelesítési kérelem előtt, például a lapon vagy a nézeten.
nonce kötelező Az alkalmazás által létrehozott kérésben szereplő érték, amely jogcímként szerepel az eredményül kapott azonosító jogkivonatban. 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ó. Csak id_token kérése esetén szükséges.
prompt választható A szükséges felhasználói beavatkozás típusát jelzi. Az egyetlen érvényes érték jelenleg a login, none, select_accountés consent. 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 - ez biztosítja, hogy a felhasználó nem jelenik meg semmilyen interaktív kérdést. Ha a kérés nem hajtható végre csendesen az egyszeri bejelentkezéssel, a Microsoft Identitásplatform hibát ad vissza. prompt=select_account elküldi a felhasználót egy fiókválasztónak, ahol a munkamenetben megjegyzett összes fiók megjelenik. prompt=consent az OAuth hozzájárulási párbeszédpanelt a felhasználó bejelentkezése után aktiválja, és megkéri a felhasználót, hogy adjon engedélyeket az alkalmazásnak.
login_hint választható Ezzel a paramétersel 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 használják ezt a paramétert az újrahitelesítés során, miután már kinyerték az login_hintopcionális jogcímet egy korábbi bejelentkezésből.
domain_hint választható Ha tartalmazza, akkor 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. Ezt a paramétert gyakran használják olyan Üzletági alkalmazásokhoz, amelyek egyetlen bérlőben működnek, ahol egy adott bérlőn belül megadnak egy tartománynevet, és továbbítják a felhasználót az adott bérlő összevonási szolgáltatójának. Ez a tipp megakadályozza, hogy a vendégek bejelentkeznek az alkalmazásba, és korlátozzák a felhőbeli hitelesítő adatok, például a FIDO használatát.

Ekkor 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á, kérni fogja a felhasználót, hogy járuljon hozzá a szükséges engedélyekhez. További információ: engedélyek, hozzájárulás és több-bérlős alkalmazások.

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

Sikeres válasz

A sikeres válasz az response_mode=fragmentresponse_type=id_token+code alábbihoz hasonlóan működik (olvashatóság érdekében sortörésekkel):

GET https://localhost/myapp/#
code=0.AgAAktYV-sfpYESnQynylW_UKZmH-C9y_G1A
&id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...
&state=12345
Paraméter Leírás
code Tartalmazza, ha response_type tartalmazza code. Ez egy engedélyezési kód, amely alkalmas az engedélyezési kód folyamatában való használatra.
access_token Tartalmazza, ha response_type tartalmazza token. Az alkalmazás által kért hozzáférési jogkivonat. A hozzáférési jogkivonatot nem szabad dekódolni vagy más módon ellenőrizni, átlátszatlan sztringként kell kezelni.
token_type Tartalmazza, ha response_type tartalmazza token. Ez mindig így lesz Bearer.
expires_in Tartalmazza, ha response_type tartalmazza token. Azt jelzi, hogy a jogkivonat hány másodpercig érvényes gyorsítótárazási célokra.
scope Tartalmazza, ha response_type tartalmazza token. Azt a hatókört jelzi, amelyre a access_token érvényes lesz. Előfordulhat, hogy nem tartalmazza az összes kért hatókört, ha nem alkalmazhatók a felhasználóra. Például a microsoft entra-only hatókörök, amikor személyes fiók használatával jelentkeznek be.
id_token Aláírt JSON-webjogkivonat (JWT). 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. Az azonosító jogkivonatokkal kapcsolatos további információkért lásd: id_token reference.
Megjegyzés: Csak akkor van megadva, ha openid a hatókört kérték és response_type belefoglalták id_tokens.
state Ha egy állapotparamé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.

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

A hibaválaszokat is elküldheti a rendszer, redirect_uri hogy az alkalmazás megfelelően kezelje őket:

GET https://localhost/myapp/#
error=access_denied
&error_description=the+user+canceled+the+authentication
Paraméter Leírás
error Hibakódsztring, 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 a hitelesítési hibák kiváltó okának azonosításában.

Hozzáférési jogkivonatok csendes beszerzése

Fontos

Az implicit folyamat ezen része valószínűleg nem fog működni az alkalmazás számára, mivel a harmadik féltől származó cookie-k alapértelmezés szerint eltávolítása miatt különböző böngészőkben használják. Bár ez még mindig működik a Chromium-alapú böngészőkben, amelyek nem inkognitó, a fejlesztőknek újra kell gondolniuk ezt a részét a folyamatnak. A harmadik féltől származó cookie-kat nem támogató böngészőkben hibaüzenet jelenik meg, amely azt jelzi, hogy nincsenek bejelentkezve felhasználók, mivel a bejelentkezési oldal munkamenet-cookie-jait a böngésző eltávolította.

Most, hogy aláírta a felhasználót az egyoldalas alkalmazásba, csendesen lekérheti a hozzáférési jogkivonatokat a Microsoft Identitásplatform által védett webes API-k, például a Microsoft Graph meghívásához. Még akkor is, ha már kapott egy jogkivonatot a response_type használatával, ezzel a token módszerrel jogkivonatokat szerezhet be további erőforrásokba anélkül, hogy átirányította volna a felhasználót a bejelentkezésre.

A normál OpenID-Csatlakozás/OAuth-folyamatban ezt a Microsoft Identitásplatform /token végpontra irányuló kéréssel teheti meg. A kérést egy rejtett iframe-ben is megadhatja, hogy új jogkivonatokat kapjon más webes API-khoz:

// Line breaks for legibility only

https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444&response_type=token
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fuser.read
&response_mode=fragment
&state=12345
&nonce=678910
&prompt=none
&login_hint=myuser@mycompany.com

Az URL-ben található lekérdezési paraméterekkel kapcsolatos részletekért lásd a bejelentkezési kérés elküldését.

Tipp.

Próbálja meg átmásolni az alábbi kérést egy böngészőlapra! (Ne felejtse el lecserélni az login_hint értékeket a felhasználó számára megfelelő értékre)

https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id=535fb089-9ff3-47b6-9bfb-4f1264799865&response_type=token&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F&scope=https%3A%2F%2Fgraph.microsoft.com%2Fuser.read&response_mode=fragment&state=12345&nonce=678910&prompt=none&login_hint={your-username}

Vegye figyelembe, hogy ez a külső cookie-támogatás nélküli böngészőkben is működni fog, mivel ezt közvetlenül egy böngészősávba nyitja meg, nem pedig egy iframe-en belül.

A paraméternek köszönhetően ez a prompt=none kérés sikeres vagy azonnal sikertelen lesz, és visszatér az alkalmazáshoz. A válasz a megadott redirect_uriidőpontban lesz elküldve az alkalmazásnak a paraméterben response_mode megadott módszerrel.

Sikeres válasz

Sikeres válasz a response_mode=fragment következőképpen néz ki:

GET https://localhost/myapp/#
access_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...
&state=12345
&token_type=Bearer
&expires_in=3599
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fdirectory.read
Paraméter Leírás
access_token Tartalmazza, ha response_type tartalmazza token. Az alkalmazás által kért hozzáférési jogkivonat, ebben az esetben a Microsoft Graph esetében. A hozzáférési jogkivonatot nem szabad dekódolni vagy más módon ellenőrizni, átlátszatlan sztringként kell kezelni.
token_type Ez mindig így lesz Bearer.
expires_in Azt jelzi, hogy a jogkivonat hány másodpercig érvényes gyorsítótárazási célokra.
scope Azt a hatókört jelzi, amelyre érvényes lesz a hozzáférési jogkivonat. Előfordulhat, hogy nem tartalmazza az összes kért hatókört, ha nem alkalmazhatók a felhasználóra (abban az esetben, ha a Microsoft Entra csak a személyes fiók használatával jelentkezik be).
id_token Aláírt JSON-webjogkivonat (JWT). Tartalmazza, ha response_type tartalmazza id_token. 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. A id_tokens kapcsolatos további információkért lásd a id_token hivatkozást.
Megjegyzés: Csak akkor van megadva, ha openid a hatókört kérték.
state Ha egy állapotparamé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.

Hibaválasz

A hibaválaszokat is elküldheti a rendszer, redirect_uri hogy az alkalmazás megfelelően kezelje őket. Ebben az esetben prompt=nonea következő várható hiba jelenik meg:

GET https://localhost/myapp/#
error=user_authentication_required
&error_description=the+request+could+not+be+completed+silently
Paraméter Leírás
error Hibakódsztring, 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 a hitelesítési hibák kiváltó okának azonosításában.

Ha ezt a hibát az iframe-kérelemben kapja, a felhasználónak újra interaktívan be kell jelentkeznie egy új jogkivonat lekéréséhez. Dönthet úgy, hogy bármilyen módon kezeli ezt az esetet az alkalmazás számára.

Jogkivonatok frissítése

Az implicit támogatás nem biztosít frissítési jogkivonatokat. Az azonosító jogkivonatok és a hozzáférési jogkivonatok is rövid idő elteltével lejárnak, ezért az alkalmazásnak készen kell állnia arra, hogy rendszeresen frissítse ezeket a jogkivonatokat. Bármelyik jogkivonattípus frissítéséhez ugyanazt a rejtett iframe-kérést hajthatja végre fentről a paraméterrel az prompt=none identitásplatform viselkedésének szabályozásához. Ha új azonosító jogkivonatot szeretne kapni, mindenképpen használja id_token az response_type és scope=openid, valamint egy paramétert nonce .

A harmadik féltől származó cookie-kat nem támogató böngészőkben ez hibaüzenetet eredményez, amely azt jelzi, hogy nincs bejelentkezve felhasználó.

Bejelentkezési kérés küldése

Az OpenID Csatlakozás end_session_endpoint lehetővé teszi, hogy az alkalmazás kérést küldjön a Microsoft Identitásplatform a felhasználó munkamenetének befejezéséhez és a Microsoft Identitásplatform által beállított cookie-k törléséhez. Ha egy felhasználót teljes mértékben ki szeretne jelentkezni egy webalkalmazásból, az alkalmazásnak be kell fejeznie a saját munkamenetét a felhasználóval (általában a jogkivonat-gyorsítótár törlésével vagy a cookie-k elvetésével), majd átirányítani a böngészőt a következőre:

https://login.microsoftonline.com/{tenant}/oauth2/v2.0/logout?post_logout_redirect_uri=https://localhost/myapp/
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 engedélyezett értékek a common, organizationsés consumersa bérlőazonosítók. További részletekért tekintse meg a protokoll alapjait.
post_logout_redirect_uri ajánlott Az URL-cím, amelyet a felhasználónak vissza kell adni a kijelentkezés befejezése után. Ennek az értéknek meg kell egyeznie az alkalmazáshoz regisztrált átirányítási URI-k egyikével. Ha nem tartalmazza, a felhasználó egy általános üzenetet jelenít meg a Microsoft Identitásplatform.

Következő lépések