OAuth 2.0 engedélyezési kódfolyam az Azure Active Directory B2C-ben

Cikk
11/06/2023

Az eszközre telepített alkalmazásokban az OAuth 2.0 engedélyezési kód megadásával hozzáférhet a védett erőforrásokhoz, például a webes API-khoz. Az OAuth 2.0 Azure Active Directory B2C (Azure AD B2C) implementációjának használatával regisztrációs, bejelentkezési és egyéb identitáskezelési feladatokat adhat hozzá az egyoldalas, mobil- és asztali alkalmazásokhoz. Ez a cikk nyelvfüggetlen. A cikkben bemutatjuk, hogyan küldhet és fogadhat HTTP-üzeneteket nyílt forráskódú kódtárak használata nélkül. Ha lehetséges, javasoljuk, hogy használja a microsoftos hitelesítési kódtárakat (MSAL). Tekintse meg az MSAL-t használó mintaalkalmazásokat.

Az OAuth 2.0 engedélyezési kódfolyamatát az OAuth 2.0 specifikációjának 4.1. szakasza ismerteti. A legtöbb alkalmazástípusban használhatja hitelesítésre és engedélyezésre, beleértve a webalkalmazásokat, az egyoldalas alkalmazásokat és a natívan telepített alkalmazásokat. Az OAuth 2.0 engedélyezési kódfolyamatával biztonságosan szerezhet be hozzáférési jogkivonatokat és frissítési jogkivonatokat az alkalmazásokhoz, amelyek az engedélyezési kiszolgáló által védett erőforrások eléréséhez használhatók. A frissítési jogkivonat lehetővé teszi, hogy az ügyfél új hozzáférési (és frissítési) jogkivonatokat szerezzen be a hozzáférési jogkivonat lejárata után, általában egy óra elteltével.

Ez a cikk a nyilvános ügyfelek OAuth 2.0 engedélyezési kódfolyamatával foglalkozik. A nyilvános ügyfél minden olyan ügyfélalkalmazás, amely nem megbízható a titkos jelszó integritásának biztonságos fenntartása érdekében. Ez magában foglalja az egyoldalas alkalmazásokat, a mobilalkalmazásokat, az asztali alkalmazásokat és lényegében minden olyan alkalmazást, amely nem fut egy kiszolgálón.

Megjegyzés

Ha Azure AD B2C használatával szeretne identitáskezelést hozzáadni egy webalkalmazáshoz, használja az OpenID Connectet az OAuth 2.0 helyett.

Azure AD A B2C kiterjeszti a szabványos OAuth 2.0-folyamatokat az egyszerű hitelesítés és engedélyezés helyett. Bevezeti a felhasználói folyamatot. A felhasználói folyamatokkal az OAuth 2.0 használatával felhasználói élményeket adhat az alkalmazáshoz, például a regisztrációt, a bejelentkezést és a profilkezelést. Az OAuth 2.0 protokollt használó identitásszolgáltatók közé tartozik az Amazon, Microsoft Entra ID, Facebook, GitHub, Google és LinkedIn.

A http-kérések kipróbálása ebben a cikkben:

Cserélje le {tenant} a elemet a Azure AD B2C-bérlő nevére.
Cserélje le a elemet 90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6 a Azure AD B2C-bérlőben korábban regisztrált alkalmazás alkalmazásazonosítójára.
Cserélje le {policy} a elemet a bérlőben létrehozott szabályzat nevére, például b2c_1_sign_in: .

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

Az egyoldalas alkalmazások engedélyezési kódjának folyamata további beállításokat igényel. Kövesse az egyoldalas alkalmazás létrehozására vonatkozó utasításokat, hogy helyesen jelölje meg az átirányítási URI-t a CORS számára engedélyezettként. Ha frissíteni szeretne egy meglévő átirányítási URI-t a CORS engedélyezéséhez, kattintson az alkalmazásregisztrációHitelesítés lapjának "Web" szakaszában található migrálási kérdésre. Másik lehetőségként megnyithatja a Alkalmazásregisztrációk jegyzékszerkesztőt, és beállíthatja az type átirányítási URI mezőjét spa a replyUrlsWithType szakaszban.

Az spa átirányítási típus visszafelé kompatibilis az implicit folyamattal. A jogkivonatok lekérésére jelenleg implicit folyamatot 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.

