Hozzáférés engedélyezése webalkalmazásoknak OpenID Connect és az Azure Active Directory használatával

  • Cikk

Figyelmeztetés

Ez a tartalom a régebbi Azure AD 1.0-s verziójú végponthoz tartozik. Használja a Microsoft Identitásplatform új projektekhez.

Az OpenID Connect egy egyszerű identitásréteg, amely az OAuth 2.0 protokollra épül. Az OAuth 2.0 olyan mechanizmusokat határoz meg, amelyekkel hozzáférési jogkivonatokat szerezhet be és használhat a védett erőforrások eléréséhez, de nem határoznak meg szabványos módszereket az identitásadatok biztosításához. Az OpenID Connect az OAuth 2.0 engedélyezési folyamat kiterjesztéseként implementálja a hitelesítést. A végfelhasználóval kapcsolatos információkat biztosít olyan id_token formában, amely ellenőrzi a felhasználó identitását, és alapvető profiladatokat biztosít a felhasználóról.

Az OpenID Connect a mi javaslatunk, ha egy kiszolgálón üzemeltetett és böngészőn keresztül elérhető webalkalmazást hoz létre.

Alkalmazás regisztrálása az AD-bérlőben

Először regisztrálja az alkalmazást az Azure Active Directory-bérlőben (Azure AD). Ekkor kapni fog egy alkalmazásazonosítót az alkalmazáshoz, amely immár képes jogkivonatokat fogadni.

  1. Jelentkezzen be az Azure Portalra.

  2. Válassza ki a Azure AD bérlőt a lap jobb felső sarkában található fiók kiválasztásával, majd válassza a Címtárváltás navigációt, majd válassza ki a megfelelő bérlőt.

    • Hagyja ki ezt a lépést, ha csak egy Azure AD bérlő van a fiókjában, vagy ha már kiválasztotta a megfelelő Azure AD bérlőt.

  3. A Azure Portal keresse meg és válassza az Azure Active Directory lehetőséget.

  4. Az Azure Active Directory bal oldali menüjében válassza az Alkalmazásregisztrációk, majd az Új regisztráció lehetőséget.

  5. Kövesse az utasításokat az új alkalmazás létrehozásához. Nem számít, hogy webalkalmazásról vagy nyilvános ügyfélalkalmazásról (mobil & asztali) van-e szó, de ha konkrét példákra van szüksége webalkalmazásokhoz vagy nyilvános ügyfélalkalmazásokhoz, tekintse meg a rövid útmutatókat.

    • A név az alkalmazás neve, amely a végfelhasználók számára ad leírást az alkalmazásról.
    • A Támogatott fióktípusok területen válassza a Fiókok lehetőséget bármely szervezeti címtárban és személyes Microsoft-fiókban.
    • Adja meg az átirányítási URI-t. Webalkalmazások esetén ez az alkalmazás alap URL-címe, ahová a felhasználók bejelentkezhetnek. Például: http://localhost:12345. Nyilvános ügyfél (mobil & asztali) esetén Azure AD tokenválaszok visszaadására használja. Adja meg az alkalmazáshoz tartozó értéket. Például: http://MyFirstAADApp.

  6. A regisztráció befejezése után Azure AD egyedi ügyfél-azonosítót (alkalmazásazonosítót) rendel az alkalmazáshoz. Erre az értékre szüksége lesz a következő szakaszokban, ezért másolja ki az alkalmazás oldaláról.

  7. Ha meg szeretné keresni az alkalmazást a Azure Portal, válassza a Alkalmazásregisztrációk, majd az Összes alkalmazás megtekintése lehetőséget.

Hitelesítési folyamat az OpenID Connect használatával

A legalapvetőbb bejelentkezési folyamat a következő lépéseket tartalmazza – ezeket az alábbiakban részletesen ismertetjük.

OpenId Connect hitelesítési folyamat

OpenID Connect-metaadat-dokumentum

Az OpenID Connect egy metaadat-dokumentumot ír le, amely a bejelentkezés végrehajtásához szükséges legtöbb információt tartalmazza. Ide tartoznak például a használandó URL-címek és a szolgáltatás nyilvános aláírókulcsainak helye. Az OpenID Connect metaadat-dokumentuma a következő helyen található:

