Engedélyek és hozzájárulás a Microsoft-identitásplatformon

  • Cikk
  • 22 perc alatt elolvasható

A Microsoft identitásplatformjával integrálható alkalmazások olyan engedélyezési modellt követnek, amely lehetővé teszi a felhasználók és a rendszergazdák számára az adatok elérésének szabályozását. Az engedélyezési modell implementációja frissült a Microsoft identitásplatformján. Megváltoztatja, hogyan kell az alkalmazásnak kommunikálnia a Microsoft identitásplatformjával. Ez a cikk az engedélyezési modell alapvető fogalmait ismerteti, beleértve a hatóköröket, az engedélyeket és a hozzájárulást.

Hatókörök és engedélyek

A Microsoft identitásplatformja implementálja az OAuth 2.0 engedélyezési protokollt . Az OAuth 2.0 egy olyan módszer, amellyel egy külső alkalmazás hozzáférhet a webre üzemeltetett erőforrásokhoz egy felhasználó nevében. Minden, a Microsoft identitásplatformjával integrálható webes erőforrás rendelkezik erőforrás-azonosítóval vagy alkalmazásazonosító URI-val.

Íme néhány példa a Microsoft által üzemeltetett erőforrásokra:

  • Microsoft Graph: https://graph.microsoft.com
  • Microsoft 365 Mail API: https://outlook.office.com
  • Azure Key Vault: https://vault.azure.net

Ugyanez vonatkozik a Microsoft identitásplatformjával integrált külső erőforrásokra is. Ezen erőforrások bármelyike meghatározhat egy engedélykészletet is, amellyel az erőforrás funkcióit kisebb adattömbökre oszthatja. Például a Microsoft Graph többek között a következő feladatok végrehajtására vonatkozó engedélyeket határozott meg:

  • Felhasználó naptárának olvasása
  • Írás a felhasználó naptárában
  • E-mail küldése felhasználóként

Az ilyen típusú engedélydefiníciók miatt az erőforrás részletesen szabályozza az adatokat, és hogy az API-funkciók hogyan lesznek elérhetővé téve. Egy külső alkalmazás kérheti ezeket az engedélyeket a felhasználóktól és a rendszergazdáktól, akiknek jóvá kell hagyniuk a kérést ahhoz, hogy az alkalmazás hozzáférhessen az adatokhoz, vagy eljárjon a felhasználó nevében.

Ha egy erőforrás funkciói kis engedélykészletekre vannak osztva, külső alkalmazások is létrehozhatók, hogy csak azokat az engedélyeket kérjék le, amelyekre szükségük van a funkciójuk végrehajtásához. A felhasználók és a rendszergazdák tudni tudják, milyen adatokhoz férhetnek hozzá az alkalmazás. És biztosak lehetnek abban, hogy az alkalmazás nem rosszindulatú szándékkal viselkedik. A fejlesztőknek mindig be kell tartaniuk a minimális jogosultság elvét, és csak azokat az engedélyeket kell kérniük, amelyekre az alkalmazásaik működéséhez szükségük van.

Az OAuth 2.0-ban az ilyen típusú engedélykészleteket hatóköröknek nevezzük. Ezeket gyakran engedélyeknek is nevezik. A Microsoft identitásplatformon az engedély sztringértékként jelenik meg. Egy alkalmazás a lekérdezési paraméterben megadott engedély megadásával kéri le a scope szükséges engedélyeket. Az identitásplatform számos jól definiált OpenID Connect-hatókört és erőforrás-alapú engedélyeket támogat (az egyes engedélyeket az engedély értékének az erőforrás azonosítójának vagy alkalmazásazonosítójának URI-jának hozzáfűzésével jelöljük). Az engedélysztring https://graph.microsoft.com/Calendars.Read például arra szolgál, hogy engedélyt kérjen a felhasználói naptárak olvasásához a Microsoft Graphban.

Az alkalmazások leggyakrabban a Microsoft identitásplatform engedélyezési végpontjának küldött kérelmek hatóköreinek megadásával kérik le ezeket az engedélyeket. Egyes magas jogosultsági szintű engedélyek azonban csak rendszergazdai hozzájárulással adhatók meg. Ezek a rendszergazdai hozzájárulási végpont használatával kérhetők vagy adhatók meg. További információért olvasson tovább.

A Microsoft Identity platform engedélyezési, jogkivonat- vagy hozzájárulási végpontjaira irányuló kérésekben, ha az erőforrás-azonosító nincs megadva a hatókör paraméterben, akkor az erőforrást a microsoft graphnak feltételezi a rendszer. Például a scope=User.Read egyenértékű a következővel: https://graph.microsoft.com/User.Read.

Engedélytípusok

A Microsoft identitásplatformja kétféle engedélyt támogat: delegált engedélyeket és alkalmazásengedélyeket.

  • A delegált engedélyeket olyan alkalmazások használják, amelyek bejelentkezett felhasználóval rendelkeznek. Ezekben az alkalmazásokban a felhasználó vagy egy rendszergazda elfogadja az alkalmazás által kért engedélyeket. Az alkalmazás delegált engedélyt kap arra, hogy bejelentkezett felhasználóként viselkedjen a célerőforrások hívásakor.

    Egyes delegált engedélyeket nemminisztrátorok is jóváhagyhatnak. Bizonyos magas jogosultsági szintű engedélyekhez azonban rendszergazdai hozzájárulás szükséges. Ha meg szeretné tudni, hogy mely rendszergazdai szerepkörök járulhatnak hozzá a delegált engedélyekhez, tekintse meg az Azure Active Directory (Azure AD) rendszergazdai szerepkör-engedélyeit.

  • Az alkalmazásengedélyeket olyan alkalmazások használják, amelyek bejelentkezett felhasználó nélkül futnak, például háttérszolgáltatásként vagy démonként futó alkalmazások. Csak a rendszergazda hagyhatja jóvá az alkalmazásengedélyeket.