1. Engedélyezési kód leké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 . Ez a folyamat interaktív része, ahol a felhasználó végrehajtja a műveletet. Ebben a kérelemben az ügyfél a paraméterben scope jelzi a felhasználótól beszerezni kívánt engedélyeket. Az alábbi példák (az olvashatóság érdekében sortörésekkel) bemutatják, hogyan szerezhet be engedélyezési kódot. Ha ezt a GET HTTP-kérést teszteli, használja a böngészőt.

GET https://{tenant}.b2clogin.com/{tenant}.onmicrosoft.com/{policy}/oauth2/v2.0/authorize?
client_id=90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6
&response_type=code
&redirect_uri=urn%3Aietf%3Awg%3Aoauth%3A2.0%3Aoob
&response_mode=query
&scope=90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6%20offline_access%20https://{tenant-name}/{app-id-uri}/{scope}
&state=arbitrary_data_you_can_receive_in_the_response
&code_challenge=YTFjNjI1OWYzMzA3MTI4ZDY2Njg5M2RkNmVjNDE5YmEyZGRhOGYyM2IzNjdmZWFhMTQ1ODg3NDcxY2Nl
&code_challenge_method=S256

Paraméter	Kötelező?	Description
{tenant}	Kötelező	A Azure AD B2C-bérlő neve
{policy}	Kötelező	A futtatandó felhasználói folyamat. Adja meg a Azure AD B2C-bérlőben létrehozott felhasználói folyamat nevét. Például: `b2c_1_sign_in`, `b2c_1_sign_up`vagy `b2c_1_edit_profile`.
client_id	Kötelező	Az alkalmazáshoz rendelt alkalmazásazonosító a Azure Portal.
response_type	Kötelező	A válasz típusa, amelynek tartalmaznia `code` kell az engedélyezési kódfolyamatot. Akkor kaphat azonosító jogkivonatot, ha a választípusba (például `code+id_token`) belefoglalja, és ebben az esetben a hatókörnek tartalmaznia kell a következőt `openid`: .
redirect_uri	Kötelező	Az alkalmazás átirányítási URI-ja, ahol az alkalmazás hitelesítési válaszokat küld és fogad. Pontosan meg kell egyeznie a portálon regisztrált átirányítási URI-k egyikével, kivéve, hogy URL-kódolásúnak kell lennie.
scope	Kötelező	A hatókörök szóközzel elválasztott listája. A `openid` hatókör azt jelzi, hogy a felhasználó bejelentkezhet, és azonosító jogkivonatok formájában lekérheti a felhasználó adatait. A `offline_access` hatókör nem kötelező webalkalmazásokhoz. Azt jelzi, hogy az alkalmazásnak szüksége lesz egy frissítési jogkivonatra az erőforrásokhoz való kiterjesztett hozzáféréshez. Az ügyfél-azonosító azt jelzi, hogy a kibocsátott jogkivonatot Azure AD B2C-ben regisztrált ügyfél használja. A `https://{tenant-name}/{app-id-uri}/{scope}` a védett erőforrásokra, például egy webes API-ra vonatkozó engedélyt jelez. További információ: Hozzáférési jogkivonat kérése.
response_mode	Ajánlott	Az a módszer, amellyel az eredményül kapott engedélyezési kódot visszaküldi az alkalmazásnak. `query`Lehet , vagy `form_postfragment`.
állapot	Ajánlott	A kérelemben szereplő érték, amely bármilyen használni kívánt tartalom sztringje lehet. A rendszer általában véletlenszerűen generált egyedi értéket használ a helyek közötti kérelmek hamisítási támadásainak megakadályozására. Az állapotot arra is használják, hogy a hitelesítési kérés előtt kódolja a felhasználó állapotával kapcsolatos információkat az alkalmazásban. Például az a lap, amelyen a felhasználó volt, vagy a végrehajtás alatt álló felhasználói folyamat.
Gyors	Választható	A szükséges felhasználói interakció típusa. Jelenleg az egyetlen érvényes érték a `login`, amely kényszeríti a felhasználót, hogy adja meg a hitelesítő adatait a kérelemben. Az egyszeri bejelentkezés nem lép érvénybe.
code_challenge	ajánlott /kötelező	Az engedélyezési kód megadásának védelmére szolgál a Code Exchange (PKCE) proof key (Proof Key for Code Exchange, PKCE) segítségével. Kötelező, ha `code_challenge_method` szerepel benne. A és `code_challenge`a létrehozásához logikát kell hozzáadnia az `code_verifier` alkalmazásban. A `code_challenge` a base64 URL-kódolású SHA256 kivonata.`code_verifier` Az alkalmazást későbbi használatra tárolhatja `code_verifier` , és elküldheti az `code_challenge` engedélyezési kérelemmel együtt. További információ: PKCE RFC. Ez mostantól minden alkalmazástípushoz ajánlott – natív alkalmazásokhoz, SPA-khoz és olyan bizalmas ügyfelekhez, mint a webalkalmazások.
`code_challenge_method`	ajánlott /kötelező	A paraméter kódolásához `code_verifiercode_challenge` használt metódus. Ennek kell lennie `S256`, de a specifikáció lehetővé teszi a használatát `plain` , ha az ügyfél valamilyen okból nem tudja támogatni az SHA256-ot. Ha kizárja a `code_challenge_method`, de továbbra is tartalmazza a `code_challenge`értéket, akkor a `code_challenge` függvény egyszerű szövegnek számít. Microsoft Identitásplatform támogatja a és a `S256`elemet is`plain`. További információ: PKCE RFC. Ez az engedélyezési kódfolyamatot használó egyoldalas alkalmazások esetében szükséges.
login_hint	No	A bejelentkezési oldal bejelentkezési név mezőjének előzetes kitöltésére használható. További információ: A bejelentkezési név előzetes feltöltése.
domain_hint	No	A B2C Azure AD a bejelentkezéshez használandó közösségi identitásszolgáltatóra vonatkozó tippet nyújt. Ha érvényes értéket tartalmaz, a felhasználó közvetlenül az identitásszolgáltató bejelentkezési oldalára kerül. További információ: Bejelentkezés átirányítása közösségi szolgáltatóhoz.
Egyéni paraméterek	No	Egyéni szabályzatokkal használható egyéni paraméterek. Például dinamikus egyéni laptartalom URI-ja vagy kulcs-érték jogcímfeloldók.

