Megosztás a következőn keresztül:

Fejlesztői útmutató engedélyek és hozzájárulás kéréséhez a Microsoft Identity Platformon

Az alkalmazások a Microsoft identitásplatformján a hozzájárulást igénylik, hogy hozzáférjenek a szükséges erőforrásokhoz vagy API-khoz. A különböző típusú hozzájárulások jobbak a különböző alkalmazási helyzetekben. Az alkalmazás hozzájárulásának legjobb módszerének kiválasztása lehetővé teszi, hogy sikeresebb legyen a felhasználók és a szervezetek számára.

Ebben a cikkben megismerheti a hozzájárulás különböző típusait, és azt, hogyan kérhet engedélyt az alkalmazáshoz hozzájáruláson keresztül.

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 a Microsoft Entra felügyeleti központban. Ha a felhasználó (vagy adott esetben a rendszergazda) nem ad hozzájárulást ehhez az alkalmazáshoz, akkor a Microsoft identitásplatformja kéri 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 hozzájárulást a szervezet összes felhasználója nevében.

A statikus hozzájárulásra és egyetlen engedélylistára támaszkodva a kód szép és egyszerű marad, azt is jelenti, hogy az alkalmazás minden olyan engedélyt kér, amelyre valaha szükség lehet. Ez a beállítás elriaszthatja a felhasználókat és a rendszergazdákat az alkalmazás hozzáférési kérésének jóváhagyásától.

A Microsoft identitásplatform végpontjával figyelmen kívül hagyhatja a Microsoft Entra felügyeleti központban az alkalmazásregisztrációs információkban meghatározott statikus engedélyeket. Ehelyett növekményesen kérhet engedélyeket. A minimális engedélyeket előre is kérheti, és idővel többet kérhet, mivel az ügyfél több alkalmazásfunkciót használ. Ehhez bármikor megadhatja az alkalmazás által igényelt hatóköröket úgy, hogy a scope az új hatóköröket belefogalmazva a paraméterbe – anélkül, hogy előre meg kellene adni őket az alkalmazásregisztrációs adatokban.

Ha a felhasználó nem járul hozzá a kérelemhez hozzáadott új hatókörökhöz, a rendszer kérni fogja, hogy csak az új engedélyekhez járuljon hozzá. 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 mértékben szabályozhatja a fejlesztők felhasználói élményét. Először betölti a hozzájárulási felületet, és egyetlen kezdeti engedélyezési kérelemben kéri az összes engedélyt. Ha az alkalmazás nagy számú engedélyt igényel, 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 jelentős 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 paneljeinek rendszergazdai hozzájárulási felülete nem tud ezekről a dinamikus engedélyekről a hozzájárulás időpontjában. Javasoljuk, hogy egy fejlesztő felsorolja az összes rendszergazdai jogosultsággal rendelkező engedélyt, amelyekre az alkalmazásnak szüksége van a portálon.

Ez lehetővé teszi a bérlői rendszergazdák számára, hogy a portál összes felhasználója nevében egyeztessel járuljanak hozzá. A felhasználóknak nem kell átmennie a bejelentkezéshez szükséges engedélyekkel kapcsolatos hozzájárulási felületen. 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 egyéni rendszergazda bejelentkezik az alkalmazásba, elindít egy hozzájárulási kérést a megfelelő engedélyekhez, és a hozzájárulási párbeszédben kiválasztja a teljes szervezetem hozzájárulását .

OpenID Connect vagy OAuth 2.0 engedélyezési kérelem esetén az alkalmazás a lekérdezési paraméterrel kérheti 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 vannak hozzáadva).

GET https://login.microsoftonline.com/common/oauth2/v2.0/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&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 erőforrás azonosítójának (az alkalmazásazonosító URI-jának) hozzáfűzésével jelzi a program. A kérési példában az alkalmazásnak engedéllyel kell olvasnia a felhasználó naptárát, és felhasználóként e-mailt kell küldenie.

A bejelentkezés után a Microsoft identitásplatformja ellenőrzi a meglévő felhasználói hozzájárulást. Ha a felhasználó nem hagyja jóvá a kért engedélyeket, és a rendszergazda sem hagyja jóvá őket, a platform kéri a felhasználót a hozzájárulás megadására.