Az érvényes engedélyek azok az engedélyek, amelyekkel az alkalmazás rendelkezik, amikor kéréseket küld a célerőforrásnak. Fontos tisztában lenni azzal, hogy mi a különbség az alkalmazás által megadott delegált engedélyek és alkalmazásengedélyek között, és hogy az alkalmazás milyen érvényes engedélyeket kap a célerőforrás felé irányuló hívások során.

  • A delegált engedélyek esetében az alkalmazás érvényes engedélyei az alkalmazás által (hozzájárulással) megadott delegált engedélyek és az aktuálisan bejelentkezett felhasználó jogosultságainak legalacsonyabb jogosultsági szintű metszetei. Az alkalmazásnak soha nem lehet több jogosultsága, mint a bejelentkezett felhasználónak.

    A szervezeteken belül a bejelentkezett felhasználó jogosultságait szabályzat vagy egy vagy több rendszergazdai szerepkör tagsága határozza meg. Ha meg szeretné tudni, hogy mely rendszergazdai szerepkörök adhatjanak hozzájárulást a delegált engedélyekhez, tekintse meg a rendszergazdai szerepkörök engedélyeit az Azure AD-ben.

    Tegyük fel például, hogy az alkalmazás megkapta a User.ReadWrite.All delegált engedélyt. Ez az engedély névlegesen ad engedélyt az alkalmazás számára egy cégben lévő összes felhasználó profiljának olvasásához és frissítéséhez. Ha a bejelentkezett felhasználó globális rendszergazda, az alkalmazás a szervezet minden felhasználójának profilját frissítheti. Ha azonban a bejelentkezett felhasználónak nincs rendszergazdai szerepköre, az alkalmazás csak a bejelentkezett felhasználó profilját frissítheti. Nem tudja frissíteni a szervezet más felhasználóinak profiljait, mert az a felhasználó, akinek a nevében eljárhat, nem rendelkezik ezekkel a jogosultságokkal.

  • Az alkalmazásengedélyek esetében az alkalmazás érvényes engedélyei az engedély által vélelmezett jogosultságok teljes szintje. Például egy User.ReadWrite.All alkalmazás engedéllyel rendelkező alkalmazás frissítheti a szervezet minden felhasználójának profilját.

OpenID Connect-hatókörök

Az OpenID Connect Microsoft identitásplatform-implementációja néhány jól definiált hatókörrel rendelkezik, amelyek a Microsoft Graphon is futnak: openid, email, , profileés offline_access. phone Az address OpenID Connect és a hatókörök nem támogatottak.

Ha az OpenID Connect hatóköreit és egy jogkivonatot kér, egy jogkivonatot kap a UserInfo végpont meghívásához.

Openid

Ha egy alkalmazás openID Connect használatával jelentkezik be, le kell kérnie a hatókört openid . A openid hatókör a munkahelyi fiók hozzájárulási lapján a Bejelentkezés engedélyként jelenik meg.

Ezzel az engedéllyel az alkalmazás egyedi azonosítót kaphat a felhasználóhoz a sub jogcím formájában. Az engedély hozzáférést biztosít az alkalmazásnak a UserInfo végponthoz is. A openid hatókör a Microsoft identitásplatform jogkivonat-végpontján használható az azonosító jogkivonatok beszerzéséhez. Az alkalmazás ezeket a jogkivonatokat használhatja a hitelesítéshez.

e-mail

A email hatókör használható a openid hatókörrel és minden más hatókörrel. Ez hozzáférést biztosít az alkalmazásnak a felhasználó elsődleges e-mail-címéhez a email jogcím formájában.

A email jogcím csak akkor szerepel a jogkivonatban, ha a felhasználói fiókhoz e-mail-cím van társítva, ami nem mindig így van. Ha az alkalmazás a hatókört email használja, az alkalmazásnak képesnek kell lennie kezelni egy olyan esetet, amelyben nincs email jogcím a jogkivonatban.

profil

A profile hatókör használható a openid hatókörrel és bármely más hatókörrel. Ez hozzáférést biztosít az alkalmazásnak a felhasználóval kapcsolatos nagy mennyiségű információhoz. Az általa elérhető információk közé tartozik a felhasználó utóneve, vezetékneve, előnyben részesített felhasználóneve és objektumazonosítója, de nem kizárólagosan.

Az adott felhasználóhoz tartozó paraméterben id_tokens elérhető jogcímek teljes listáját profile a id_tokens hivatkozásban találja.

offline_access

Ez a offline_access hatókör hosszabb ideig biztosít hozzáférést az alkalmazásnak a felhasználó nevében található erőforrásokhoz. A hozzájárulási lapon ez a hatókör a Hozzáférés fenntartása azokhoz az adatokhoz, amelyekhez hozzáférést adott az engedélyhez .

Amikor egy felhasználó jóváhagyja a offline_access hatókört, az alkalmazás frissítési jogkivonatokat fogadhat a Microsoft identitásplatformjának jogkivonatvégpontjától. A frissítési jogkivonatok hosszú élettartamúak. Az alkalmazás új hozzáférési jogkivonatokat kaphat, amint a régebbiek lejárnak.

Megjegyzés