Ekkor a rendszer felkéri a felhasználót, hogy fejezze be a felhasználói folyamat munkafolyamatát. Ez magában foglalhatja a felhasználó felhasználónevét és jelszavát, a közösségi identitással való bejelentkezést, a címtárra való regisztrációt vagy bármilyen más lépést. A felhasználói műveletek a felhasználói folyamat definiálásától függenek.

Miután a felhasználó befejezte a felhasználói folyamatot, Microsoft Entra azonosító választ ad vissza az alkalmazásnak a használt értékenredirect_uri. A paraméterben megadott metódust response_mode használja. A válasz minden felhasználói műveleti forgatókönyv esetében pontosan ugyanaz, függetlenül a végrehajtott felhasználói folyamattól.

A következőhöz hasonló sikeres válasz response_mode=query :

GET urn:ietf:wg:oauth:2.0:oob?
code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...        // the authorization_code, truncated
&state=arbitrary_data_you_can_receive_in_the_response                // the value provided in the request

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 egy célerőforráshoz. Az engedélyezési kódok nagyon rövid élettartamúak. Általában körülbelül 10 perc elteltével járnak le.
állapot	Tekintse meg a teljes leírást az előző szakaszban található táblázatban. 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 `state` kérésben és a válaszban szereplő értékek azonosak-e.

A hibaválaszok elküldhetők az átirányítási URI-nak is, hogy az alkalmazás megfelelően kezelje őket:

GET urn:ietf:wg:oauth:2.0:oob?
error=access_denied
&error_description=The+user+has+cancelled+entering+self-asserted+information
&state=arbitrary_data_you_can_receive_in_the_response

Paraméter	Leírás
error	Hibakódsztring, amellyel osztályozhatja a felmerülő hibatípusokat. A sztring használatával is reagálhat a hibákra.
error_description	Egy adott hibaüzenet, amely segíthet azonosítani a hitelesítési hiba kiváltó okát.
állapot	Tekintse meg a teljes leírást az előző táblázatban. 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 `state` kérésben és a válaszban szereplő értékek azonosak-e.

2. Hozzáférési jogkivonat lekérése