https://login.microsoftonline.com/{tenant}/.well-known/openid-configuration

A metaadatok egy egyszerű JavaScript Object Notation -dokumentum (JSON). Egy példát az alábbi kódrészletben talál. A kódrészlet tartalmát az OpenID Connect specifikációja tartalmazza. Vegye figyelembe, hogy a fenti {tenant} helyett bérlőazonosító common megadása bérlőspecifikus URI-kat eredményez a visszaadott JSON-objektumban.

{
    "authorization_endpoint": "https://login.microsoftonline.com/{tenant}/oauth2/authorize",
    "token_endpoint": "https://login.microsoftonline.com/{tenant}/oauth2/token",
    "token_endpoint_auth_methods_supported":
    [
        "client_secret_post",
        "private_key_jwt",
        "client_secret_basic"
    ],
    "jwks_uri": "https://login.microsoftonline.com/common/discovery/keys"
    "userinfo_endpoint":"https://login.microsoftonline.com/{tenant}/openid/userinfo",
    ...
}

Ha az alkalmazás egyéni aláírókulcsokkal rendelkezik a jogcímleképezési funkció használata miatt, hozzá kell fűznie egy appid , az alkalmazásazonosítót tartalmazó lekérdezési paramétert, hogy jwks_uri az alkalmazás aláírókulcs-adataira mutasson. Például: https://login.microsoftonline.com/{tenant}/.well-known/openid-configuration?appid=6731de76-14a6-49ae-97bc-6eba6914391e egy a-t https://login.microsoftonline.com/{tenant}/discovery/keys?appid=6731de76-14a6-49ae-97bc-6eba6914391ejwks_uri tartalmaz.

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

Ha a webalkalmazásnak hitelesítenie kell a felhasználót, a felhasználót a /authorize végponthoz kell irányítania. Ez a kérés hasonlít az OAuth 2.0 engedélyezési kódfolyamat első szakaszához, néhány fontos különbséggel:

  • A kérelemnek tartalmaznia kell a hatókört openid a scope paraméterben.
  • A response_type paraméternek tartalmaznia kell a következőt id_token: .
  • A kérelemnek tartalmaznia kell a paramétert nonce .

Egy mintakérés így nézne ki:

// Line breaks for legibility only