Ez az engedély jelenleg az összes jóváhagyási oldalon megjelenik, még az olyan folyamatok esetében is, amelyek nem biztosítanak frissítési jogkivonatot (például az implicit folyamatot). Ez a beállítás olyan forgatókönyveket kezel, ahol az ügyfél az implicit folyamaton belül kezdhet, majd a kódfolyamatba léphet, ahol frissítési jogkivonat várható.

A Microsoft identitásplatformján (a 2.0-s verziójú végpontra irányuló kérések) az alkalmazásnak explicit módon le kell kérnie a offline_access hatókört a frissítési jogkivonatok fogadásához. Így amikor bevált egy engedélyezési kódot az OAuth 2.0 engedélyezési kódfolyamatában, csak egy hozzáférési jogkivonatot kap a /token végponttól.

A hozzáférési jogkivonat rövid ideig érvényes. Általában egy óra múlva lejár. Ekkor az alkalmazásnak vissza kell irányítania a felhasználót a /authorize végpontra, hogy új engedélyezési kódot kapjon. Az átirányítás során az alkalmazás típusától függően előfordulhat, hogy a felhasználónak újra meg kell adnia a hitelesítő adatait, vagy újra hozzá kell adnia az engedélyeket.

A frissítési jogkivonatok beszerzéséről és használatáról a Microsoft identitásplatform protokollreferenciájában talál további információt.

A Microsoft identitásplatform alkalmazásai hozzájárulásra támaszkodnak a szükséges erőforrásokhoz vagy API-khoz való hozzáféréshez. Különböző típusú jóváhagyások léteznek, amelyeket az alkalmazásnak esetleg ismernie kell a sikeres működés érdekében. Az engedélyek meghatározásakor azt is tudnia kell, hogyan fognak hozzáférni a felhasználók az alkalmazáshoz vagy az API-hoz.

A statikus felhasználói hozzájárulási forgatókönyvben meg kell adnia az összes szükséges engedélyt az alkalmazás konfigurációjában az Azure Portalon. Ha a felhasználó (vagy adott esetben a rendszergazda) nem adott hozzájárulást ehhez az alkalmazáshoz, akkor a Microsoft identitásplatformja kérni fogja a felhasználót, hogy adja meg a hozzájárulást.

A statikus engedélyek lehetővé teszik a rendszergazdák számára a jóváhagyást a szervezet összes felhasználója nevében .

Bár az Azure Portalon definiált alkalmazás statikus engedélyei szépek és egyszerűek maradnak, néhány lehetséges problémát jelez a fejlesztők számára:

  • Az alkalmazásnak minden szükséges engedélyt le kell kérnie a felhasználó első bejelentkezésekor. Ez az engedélyek hosszú listáját eredményezheti, amely megakadályozza, hogy a végfelhasználók jóváhagyják az alkalmazás hozzáférését a kezdeti bejelentkezéskor.

  • Az alkalmazásnak ismernie kell azokat az erőforrásokat, amelyekhez előre hozzáférne. Nehéz olyan alkalmazásokat létrehozni, amelyek tetszőleges számú erőforráshoz férhetnek hozzá.

A Microsoft identitásplatform végpontjával figyelmen kívül hagyhatja az Azure Portal alkalmazásregisztrációs információiban meghatározott statikus engedélyeket, és fokozatosan kérhet engedélyeket. Kérhet egy minimális engedélykészletet előre, és idővel többet kérhet, mivel az ügyfél további alkalmazásfunkciókkal rendelkezik. Ehhez bármikor megadhatja az alkalmazás által igényelt hatóköröket úgy, hogy a hozzáférési jogkivonatok igénylésekor az új hatóköröket bele kell venni a scope paraméterbe anélkül, hogy előre meg kellene határozni őket az alkalmazásregisztrációs adatokban. Ha a felhasználó még nem járult hozzá a kérelemhez hozzáadott új hatókörökhöz, a rendszer csak az új engedélyek jóváhagyását kéri. A növekményes vagy dinamikus hozzájárulás csak a delegált engedélyekre vonatkozik, az alkalmazásengedélyekre nem.

Ha lehetővé teszi egy alkalmazás számára, hogy dinamikusan kérjen engedélyeket a scope paraméteren keresztül, teljes körű ellenőrzést biztosít a fejlesztők számára a felhasználói élmény felett. Emellett betöltheti a hozzájárulási felületet, és egyetlen kezdeti engedélyezési kérelemben kérheti az összes engedélyt. Ha az alkalmazásnak nagy számú engedélyre van szüksége, akkor ezeket az engedélyeket növekményesen gyűjtheti össze a felhasználótól, miközben idővel megpróbálják használni az alkalmazás bizonyos funkcióit.

Fontos

A dinamikus hozzájárulás kényelmes lehet, de nagy kihívást jelent a rendszergazdai hozzájárulást igénylő engedélyek esetében. A portál Alkalmazásregisztrációk és Vállalati alkalmazások paneljén található rendszergazdai hozzájárulási felület nem tud ezekről a dinamikus engedélyekről a hozzájárulás időpontjában. Azt javasoljuk, hogy a fejlesztők listázják az alkalmazáshoz szükséges rendszergazdai jogosultsági engedélyeket a portálon. Ez lehetővé teszi, hogy a bérlői rendszergazdák egyszer, a portálon lévő összes felhasználójuk nevében hozzájárulást adjanak. A felhasználóknak nem kell végighaladnia a hozzájárulási felületen a bejelentkezéskor megadott engedélyekhez. A másik lehetőség, hogy dinamikus hozzájárulást használ ezekhez az engedélyekhez. A rendszergazdai hozzájárulás megadásához egy rendszergazda bejelentkezik az alkalmazásba, elindítja a megfelelő engedélyek megadására vonatkozó hozzájárulási kérést, és a hozzájárulási párbeszédben a teljes szervezet számára kiválasztja a hozzájárulást .