Most, hogy beszerezte az engedélyezési kódot, beválthatja a code jogkivonatot a kívánt erőforrásra egy POST-kérés végpontra /token küldésével. A Azure AD B2C-ben a szokásos módon kérhet hozzáférési jogkivonatokat más API-khoz a kérelemben megadott hatókör(ek) megadásával.

Hozzáférési jogkivonatot is kérhet az alkalmazás saját háttérbeli webes API-jához, ha konvenció szerint az alkalmazás ügyfél-azonosítóját használja a kért hatókörként (ami egy hozzáférési jogkivonatot eredményez, amely az adott ügyfél-azonosítót fogja "célközönségként" használni):

POST https://{tenant}.b2clogin.com/{tenant}.onmicrosoft.com/{policy}/oauth2/v2.0/token HTTP/1.1

Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&client_id=90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6
&scope=90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6 offline_access
&code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&redirect_uri=urn:ietf:wg:oauth:2.0:oob
&code_verifier=ThisIsntRandomButItNeedsToBe43CharactersLong

Paraméter	Kötelező?	Description
{tenant}	Kötelező	A Azure AD B2C-bérlő neve
{policy}	Kötelező	Az engedélyezési kód beszerzéséhez használt felhasználói folyamat. Ebben a kérelemben nem használhat másik felhasználói folyamatot.
client_id	Kötelező	Az alkalmazáshoz rendelt alkalmazásazonosító a Azure Portal.
client_secret	Igen, Web Apps	A Azure Portal létrehozott alkalmazáskulcs. Ebben a folyamatban ügyfélkulcsokat használunk webalkalmazás-forgatókönyvekhez, ahol az ügyfél biztonságosan tárolhat titkos ügyfélkódokat. Natív alkalmazások (nyilvános ügyfél) esetén az ügyfélkulcsok nem tárolhatók biztonságosan, ezért nem használhatók ebben a hívásban. Ha titkos ügyfélkulcsot használ, rendszeresen módosítsa.
grant_type	Kötelező	A támogatás típusa. Az engedélyezési kód folyamatához a megadás típusának kell lennie `authorization_code`.
scope	Ajánlott	A hatókörök szóközzel elválasztott listája. Egyetlen hatókörérték jelzi, hogy Microsoft Entra mindkét kért engedély azonosítóját. Az ügyfél-azonosító hatókörként való használata azt jelzi, hogy az alkalmazásnak szüksége van egy hozzáférési jogkivonatra, amelyet a saját szolgáltatásához vagy webes API-hoz használhat, amelyet ugyanaz az ügyfél-azonosító jelöl. A `offline_access` hatókör azt jelzi, hogy az alkalmazásnak frissítési jogkivonatra van szüksége az erőforrásokhoz való hosszú élettartamú hozzáféréshez. A hatókör használatával `openid` id tokent is kérhet Azure AD B2C-től.
code	Kötelező	A végpontról `/authorize` beszerzett engedélyezési kód.
redirect_uri	Kötelező	Annak az alkalmazásnak az átirányítási URI-ja, ahol megkapta az engedélyezési kódot.
code_verifier	Ajánlott	Ugyanaz `code_verifier` , mint az engedélyezési kód lekéré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.

Ha teszteli ezt a POST HTTP-kérést, bármilyen HTTP-ügyfelet használhat, például a Microsoft PowerShellt vagy a Postmant.

A sikeres jogkivonat-válasz így néz ki:

{
    "not_before": "1442340812",
    "token_type": "Bearer",
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
    "scope": "90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6 offline_access",
    "expires_in": "3600",
    "refresh_token": "AAQfQmvuDy8WtUv-sd0TBwWVQs1rC-Lfxa_NDkLqpg50Cxp5Dxj0VPF1mx2Z...",
}

Paraméter	Leírás
not_before	Az az időpont, amikor a jogkivonat érvényesnek minősül, az alapidőszakban.
token_type	A jogkivonat típusának értéke. Az egyetlen típus, amelyet Microsoft Entra azonosító támogat, a Tulajdonos.
access_token	A kért aláírt JSON webes jogkivonat (JWT).
scope	Azok a hatókörök, amelyekre a jogkivonat érvényes. Hatókörök használatával is gyorsítótárazhatja a jogkivonatokat későbbi használatra.
expires_in	A jogkivonat érvényességének időtartama (másodpercben).
refresh_token	Egy OAuth 2.0 frissítési jogkivonat. Az alkalmazás ezzel a jogkivonattal további jogkivonatokat szerezhet be az aktuális jogkivonat lejárata után. A frissítési jogkivonatok hosszú élettartamúak. Ezekkel hosszabb ideig megőrizheti az erőforrásokhoz való hozzáférést. További információ: Azure AD B2C-token referenciája.