GET https://login.microsoftonline.com/{tenant}/oauth2/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&response_type=id_token
&redirect_uri=http%3A%2F%2Flocalhost%3a12345
&response_mode=form_post
&scope=openid
&state=12345
&nonce=7362CAEA-9CA5-4B43-9BA3-34D7C303EBA7
Paraméter Típus Description
Bérlő kötelező A {tenant} kérés elérési útjának értéke annak szabályozására használható, hogy ki jelentkezhet be az alkalmazásba. Az engedélyezett értékek például bérlőazonosítók, 8eaef023-2b34-4da1-9baa-8bc8c9d6a490 vagy contoso.onmicrosoft.comcommon bérlőfüggetlen jogkivonatok
client_id kötelező Az alkalmazáshoz rendelt alkalmazásazonosító, amikor regisztrálta azt Azure AD. Ezt a Azure Portal találja. Kattintson az Azure Active Directory elemre, kattintson az Alkalmazásregisztrációk elemre, válassza ki az alkalmazást, és keresse meg az alkalmazásazonosítót az alkalmazás oldalán.
response_type kötelező Tartalmaznia id_token kell az OpenID Connect-bejelentkezést. Más response_types is tartalmazhat, például code vagy token.
scope Ajánlott Az OpenID Connect specifikációja megköveteli a hatókört openid, amely a hozzájárulás felhasználói felületén található "Bejelentkezés" engedélyre fordítható. Ezt és más OIDC-hatóköröket a rendszer figyelmen kívül hagyja az 1.0-s verziójú végponton, de továbbra is ajánlott eljárás a szabványoknak megfelelő ügyfelek esetében.
nemce kötelező A kérelemben szereplő, az alkalmazás által létrehozott érték, amely az eredményben id_token jogcímként szerepel. Az alkalmazás ezután ellenőrizheti ezt az értéket a jogkivonat-visszajátszási támadások mérséklése érdekében. Az érték általában egy véletlenszerű, egyedi sztring vagy GUID, amely a kérés eredetének azonosítására használható.
redirect_uri Ajánlott Az alkalmazás redirect_uri, ahol az alkalmazás hitelesítési válaszokat küldhet és fogadhat. Pontosan egyeznie kell a portálon regisztrált redirect_uris egyikével, kivéve, hogy URL-kódolásúnak kell lennie. Ha hiányzik, a rendszer véletlenszerűen visszaküldi a felhasználói ügynököt az alkalmazáshoz regisztrált átirányítási URI-k egyikének. A maximális hossz 255 bájt
response_mode választható Megadja azt a metódust, amellyel az eredményül kapott authorization_code vissza lehet küldeni az alkalmazásnak. A támogatott értékek a form_postHTTP-űrlap bejegyzéseihez és fragment az URL-töredékhez tartoznak. Webalkalmazások esetén a használatával response_mode=form_post biztosíthatja a jogkivonatok alkalmazásba történő legbiztonságosabb átvitelét. A id_token is tartalmazó folyamatok alapértelmezett értéke a fragment.
állapot Ajánlott A jogkivonat-válaszban visszaadott kérésben szereplő érték. Bármilyen tartalom sztringje lehet. A véletlenszerűen generált egyedi érték általában a helyek közötti kéréshamisí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érés előtt, például a lapon vagy a megtekintésben.
Gyors választható Azt jelzi, hogy milyen típusú felhasználói beavatkozásra van szükség. Jelenleg az egyetlen érvényes érték a "login", a "none" és a "consent". prompt=login kényszeríti a felhasználót, hogy adja meg a hitelesítő adatait a kérelemben, ne pedig az egyszeri bejelentkezést. prompt=none az ellenkezője – biztosítja, hogy a felhasználó semmilyen interaktív kérdésben ne jelenjen meg. Ha a kérés nem hajtható végre csendesen egyszeri bejelentkezéssel, a végpont hibát ad vissza. prompt=consent aktiválja az OAuth-hozzájárulás párbeszédpanelt, miután a felhasználó bejelentkezett, és megkéri a felhasználót, hogy adjon engedélyeket az alkalmazásnak.
login_hint választható A felhasználó bejelentkezési oldalának felhasználónév/e-mail-cím mezőjének előre kitöltésére használható, ha előre ismeri a felhasználónevét. Az alkalmazások gyakran használják ezt a paramétert az újrahitelesítés során, miután már kinyerték a felhasználónevet egy korábbi bejelentkezésből a preferred_username jogcím használatával.

Ekkor a felhasználónak meg kell adnia a hitelesítő adatait, és be kell fejeznie a hitelesítést.

Mintaválasz

A bejelentkezési kérelemben megadott, a felhasználó hitelesítése után küldött redirect_uri mintaválasz a következőképpen nézhet ki:

POST / HTTP/1.1
Host: localhost:12345
Content-Type: application/x-www-form-urlencoded

id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNB...&state=12345
Paraméter Leírás
id_token Az id_token alkalmazás által kért. A használatával id_token ellenőrizheti a felhasználó identitását, és munkamenetet indíthat a felhasználóval.
állapot A kérésben szereplő érték, amelyet a rendszer a jogkivonat-válaszban is visszaad. A véletlenszerűen generált egyedi érték általában a helyek közötti kéréshamisí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érés előtt, például a lapon vagy a megtekintésben.

Hibaválasz

A hibaválaszokat is elküldheti az redirect_uri alkalmazásnak, hogy azok megfelelően kezelhetők legyenek:

POST / HTTP/1.1
Host: localhost:12345
Content-Type: application/x-www-form-urlencoded