Rendszergazdai hozzájárulásra van szükség, ha az alkalmazásnak hozzáférésre van szüksége bizonyos magas jogosultsági szintű engedélyekhez. A rendszergazdai jóváhagyás biztosítja, hogy a rendszergazdák további vezérlőkkel rendelkezzenek, mielőtt engedélyeznék, hogy az alkalmazások vagy felhasználók magas jogosultságú adatokat érjenek el a cégben.

A szervezet nevében végzett rendszergazdai hozzájárulás erősen ajánlott, ha az alkalmazás nagyvállalati célközönségű. A szervezet nevében végzett rendszergazdai hozzájárulás megköveteli, hogy a statikus engedélyek regisztrálva legyenek az alkalmazáshoz a portálon. Ezeket az engedélyeket az alkalmazásregisztrációs portálon állíthatja be, ha rendszergazdai hozzájárulásra van szüksége a teljes szervezet nevében. A rendszergazda egy alkalommal a szervezet összes felhasználója nevében jóváhagyhatja ezeket az engedélyeket. Az alkalmazásba való bejelentkezéskor a felhasználóknak nem kell végighaladnia ezen engedélyek hozzájárulási felületén. Ez a felhasználók számára egyszerűbb, és csökkenti a szervezeti rendszergazda által az alkalmazás beállításához szükséges ciklusokat.

OpenID Connect- vagy OAuth 2.0-engedélyezési kérelmekben az alkalmazások a lekérdezési paraméterrel kérhetik le a scope szükséges engedélyeket. Ha például egy felhasználó bejelentkezik egy alkalmazásba, az alkalmazás az alábbi példához hasonló kérést küld. (Az olvashatóság érdekében sortörések lesznek hozzáadva.)

GET https://login.microsoftonline.com/common/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%2Fcalendars.read%20
https%3A%2F%2Fgraph.microsoft.com%2Fmail.send
&state=12345

A scope paraméter az alkalmazás által kért delegált engedélyek szóközzel elválasztott listája. Az egyes engedélyeket az engedély értékének az erőforrás azonosítójára (az alkalmazásazonosító URI-jára) való hozzáfűzésével jelezzük. A kérelem példájában az alkalmazásnak engedéllyel kell beolvasnia a felhasználó naptárát, és felhasználóként e-mailt kell küldenie.

Miután a felhasználó megadta a hitelesítő adatait, a Microsoft identitásplatformja ellenőrzi a felhasználói hozzájárulás egyező rekordját. Ha a felhasználó korábban nem járult hozzá a kért engedélyekhez, és ha a rendszergazda nem járult hozzá ezekhez az engedélyekhez a teljes szervezet nevében, a Microsoft identitásplatformja megkéri a felhasználót, hogy adja meg a kért engedélyeket.

Ekkor a ("Hozzáférés fenntartása azokhoz offline_access az adatokhoz, amelyekhez hozzáférést adott") és User.Read a ("Bejelentkezés és a profil olvasása") engedély automatikusan bekerül az alkalmazás kezdeti hozzájárulásába. Ezekre az engedélyekre általában szükség van a megfelelő alkalmazásfunkciókhoz. Az offline_access engedély hozzáférést biztosít az alkalmazásnak a natív alkalmazások és webalkalmazások szempontjából kritikus fontosságú jogkivonatok frissítéséhez. Az User.Read engedély hozzáférést biztosít a sub jogcímhez. Lehetővé teszi, hogy az ügyfél vagy az alkalmazás megfelelően azonosítsa a felhasználót az idő múlásával, és hozzáférjen a kezdetleges felhasználói adatokhoz.

Example screenshot that shows work account consent.

Amikor a felhasználó jóváhagyja az engedélykérelmet, a rendszer rögzíti a hozzájárulást. A felhasználónak nem kell újra jóváhagynia, amikor később bejelentkezik az alkalmazásba.

Amikor egy szervezet licencet vagy előfizetést vásárol egy alkalmazáshoz, a szervezet gyakran proaktív módon szeretné beállítani az alkalmazást a szervezet összes tagja általi használatra. Ennek a folyamatnak a részeként a rendszergazda engedélyezheti, hogy az alkalmazás a bérlő bármely felhasználója nevében járjon el. Ha a rendszergazda a teljes bérlőnek ad hozzájárulást, a szervezet felhasználói nem látják az alkalmazás hozzájárulási lapját.

A szervezet nevében végzett rendszergazdai hozzájáruláshoz az alkalmazáshoz regisztrált statikus engedélyek szükségesek. Ezeket az engedélyeket az alkalmazásregisztrációs portálon állíthatja be, ha rendszergazdai hozzájárulásra van szüksége a teljes szervezet nevében.

Ha egy bérlő összes felhasználója számára szeretne hozzájárulást kérni a delegált engedélyekhez, az alkalmazás használhatja a rendszergazdai hozzájárulás végpontját.

Emellett az alkalmazásoknak a rendszergazdai hozzájárulási végpontot kell használniuk az alkalmazásengedélyek lekéréséhez.

Rendszergazda által korlátozott engedélyek

A Microsoft-erőforrások egyes magas jogosultsági szintű engedélyei rendszergazdai korlátozásra állíthatók be. Íme néhány példa az ilyen típusú engedélyekre:

  • Olvassa el az összes felhasználó teljes profilját a következővel: User.Read.All
  • Adatok írása egy szervezet címtárába a következő használatával: Directory.ReadWrite.All
  • Egy szervezet címtárában lévő összes csoport olvasása a következővel: Groups.Read.All