A hibaválaszok a következőképpen néznek ki:

{
    "error": "access_denied",
    "error_description": "The user revoked access to the app.",
}

Paraméter	Leírás
error	Hibakódsztring, amellyel osztályozhatja a felmerülő hibatípusokat. A sztring használatával is reagálhat a hibákra.
error_description	Egy adott hibaüzenet, amely segíthet azonosítani a hitelesítési hiba kiváltó okát.

3. A jogkivonat használata

Most, hogy sikeresen beszerezte a hozzáférési jogkivonatot, használhatja a jogkivonatot a háttérbeli webes API-knak küldött kérésekben, ha beleveszi azt a Authorization fejlécbe:

GET /tasks
Host: mytaskwebapi.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...

4. A jogkivonat frissítése

A hozzáférési jogkivonatok és az azonosító jogkivonatok rövid élettartamúak. A lejáratuk után frissítenie kell őket, hogy továbbra is hozzáférjenek az erőforrásokhoz. A hozzáférési jogkivonat frissítésekor Azure AD B2C egy új jogkivonatot ad vissza. A frissített hozzáférési jogkivonat frissülni nbf fog (nem korábban), iat (a kiállítás időpontja) és exp (lejárati) jogcímértékek. Minden más jogcímérték megegyezik az eredetileg kiadott hozzáférési jogkivonattal.

A jogkivonat frissítéséhez küldjön egy másik POST kérést a /token végpontnak. Ezúttal adja meg a refresh_token elemet a helyett:code

POST https://{tenant}.b2clogin.com/{tenant}.onmicrosoft.com/{policy}/oauth2/v2.0/token HTTP/1.1

Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&client_id=90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6
&scope=90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6 offline_access
&refresh_token=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&redirect_uri=urn:ietf:wg:oauth:2.0:oob

Paraméter	Kötelező?	Description
{tenant}	Kötelező	A Azure AD B2C-bérlő neve
{policy}	Kötelező	Az eredeti frissítési jogkivonat beszerzéséhez használt felhasználói folyamat. Ebben a kérelemben nem használhat másik felhasználói folyamatot.
client_id	Kötelező	Az alkalmazáshoz rendelt alkalmazásazonosító a Azure Portal.
client_secret	Igen, Web Apps	A Azure Portal létrehozott alkalmazáskulcs. Ebben a folyamatban ügyfélkulcsokat használunk webalkalmazás-forgatókönyvekhez, ahol az ügyfél biztonságosan tárolhat titkos ügyfélkódokat. Natív alkalmazások (nyilvános ügyfél) esetén az ügyfélkulcsok nem tárolhatók biztonságosan, ezért nem használhatók ebben a hívásban. Ha titkos ügyfélkulcsot használ, rendszeresen módosítsa.
grant_type	Kötelező	A támogatás típusa. Az engedélyezési kód folyamatának ezen szakaszához a megadás típusának kell lennie `refresh_token`.
scope	Ajánlott	A hatókörök szóközzel elválasztott listája. Egyetlen hatókörérték jelzi, hogy Microsoft Entra mindkét kért engedély azonosítóját. Az ügyfél-azonosító hatókörként való használata azt jelzi, hogy az alkalmazásnak szüksége van egy hozzáférési jogkivonatra, amelyet a saját szolgáltatásához vagy webes API-hoz használhat, amelyet ugyanaz az ügyfél-azonosító jelöl. A `offline_access` hatókör azt jelzi, hogy az alkalmazásnak frissítési jogkivonatra lesz szüksége az erőforrásokhoz való hosszú élettartamú hozzáféréshez. A hatókör használatával `openid` id tokent is kérhet Azure AD B2C-től.
redirect_uri	Választható	Annak az alkalmazásnak az átirányítási URI-ja, ahol megkapta az engedélyezési kódot.
refresh_token	Kötelező	A folyamat második szakaszában beszerzett eredeti frissítési jogkivonat.