A következő példában a ("Hozzáférés fenntartása azokhoz offline_access az adatokhoz, amelyekhez hozzáférést ad") engedély és User.Read a ("Bejelentkezés és a profil elolvasása") engedély automatikusan bekerül az alkalmazás kezdeti hozzájárulásába. Ezek az engedélyek szükségesek 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 az ügyfél vagy alkalmazás számára, hogy időben helyesen azonosítsa a felhasználót, és hozzáférjen az alapvetõ felhasználói adatokhoz.

Példa képernyőkép a munkahelyi fiók beleegyezését ábrázoló képernyőképről.

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 beleegyeznie, amikor később bejelentkezik az alkalmazásba.

A teljes bérlő hozzájárulásának kéréséhez rendszergazdai hozzájárulásra van szükség. A szervezet nevében végzett rendszergazdai hozzájáruláshoz az alkalmazáshoz regisztrált statikus engedélyek szükségesek. Állítsa be ezeket az engedélyeket az alkalmazásregisztrációs portálon, ha rendszergazdai hozzájárulásra van szüksége a teljes szervezet nevében.

Amikor az alkalmazás rendszergazdai hozzájárulást igénylő delegált engedélyeket kér, a felhasználók "engedély nélküli hozzájárulás" hibaüzenetet kapnak, és hozzáférést kell kérnie a rendszergazdától. Ha egy rendszergazda a teljes bérlőhöz hozzájárulást ad, a rendszer csak akkor kéri újra a felhasználókat, ha visszavonják a hozzájárulást, vagy új engedélyeket adnak hozzá.

Az ugyanazt az alkalmazást használó rendszergazdák a rendszergazdai hozzájárulási kérést látják. A rendszergazdai hozzájárulási kérés egy jelölőnégyzetet biztosít, amely lehetővé teszi számukra, hogy hozzáférést adjanak az alkalmazásnak a kért adatokhoz a teljes bérlő felhasználói nevében. A felhasználói és rendszergazdai hozzájárulási felülettel kapcsolatos további információkért tekintse meg az alkalmazás hozzájárulási felületét.

A Microsoft Graph rendszergazdai hozzájárulást igénylő delegált engedélyeinek példái a következők:

  • Az összes felhasználó teljes profiljának olvasása a User.Read.All használatával
  • Adatok írása egy szervezet könyvtárába a Directory.ReadWrite.All használatával
  • Egy szervezet címtárában lévő összes csoport beolvasása a Groups.Read.All használatával

A Microsoft Graph-engedélyek teljes listájának megtekintéséhez tekintse meg a Microsoft Graph engedélyeinek hivatkozását.

Saját erőforrásaira vonatkozó engedélyeket is konfigurálhat, hogy rendszergazdai hozzájárulást igényeljen. További információ a rendszergazdai hozzájárulást igénylő hatókörök hozzáadásáról: Rendszergazdai hozzájárulást igénylő hatókör hozzáadása.

Egyes szervezetek módosíthatják a bérlő alapértelmezett felhasználói hozzájárulási szabályzatát. Amikor az alkalmazás hozzáférést kér az engedélyekhez, ezek a szabályzatok alapján lesznek kiértékelve. Előfordulhat, hogy a felhasználónak akkor is rendszergazdai hozzájárulást kell kérnie, ha alapértelmezés szerint nem szükséges. Ha tudni szeretné, hogy a rendszergazdák hogyan kezelik az alkalmazásokra vonatkozó hozzájárulási szabályzatokat, tekintse meg az alkalmazás-hozzájárulási szabályzatok kezelését ismertető témakört.

Megjegyzés:

A Microsoft identitásplatform-engedélyezési, jogkivonat- vagy hozzájárulási kérelmeiben az alapértelmezett paraméter erőforrás-azonosítójának kihagyása a scope Microsoft Graphra. Például a scope=User.Read úgy van kezelve, mint a https://graph.microsoft.com/User.Read.

Az alkalmazásengedélyek használatához mindig rendszergazdai hozzájárulás szükséges. Az alkalmazásengedélyek nem rendelkeznek felhasználói környezettel, és a hozzájárulás megadása egyetlen felhasználó nevében sem 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 nem interaktív alkalmazások használják. A rendszergazdáknak előre kell konfigurálnia az engedélyeket, és rendszergazdai hozzájárulást kell adniuk a Microsoft Entra felügyeleti központon keresztül.