Megjegyzés

A Microsoft Identity platform engedélyezési, jogkivonat- vagy hozzájárulási végpontjaira irányuló kérésekben, ha az erőforrás-azonosító nincs megadva a hatókörparaméterben, akkor az erőforrás a Microsoft Graph lesz. Például a scope=User.Read egyenértékű a következővel: https://graph.microsoft.com/User.Read.

Bár a fogyasztói felhasználók hozzáférést biztosíthatnak az alkalmazásoknak az ilyen típusú adatokhoz, a szervezeti felhasználók nem adhatnak hozzáférést ugyanahhoz a bizalmas vállalati adatkészlethez. Ha az alkalmazás hozzáférést kér egy szervezeti felhasználótól ezen engedélyek egyikéhez, a felhasználó hibaüzenetet kap, amely szerint nem jogosult az alkalmazás engedélyeinek jóváhagyására.

Ha az alkalmazás hatóköröket igényel a rendszergazda által korlátozott engedélyekhez, a szervezet rendszergazdájának hozzá kell adnia ezeket a hatóköröket a szervezet felhasználóinak nevében. Annak érdekében, hogy ne jelenjenek meg olyan kérések a felhasználóknak, amelyek hozzájárulást kérnek az általuk nem adható engedélyekhez, az alkalmazás használhatja a rendszergazdai hozzájárulás végpontját. A rendszergazdai hozzájárulás végpontját a következő szakasz ismerteti.

Ha az alkalmazás magas jogosultságú delegált engedélyeket kér, és egy rendszergazda a rendszergazdai hozzájárulási végponton keresztül adja meg ezeket az engedélyeket, a bérlő összes felhasználója számára meg lesz adva a hozzájárulás.

Ha az alkalmazás alkalmazásengedélyeket kér, és egy rendszergazda a rendszergazdai hozzájárulási végponton keresztül adja meg ezeket az engedélyeket, az adott felhasználó nevében nem történik meg. Ehelyett az ügyfélalkalmazás közvetlenül kap engedélyeket. Ezeket az engedélyeket csak a démonszolgáltatások és a háttérben futó egyéb neminteraktív alkalmazások használják.

Miután a rendszergazdai hozzájárulási végpontot használta a rendszergazdai hozzájárulás megadásához, befejeződött. A felhasználóknak nem kell további lépéseket tenniük. A rendszergazdai hozzájárulás megadása után a felhasználók egy tipikus hitelesítési folyamaton keresztül kaphatnak hozzáférési jogkivonatot. Az eredményül kapott hozzáférési jogkivonat rendelkezik a hozzájárulással rendelkező engedélyekkel.

Ha egy globális rendszergazda az alkalmazást használja, és az engedélyezési végpontra irányítja, a Microsoft identitásplatform észleli a felhasználó szerepkörét. Megkérdezi, hogy a globális rendszergazda a teljes bérlő nevében szeretne-e hozzájárulni a kért engedélyekhez. Ehelyett használhat dedikált rendszergazdai hozzájárulási végpontot, hogy proaktív módon kérje meg a rendszergazdát, hogy adjon engedélyt a teljes bérlő nevében. Ez a végpont az alkalmazásengedélyek lekéréséhez is szükséges. Az engedélyezési végpont használatával nem kérhetők alkalmazásengedélyek.

Ha követi ezeket a lépéseket, az alkalmazás engedélyeket kérhet egy bérlő összes felhasználójához, beleértve a rendszergazda által korlátozott hatóköröket is. Ez a művelet magas jogosultsági szintű. A műveletet csak akkor használja, ha az a forgatókönyvhöz szükséges.

A lépéseket megvalósító kódminta megtekintéséhez tekintse meg a Rendszergazda által korlátozott hatókörök mintáját a GitHubon.

Engedélyek kérése az alkalmazásregisztrációs portálon

Az alkalmazásregisztrációs portálon az alkalmazások listázhatják a szükséges engedélyeket, beleértve a delegált engedélyeket és az alkalmazásengedélyeket is. Ez a beállítás lehetővé teszi a hatókör és az .default Azure Portal Rendszergazdai hozzájárulás megadása lehetőségének használatát.

Általánosságban elmondható, hogy az engedélyeket statikusan kell meghatározni egy adott alkalmazáshoz. Ezek az alkalmazás által dinamikusan vagy növekményesen igényelni kívánt engedélyek szuperhalmazának kell lenniük.

Megjegyzés

Az alkalmazásengedélyek csak a következő használatával .defaultkérhetők: . Ha tehát az alkalmazásnak alkalmazásengedélyre van szüksége, győződjön meg arról, hogy szerepelnek az alkalmazásregisztrációs portálon.

Az alkalmazás statikusan kért engedélyeinek listájának konfigurálása:

  1. Nyissa meg az alkalmazást az Azure Portalon – Az alkalmazásregisztrációk rövid útmutatója.
  2. Válasszon ki egy alkalmazást, vagy hozzon létre egy alkalmazást , ha még nem tette meg.
  3. Az alkalmazás Áttekintés lapján, a Kezelés területen válassza az API-engedélyek>engedély hozzáadása lehetőséget.
  4. Válassza a Microsoft Graphot az elérhető API-k listájából. Ezután adja hozzá az alkalmazáshoz szükséges engedélyeket.
  5. Válassza az Engedélyek hozzáadása lehetőséget.