error=access_denied&error_description=the+user+canceled+the+authentication
Paraméter Leírás
error Hibakódsztring, amely a felmerülő 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 hiba kiváltó okát.

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 Description Ü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 egy fejlesztési hiba, amelyet általában a kezdeti tesztelés során észlelnek.
unauthorized_client Az ügyfélalkalmazás nem kérhet engedélyezési kódot. Ez általában akkor fordul elő, ha az ügyfélalkalmazás nincs regisztrálva Azure AD, vagy nincs hozzáadva a felhasználó Azure AD bérlőhöz. Az alkalmazás megkérheti a felhasználót az alkalmazás telepítésére és Azure AD való hozzáadására.
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 egy fejlesztési hiba, amelyet általában a kezdeti tesztelés során észlelnek.
server_error A kiszolgáló váratlan hibát észlelt. Ismételje meg a kérést. Ezek a hibák ideiglenes feltételekből adódhatnak. Az ügyfélalkalmazás elmagyarázhatja a felhasználónak, hogy a válasza egy ideiglenes hiba miatt 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, 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 megkérheti a felhasználót az alkalmazás telepítésére és Azure AD való hozzáadására.

A id_token ellenőrzése

A felhasználó hitelesítéséhez nem elegendő csak egy id_token fogadás; ellenőriznie kell az aláírást, és ellenőriznie kell a jogcímeket az id_token alkalmazás követelményeinek megfelelően. A Azure AD végpont JSON webes jogkivonatokat (JWT-ket) és nyilvános kulcsú titkosítást használ a tokenek aláírásához és érvényességének ellenőrzéséhez.

Dönthet úgy, hogy érvényesíti az id_token ügyfélkódban szereplő kódot, de gyakori eljárás, hogy elküldi a id_token parancsot egy háttérkiszolgálónak, és ott hajtja végre az ellenőrzést.

A forgatókönyvtől függően további jogcímeket is érvényesíthet. Néhány gyakori ellenőrzés:

  • Annak biztosítása, hogy a felhasználó/szervezet regisztrált az alkalmazásra.
  • Győződjön meg arról, hogy a felhasználó rendelkezik a megfelelő engedélyekkel/jogosultságokkal a vagy roles jogcímek wids használatával.
  • A hitelesítés bizonyos erősségének biztosítása, például a többtényezős hitelesítés.

A érvényesítése után megkezdheti a id_tokenmunkamenetet a felhasználóval, és a(z) id_token jogcímeivel információkat szerezhet a felhasználóról az alkalmazásban. Ezek az információk megjeleníthetők, rögzíthetők, személyre szabhatók stb. A és jogcímekkel kapcsolatos id_tokens további információkért olvassa el az AAD id_tokens című cikket.

Kijelentkezés kérésének küldése

Ha ki szeretné jelentkezni a felhasználót az alkalmazásból, nem elegendő törölni az alkalmazás cookie-ját, vagy más módon befejezni a munkamenetet a felhasználóval. A felhasználót is át kell irányítania a end_session_endpoint kijelentkezéshez. Ha ezt nem teszi meg, a felhasználó újrahitelesítheti az alkalmazást anélkül, hogy újból meg kellene adnia a hitelesítő adatait, mivel érvényes egyszeri bejelentkezési munkamenettel fog rendelkezni a Azure AD végponttal.

Egyszerűen átirányíthatja a felhasználót az end_session_endpoint OpenID Connect metaadat-dokumentumában felsoroltakhoz:

GET https://login.microsoftonline.com/common/oauth2/logout?
post_logout_redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
Paraméter Típus Description
post_logout_redirect_uri Ajánlott Az URL-cím, amellyel a felhasználót át kell irányítani a sikeres kijelentkezés után. Ennek az URL-címnek meg kell egyeznie az alkalmazáshoz regisztrált átirányítási URI-k egyikével az alkalmazásregisztrációs portálon. Ha a post_logout_redirect_uri nem tartalmazza, a felhasználó egy általános üzenetet jelenít meg.

Egyszeri kijelentkezés