Ha az engedélyt kérő alkalmazás több-bérlős alkalmazás, az alkalmazásregisztrációja csak abban a bérlőben létezik, ahol létrehozta, ezért az engedélyek nem konfigurálhatók a helyi bérlőben. Ha az alkalmazás rendszergazdai hozzájárulást igénylő engedélyeket kér, a rendszergazdának hozzájárulást kell kérnie a felhasználók nevében. Az engedélyek jóváhagyásához a rendszergazdáknak maguknak kell bejelentkezniük az alkalmazásba, hogy a rendszergazdai hozzájárulás bejelentkezési élménye aktiválódjon. A több-bérlős alkalmazások rendszergazdai hozzájárulási felületének beállításáról további információt a több-bérlős bejelentkezések engedélyezése című témakörben talál.

A rendszergazda az alábbi lehetőségekkel adhat hozzájárulást egy alkalmazáshoz.

Általában rendszergazdai hozzájárulást igénylő 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 csatlakozási folyamat.

Sok esetben célszerű, ha az alkalmazás csak akkor jeleníti meg a "connect" nézetet, ha egy felhasználó munkahelyi Microsoft-fiókkal vagy iskolai Microsoft-fiókkal van bejelentkezve.

Amikor bejelentkezik az alkalmazásba, azonosíthatja azt a szervezetet, amelyhez a rendszergazda tartozik, mielőtt megkérné őket a szükséges engedélyek jóváhagyására. Bár ez a lépés nem feltétlenül szükséges, 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 az alkalmazásregisztrációs portálon

Az alkalmazásregisztrációs portálon az alkalmazások felsorolhatjá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 .default hatókör és a Microsoft Entra felügyeleti központ Rendszergazdai hozzájárulás megadása lehetőségének használatát.

Az engedélyeket általában statikusan kell meghatározni egy adott alkalmazáshoz. Ezeknek az alkalmazás által dinamikusan vagy növekményesen kért 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. Jelentkezzen be a Microsoft Entra felügyeleti központba, legalább felhőalkalmazás-rendszergazdaként.
  2. Navigáljon az Entra ID>alkalmazásregisztrációk>Minden alkalmazás felé.
  3. Jelöljön ki egy alkalmazást, vagy hozzon létre egy alkalmazást , ha még nem tette meg.
  4. 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.
  5. 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.
  6. Válassza az Engedélyek hozzáadása lehetőséget.

Sikeres válasz

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

GET http://localhost/myapp/permissions?tenant=aaaabbbb-0000-cccc-1111-dddd2222eeee&state=state=12345&admin_consent=True
Paraméter Leírás
tenant Az a címtárbérltető, amely megadta az alkalmazásnak a kért engedélyeket, GUID formátumban.
state A jogkivonat válaszában visszaadott kérésben szereplő érték. 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 nézeten.
admin_consent A beállítás értéke .True

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

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ód-karakterlánc, amely a előforduló hibatípusok osztályozá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 a felhasználó hozzájárult az alkalmazás engedélyeinek megadásához, az alkalmazás olyan hozzáférési jogkivonatokat szerezhet be, amelyek az alkalmazás adott kapacitásban lévő erőforrás elérésére vonatkozó 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 kódolás azonban minden engedély, amelyet az alkalmazás adott az adott erőforráshoz. Hozzáférési jogkivonat beszerzéséhez az alkalmazás a következő módon kérheti a Microsoft identitásplatform-jogkivonat végpontját:

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

{
    "grant_type": "authorization_code",
    "client_id": "00001111-aaaa-2222-bbbb-3333cccc4444",
    "scope": "https://microsoft.graph.com/Mail.Read https://microsoft.graph.com/mail.send",
    "code": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...",
    "redirect_uri": "https://localhost/myapp",
    "client_secret": "A1bC2dE3f..."  // NOTE: Only required for web apps
}

Az eredményül kapott hozzáférési jogkivonatot az erőforrás http-kéréseiben használhatja. Megbízhatóan jelzi az erőforrásnak, hogy az alkalmazás rendelkezik a megfelelő engedéllyel egy adott tevékenység 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.

Kapcsolódó tartalom