Általában a rendszergazdai hozzájárulási végpontot használó alkalmazás létrehozásakor az alkalmazásnak olyan lapra vagy nézetre van szüksége, amelyen a rendszergazda jóváhagyhatja az alkalmazás engedélyeit. Ez a lap a következő lehet:

  • Az alkalmazás regisztrációs folyamatának része.
  • Az alkalmazás beállításainak egy része.
  • Dedikált "kapcsolódási" folyamat.

Sok esetben célszerű, ha az alkalmazás csak akkor jeleníti meg ezt a "kapcsolódási" nézetet, ha egy felhasználó munkahelyi Microsoft-fiókkal vagy iskolai Microsoft-fiókkal jelentkezett be.

Amikor bejelentkezteti a felhasználót az alkalmazásba, azonosíthatja azt a szervezetet, amelyhez a rendszergazda tartozik, mielőtt megkérné, hogy hagyja jóvá a szükséges engedélyeket. Bár ez a lépés nem feltétlenül szükséges, ez segíthet intuitívabb felhasználói élmény kialakításában a szervezeti felhasználók számára.

A felhasználó bejelentkezéséhez kövesse a Microsoft identity platform protokolljának oktatóanyagait.

Engedélyek kérése címtáradminisztrátortól

Ha készen áll arra, hogy engedélyeket kérjen a szervezet rendszergazdájától, átirányíthatja a felhasználót a Microsoft identitásplatform rendszergazdai hozzájárulási végpontjára.

// Line breaks are for legibility only.
GET https://login.microsoftonline.com/{tenant}/v2.0/adminconsent?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&state=12345
&redirect_uri=http://localhost/myapp/permissions
&scope=
https://graph.microsoft.com/calendars.read
https://graph.microsoft.com/mail.send
Paraméter Feltétel Leírás
tenant Kötelező Az a címtár-bérlő, amelytől engedélyt szeretne kérni. Guid vagy rövid név formátumban is megadható. Vagy általánosan hivatkozhat a szervezetekre, ahogy az a példában látható. Ne használjon "gyakori" kifejezést, mert a személyes fiókok csak bérlői környezetben adhatnak rendszergazdai hozzájárulást. A bérlőket kezelő személyes fiókokkal való legjobb kompatibilitás érdekében használja a bérlőazonosítót, ha lehetséges.
client_id Kötelező Az alkalmazás (ügyfél) azonosítója, amelyet az Azure Portal – Alkalmazásregisztrációk felület hozzárendelt az alkalmazáshoz.
redirect_uri Kötelező Az átirányítási URI, ahová a választ el szeretné küldeni az alkalmazás számára. Pontosan meg kell egyeznie az alkalmazásregisztrációs portálon regisztrált átirányítási URI-k egyikével.
state Ajánlott A kérésben szereplő érték, amelyet a rendszer a jogkivonat-válaszban is visszaad. Bármilyen tartalom sztringje lehet. Az állapot használatával kódolhatja a felhasználó állapotával kapcsolatos információkat az alkalmazásban a hitelesítési kérés előtt, például a lapon vagy a megtekintésben.
scope Kötelező Meghatározza az alkalmazás által kért engedélyek készletét. A hatókörök lehetnek statikusak (a használatával .default) vagy dinamikusak. Ez a készlet az OpenID Connect-hatóköröket (openid, , profile). email Ha alkalmazásengedélyre van szüksége, a statikusan konfigurált engedélyek listájának lekéréséhez kell használnia .default .

Ezen a ponton az Azure AD megköveteli, hogy a bérlő rendszergazdája jelentkezzen be a kérés teljesítéséhez. A rendszer felkéri a rendszergazdát, hogy hagyja jóvá a paraméterben scope kért összes engedélyt. Ha statikus (.default) értéket használt, az az 1.0-s verziójú rendszergazdai hozzájárulás végpontjához hasonlóan fog működni, és hozzájárulást kér az alkalmazáshoz szükséges engedélyekben található összes hatókörhöz.

Sikeres válasz

Ha a rendszergazda jóváhagyja az alkalmazás engedélyeit, a sikeres válasz így néz ki:

GET http://localhost/myapp/permissions?tenant=a8990e1f-ff32-408a-9f8e-78d3b9139b95&state=state=12345&admin_consent=True
Paraméter Leírás
tenant Az a címtár-bérlő, amely megadta az alkalmazásnak a kért engedélyeket, GUID formátumban.
state A kérésben szereplő érték, amelyet a rendszer a jogkivonat-válaszban is visszaad. Bármilyen tartalom sztringje lehet. Az állapot a felhasználó állapotával kapcsolatos információk kódolására szolgál az alkalmazásban a hitelesítési kérés előtt, például a lapon vagy a megtekintésben.
admin_consent A beállítás értéke .True

Hibaválasz

Ha a rendszergazda nem hagyja jóvá az alkalmazás engedélyeit, a sikertelen válasz a következőképpen néz ki:

GET http://localhost/myapp/permissions?error=permission_denied&error_description=The+admin+canceled+the+request
Paraméter Leírás
error Hibakódsztring, amely a hibák típusainak besorolására használható. A hibákra való reagálásra is használható.
error_description Egy adott hibaüzenet, amely segíthet a fejlesztőknek a hiba kiváltó okának azonosításában.

Miután sikeres választ kapott a rendszergazdai hozzájárulási végponttól, az alkalmazás megkapta a kért engedélyeket. Ezután jogkivonatot kérhet a kívánt erőforráshoz.

Engedélyek használata