Amikor átirányítja a felhasználót a end_session_endpoint-ra, Azure AD törli a felhasználó munkamenetét a böngészőből. Előfordulhat azonban, hogy a felhasználó továbbra is be van jelentkezve más alkalmazásokba, amelyek Azure AD használnak hitelesítésre. Ha engedélyezni szeretné ezeknek az alkalmazásoknak, hogy egyidejűleg kijelentkeztethessék a felhasználót, Azure AD http GET kérést küld az összes regisztrált LogoutUrl alkalmazásnak, amelybe a felhasználó jelenleg bejelentkezett. Az alkalmazásoknak úgy kell válaszolniuk erre a kérésre, hogy törlik a felhasználót azonosító munkameneteket, és választ adnak 200 vissza. Ha támogatni szeretné az egyszeri kijelentkezés használatát az alkalmazásban, ezt implementálnia LogoutUrl kell az alkalmazás kódjában. A értéket a Azure Portal állíthatja beLogoutUrl:

  1. Jelentkezzen be az Azure Portalra.
  2. Válassza ki az Active Directoryt a lap jobb felső sarkában található fiókra kattintva.
  3. A bal oldali navigációs panelen válassza az Azure Active Directory, majd a Alkalmazásregisztrációk lehetőséget, és válassza ki az alkalmazást.
  4. Kattintson a Beállítások, majd a Tulajdonságok elemre, és keresse meg a Kijelentkezési URL-cím szövegmezőt.

Jogkivonat beszerzése

Számos webalkalmazásnak nem csak be kell jelentkeznie a felhasználóba, hanem egy webszolgáltatáshoz is hozzá kell férnie a felhasználó nevében az OAuth használatával. Ez a forgatókönyv az OpenID Connectet kombinálja a felhasználói hitelesítéshez, miközben egyidejűleg beszerez egy authorization_code olyant, amely az OAuth engedélyezési kódfolyamatának használatához használhatóaccess_tokens.

Hozzáférési jogkivonatok lekérése

Hozzáférési jogkivonatok beszerzéséhez módosítania kell a fenti bejelentkezési kérést:

// Line breaks for legibility only

GET https://login.microsoftonline.com/{tenant}/oauth2/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e        // Your registered Application ID
&response_type=id_token+code
&redirect_uri=http%3A%2F%2Flocalhost%3a12345          // Your registered Redirect Uri, url encoded
&response_mode=form_post                              // `form_post' or 'fragment'
&scope=openid
&resource=https%3A%2F%2Fservice.contoso.com%2F        // The identifier of the protected resource (web API) that your application needs access to
&state=12345                                          // Any value, provided by your app
&nonce=678910                                         // Any value, provided by your app

Ha engedélyhatóköröket is beszúr a kérelembe és a használatával response_type=code+id_token, a authorize végpont biztosítja, hogy a felhasználó hozzájárult a scope lekérdezési paraméterben megadott engedélyekhez, és visszaadja az alkalmazásnak a hozzáférési jogkivonat cseréjéhez szükséges engedélyezési kódot.

Sikeres válasz

A használatával response_mode=form_postküldött redirect_uri sikeres válasz a következőképpen néz ki:

POST /myapp/ HTTP/1.1
Host: localhost
Content-Type: application/x-www-form-urlencoded

id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNB...&code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...&state=12345
Paraméter Leírás
id_token Az id_token alkalmazás által kért. A használatával id_token ellenőrizheti a felhasználó identitását, és munkamenetet indíthat a felhasználóval.
code Az alkalmazás által kért authorization_code. 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 élettartamúak, és általában körülbelül 10 perc elteltével lejárnak.
állapot 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 a rendszer a következő címre redirect_uri is elküldheti, hogy az alkalmazás megfelelően kezelje őket:

POST /myapp/ HTTP/1.1
Host: localhost
Content-Type: application/x-www-form-urlencoded

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 azonosítani a hitelesítési hiba kiváltó okát.

A lehetséges hibakódok és a javasolt ügyfélművelet leírását lásd: Az engedélyezési végpont hibáinak hibakódjai.

Miután megkapta az engedélyt code és a -t id_token, bejelentkeztetheti a felhasználót, és hozzáférési jogkivonatokat szerezhet be a nevükben. A felhasználó bejelentkezéséhez pontosan a fent leírt módon kell ellenőriznie id_token . A hozzáférési jogkivonatok beszerzéséhez kövesse az OAuth-kódfolyamat dokumentációjának "Hozzáférési jogkivonat kérése az engedélyezési kód használatával" című szakaszában leírt lépéseket.

Következő lépések