Miután a felhasználó engedélyezte az alkalmazás engedélyeit, az alkalmazás olyan hozzáférési jogkivonatokat szerezhet be, amelyek az alkalmazás adott kapacitásban lévő erőforráshoz való hozzáférésének engedélyét képviselik. A hozzáférési jogkivonatok csak egyetlen erőforráshoz használhatók. A hozzáférési jogkivonaton belül azonban minden olyan engedély kódolva van, amelyet az alkalmazás adott az erőforráshoz. Hozzáférési jogkivonat beszerzéséhez az alkalmazás a következő módon kérhet kérést a Microsoft identitásplatform jogkivonat-végpontjához:

POST common/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/json

{
    "grant_type": "authorization_code",
    "client_id": "6731de76-14a6-49ae-97bc-6eba6914391e",
    "scope": "https://outlook.office.com/Mail.Read https://outlook.office.com/mail.send",
    "code": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...",
    "redirect_uri": "https://localhost/myapp",
    "client_secret": "zc53fwe80980293klaj9823"  // NOTE: Only required for web apps
}

Az eredményül kapott hozzáférési jogkivonatot az erőforrásra irányuló HTTP-kérésekben használhatja. Megbízhatóan jelzi az erőforrásnak, hogy az alkalmazás rendelkezik a megfelelő engedéllyel egy adott feladat végrehajtásához.

Az OAuth 2.0 protokollról és a hozzáférési jogkivonatok beszerzéséről a Microsoft identitásplatform végpontprotokoll-referenciájában talál további információt.

Az .default hatókör

A .default hatókör használatával általánosan hivatkozhat egy erőforrás-szolgáltatásra (API) egy kérésben, anélkül, hogy konkrét engedélyeket határoz meg. Ha hozzájárulásra van szükség, .default a rendszer az alkalmazásregisztrációban (a listában szereplő összes API-hoz) tartozó összes szükséges engedély megadására kéri a hozzájárulást.

A hatókör paraméterértékének létrehozása az erőforrás azonosító URI-jának használatával történik, és .defaultperjellel (/) elválasztva. Ha például az erőforrás azonosítójának URI-ja, https://contoso.coma kérés hatóköre .https://contoso.com/.default Azokban az esetekben, amikor egy második perjelet kell megadnia a jogkivonat helyes lekéréséhez, tekintse meg a záró perjelekről szóló szakaszt.

A használat scope={resource-identifier}/.default funkcionálisan megegyezik resource={resource-identifier} az 1.0-s verziójú végponttal (ahol {resource-identifier} az API azonosító URI-ja, például https://graph.microsoft.com a Microsoft Graph esetében).

A .default hatókör bármely OAuth 2.0-s folyamatban használható, és rendszergazdai hozzájárulást kezdeményezhet. A használat a meghatalmazó folyamat és az ügyfél hitelesítő adatainak folyamatában szükséges.

Az ügyfelek nem kombinálhatják a statikus (.default) hozzájárulást és a dinamikus hozzájárulást egyetlen kérelemben. Ezért scope=https://graph.microsoft.com/.default Mail.Read hibát eredményez, mert egyesíti a hatókörtípusokat.

A .default hatókör funkcionálisan megegyezik a resource-központú v1.0-végpont viselkedésével. Az 1.0-s verziójú végpont hozzájárulási viselkedését is hordozza. Ez azt jelzi, hogy csak akkor aktivál egy hozzájárulási kérést, .default ha az ügyfél és az erőforrás közötti delegált engedélyhez nem adták meg a hozzájárulást a bejelentkezett felhasználó nevében.

Ha a hozzájárulás létezik, a visszaadott jogkivonat az adott erőforráshoz megadott összes hatókört tartalmazza a bejelentkezett felhasználó számára. Ha azonban nem adott engedélyt a kért erőforráshoz (vagy ha a prompt=consent paraméter meg lett adva), megjelenik egy hozzájárulási kérés az ügyfélalkalmazás-regisztrációhoz konfigurált összes szükséges engedélyhez, a listában szereplő összes API-hoz.

Ha például a hatókört https://graph.microsoft.com/.default kéri, az alkalmazás hozzáférési jogkivonatot kér a Microsoft Graph API-hoz. Ha a bejelentkezett felhasználó nevében legalább egy delegált engedélyt kapott a Microsoft Graphhoz, a bejelentkezés folytatódik, és az adott felhasználó számára megadott összes Microsoft Graph-delegált engedély szerepelni fog a hozzáférési jogkivonatban. Ha a kért erőforráshoz (ebben a példában a Microsoft Graphhoz) nem adták meg az engedélyeket, akkor megjelenik egy hozzájárulási kérés az alkalmazáshoz konfigurált összes szükséges engedélyhez, a listában szereplő összes API-hoz.

1. példa: A felhasználó vagy a bérlő rendszergazdája engedélyt adott

Ebben a példában a felhasználó vagy egy bérlői rendszergazda megadta a Mail.Read Microsoft Graph-engedélyeket User.Read az ügyfélnek.

Ha az ügyfél kéri scope=https://graph.microsoft.com/.default, nem jelenik meg hozzájárulási kérés, függetlenül attól, hogy milyen tartalommal rendelkezik az ügyfélalkalmazás regisztrált engedélyei a Microsoft Graphhoz. A visszaadott jogkivonat tartalmazza a hatóköröket Mail.Read és User.Reada .

2. példa: A felhasználó nem adott engedélyeket az ügyfél és az erőforrás között

Ebben a példában a felhasználó nem adott hozzájárulást az ügyfél és a Microsoft Graph között, és nincs rendszergazdája sem. Az ügyfél regisztrált az engedélyekre User.Read és Contacts.Reada . Regisztrálva lett az Azure Key Vault hatókörében https://vault.azure.net/user_impersonationis.

Amikor az ügyfél jogkivonatot scope=https://graph.microsoft.com/.defaultkér, a felhasználó megjelenik a Microsoft Graph User.Read és Contacts.Read a hatókörök hozzájárulási oldala, valamint az Azure Key Vault user_impersonation hatóköre. A visszaadott jogkivonat csak a hatóköröket és Contacts.Read a User.Read hatóköröket tartalmazza, és csak a Microsoft Graphon használható.

3. példa: A felhasználó beleegyezett, és az ügyfél további hatóköröket kér

Ebben a példában a felhasználó már beleegyezett Mail.Read az ügyfélbe. Az ügyfél regisztrált a Contacts.Read hatókörre.

Az ügyfél először a következővel végez bejelentkezést scope=https://graph.microsoft.com/.default: . A válasz paramétere alapján scopes az alkalmazás kódja azt észleli, hogy csak Mail.Read a rendszer adta meg. Az ügyfél ezután kezdeményez egy második bejelentkezést a használatával scope=https://graph.microsoft.com/.default, és ezúttal a hozzájárulást használja prompt=consent. Ha a felhasználó az alkalmazás által regisztrált összes engedélyhez engedélyt kap, megjelenik a hozzájárulási kérés. (Ha nem, hibaüzenet vagy a rendszergazdai hozzájárulási kérelem űrlapja jelenik meg.) Mindkettő Contacts.Read , és Mail.Read megjelenik a hozzájárulási kérésben. Ha a jóváhagyás meg van adva, és a bejelentkezés folytatódik, a visszaadott jogkivonat a Microsoft Graph számára lesz visszaadva, és tartalmazza és Contacts.Read.Mail.Read

Az .default hatókör használata az ügyféllel

Bizonyos esetekben az ügyfél saját .default hatókört kérhet. Az alábbi példa ezt a forgatókönyvet mutatja be.

// Line breaks are for legibility only.

GET https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize
    ?response_type=token            //Code or a hybrid flow is also possible here
    &client_id=9ada6f8a-6d83-41bc-b169-a306c21527a5
    &scope=9ada6f8a-6d83-41bc-b169-a306c21527a5/.default
    &redirect_uri=https%3A%2F%2Flocalhost
    &state=1234

Ez a példakód létrehoz egy hozzájárulási oldalt az összes regisztrált engedélyhez, ha a fenti leírások a hozzájárulásra .default vonatkoznak. Ezután a kód egy id_token, nem pedig hozzáférési jogkivonatot ad vissza.

Ez a viselkedés az Azure AD Authentication Libraryből (ADAL) a Microsoft Authentication Librarybe (MSAL) áthelyezett régi ügyfeleket is magába foglalja. Ezt a beállítást nem használhatják olyan új ügyfelek, amelyek a Microsoft identitásplatformját célják.

Az ügyfél hitelesítő adatai engedélyezik a folyamatot és az .default értéket

Egy másik felhasználási mód az alkalmazásszerepkörök (más néven alkalmazásengedélyek) kérése .default egy nem interaktív alkalmazásban, például egy démonalkalmazásban, amely az ügyfél hitelesítő adatait adja meg a webes API meghívásához.

Ha alkalmazásszerepköröket (alkalmazásengedélyeket) szeretne definiálni egy webes API-hoz, olvassa el az Alkalmazásszerepkörök hozzáadása az alkalmazásban című témakört.

Az ügyfél-szolgáltatásban az ügyfél-hitelesítő adatokra vonatkozó kéréseknek tartalmazniuk kell a következőket scope={resource}/.default: . {resource} Itt található az alkalmazás által meghívni kívánt webes API, amelyhez hozzáférési jogkivonatot szeretne beszerezni. Az egyedi alkalmazásengedélyek (szerepkörök) használatával történő ügyfél-hitelesítőadat-kérések kiadása nem támogatott. A visszaadott hozzáférési jogkivonat tartalmazza az adott webes API-hoz megadott összes alkalmazásszerepkört (alkalmazásengedélyt).

A megadott alkalmazásszerepkörökhöz való hozzáférés biztosításához, beleértve a rendszergazdai hozzájárulás megadását az alkalmazáshoz, tekintse meg az ügyfélalkalmazás webes API-hoz való hozzáférésének konfigurálásával kapcsolatos témakört.

Záró perjel és .default

Egyes erőforrás-URI-k záró perjellel rendelkeznek, https://contoso.com/https://contoso.comnem pedig . A záró perjel problémákat okozhat a jogkivonatok érvényesítésével kapcsolatban. A problémák elsősorban akkor fordulnak elő, ha jogkivonatot kérnek az Azure Resource Managerhez (https://management.azure.com/). Ebben az esetben az erőforrás URI-ján egy záró perjel azt jelenti, hogy a perjelnek jelen kell lennie a jogkivonat lekérésekor. Tehát amikor jogkivonatot https://management.azure.com/ kér és használ .default, kérnie https://management.azure.com//.default kell (figyelje meg a kettős perjelet!). Általában, ha ellenőrzi, hogy a jogkivonat kiállítása folyamatban van-e, és ha az API elutasítja a jogkivonatot, amely elfogadja azt, fontolja meg egy második perjel hozzáadását, majd próbálja újra.

A hibaelhárítási lépésekhez tekintse meg az alkalmazáshoz való hozzájáruláskor fellépő váratlan hibaüzenetet.

Következő lépések