Hatókörök és engedélyek a Microsoft Identitásplatform

  • Cikk

A Microsoft Identitásplatform 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 webalapú erőforrásokhoz egy felhasználó nevében. Minden, a Microsoft Identitásplatform integrálható webes erőforrás rendelkezik erőforrás-azonosítóval vagy alkalmazásazonosító URI-val.

Ebben a cikkben megismerheti az identitásplatform hatóköreit és engedélyeit.

Az alábbi lista néhány példát mutat be 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 minden olyan külső erőforrásra, amely integrálva van a Microsoft Identitásplatform. 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. A Microsoft Graph például többek között az alábbi feladatok elvégzésére vonatkozó engedélyekkel rendelkezik:

  • 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észletes vezérléssel rendelkezik az adatai és az API-funkciók nyilvánosságra kerülése felett. Egy harmadik féltől származó alkalmazás kérheti ezeket az engedélyeket a felhasználóktól és rendszergazdáktól, akiknek jóvá kell hagyniuk a kérést, mielőtt az alkalmazás hozzáférhet az adatokhoz, vagy eljárhatnak egy felhasználó nevében.

Ha egy erőforrás funkciói kis engedélykészletekbe vannak osztva, külső alkalmazások hozhatók létre, 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 tudják, hogy 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 az alkalmazásuk működéséhez szükséges engedélyeket kell kérniük.

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ásplatform egy engedély sztringértékként jelenik meg. Az 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-Csatlakozás hatókört és erőforrás-alapú engedélyeket támogat (az egyes engedélyeket az erőforrás azonosítójának vagy alkalmazásazonosítójának URI-jának hozzáfűzésével jelzik). Az engedélysztring https://graph.microsoft.com/Calendars.Read használatával például engedélyt kérhet a felhasználók naptárainak olvasására a Microsoft Graphban.

Az engedélyezési kiszolgálóhoz érkező kérésekben a Microsoft Identitásplatform esetében, ha az erőforrás-azonosító nem szerepel 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.

Rendszergazda korlátozott engedélyek

A Microsoft Identitásplatform engedélyei rendszergazdai korlátozásra állíthatók be. Például számos magasabb jogosultságú Microsoft Graph-engedély rendszergazdai jóváhagyást igényel. Ha az alkalmazás rendszergazda által korlátozott engedélyeket igényel, a szervezet rendszergazdájának hozzá kell adnia ezeket a hatóköröket a szervezet felhasználói nevében. Az alábbi szakasz példákat mutat be az ilyen típusú engedélyekre:

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

Feljegyzés

A Microsoft Identitásplatform engedélyezési, jogkivonati vagy jóváhagyási végpontjaira irányuló kérelmekben, ha az erőforrás-azonosító nem szerepel 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 adhatnak 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 alkalmazásengedélyeket kér, és egy rendszergazda megadja ezeket az engedélyeket, ez a támogatás nem történik meg egyetlen adott felhasználó nevében sem. Ehelyett az ügyfélalkalmazás közvetlenül kap engedélyeket. Ezeket az engedélyeket csak a démoni szolgáltatások és a háttérben futó egyéb nem interaktív alkalmazások használhatják. A közvetlen hozzáférési forgatókönyvről további információt a Microsoft Identitásplatform Access-forgatókönyveiben talál.

A hatókörök webes API-ban való közzétételével kapcsolatos lépésenkénti útmutatóért lásd : Alkalmazás konfigurálása webes API-k megjelenítésére.

OpenID Csatlakozás hatókörök

Az OpenID Csatlakozás 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. Az address OpenID Csatlakozás phone hatókörök nem támogatottak.

Ha openID-Csatlakozás hatóköröket és jogkivonatot kér, jogkivonatot kap a UserInfo végpont meghívásához.

A openid hatókör

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

Ezzel az engedéllyel az alkalmazás egyedi azonosítót kaphat a felhasználó számára 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 tokenvégponton használható az azonosító jogkivonatok beszerzéséhez. Az alkalmazás ezeket a jogkivonatokat használhatja hitelesítésre.

A email hatókör

A email 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ó elsődleges e-mail-címéhez a email jogcím formájában.

A email jogcím csak akkor szerepel a jogkivonatban, ha egy e-mail-cím van társítva a felhasználói fiókkal, ami nem mindig igaz. 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.

A profile hatókör

A profile hatókör használható a openid hatókörrel és bármely más hatókörrel. Ez nagy mennyiségű információhoz biztosít hozzáférést az alkalmazásnak a felhasználóról. 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.

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

A offline_access hatókör

A offline_access hatókör hosszabb ideig biztosít hozzáférést az alkalmazásnak az erőforrásokhoz a felhasználó nevében. A hozzájárulási lapon ez a hatókör jelenik meg az engedélyhez hozzáférést kapott adatokhoz való hozzáférés fenntartásaként.

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

Feljegyzés

Ez az engedély jelenleg az összes jóváhagyási oldalon megjelenik, még 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ásplatform (a v2.0-s végpontra irányuló kérések) esetén 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 általában körülbelül egy óráig érvényes. Ezen a ponton az alkalmazásnak vissza kell irányítania a felhasználót a /authorize végpontra, hogy új engedélyezési kódot kérjen. Az átirányítás során és 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 engedélyeznie kell az engedélyeket.

A frissítési jogkivonat lejárata hosszabb, mint a hozzáférési jogkivonaté, és általában egy napig érvényes. A frissítési jogkivonatok beszerzéséről és használatáról további információt a Microsoft Identitásplatform protokollreferenciában talál.

A .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, konkrét engedélyek azonosítása nélkül. Ha szükséges a hozzájárulás, a jelek használatával .default a hozzájárulást kell kérni az alkalmazásregisztrációban felsorolt összes szükséges engedélyhez (a listában szereplő összes API-hoz).

A hatókör paraméterértékének létrehozása az erőforrás azonosító URI-jával történik, és .defaultperjellel (perjellel elválasztva/). Ha például az erőforrás azonosítójának URI-ja, https://contoso.comakkor a kérés hatóköre.https://contoso.com/.default Azokban az esetekben, amikor egy második perjelet kell tartalmaznia 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 (hol {resource-identifier} található 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 nevében történő 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 a hatókörtípusok egyesülnek.

A .default hatókörparaméter csak akkor aktivál hozzájárulási kérést, ha az ügyfél és az erőforrás között nem kapott hozzájárulást a bejelentkezett felhasználó nevében.

Ha a hozzájárulás létezik, a visszaadott jogkivonat tartalmazza az adott erőforráshoz megadott összes hatókört 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érik, 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óhoz 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 adtak engedélyeket, akkor megjelenik egy hozzájárulási kérés az alkalmazásban 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élyekkel rendelkezik

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

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 az ügyfélalkalmazás regisztrált engedélyeit tartalmazza-e a Microsoft Graph. 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álta az engedélyeket 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, valamint az Azure Key Vault user_impersonation hatókörének hozzájárulási oldala. 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 hozzájárult Mail.Read az ügyfélhez. Az ügyfél regisztrált a Contacts.Read hatókörre.

Az ügyfél először a következővel scope=https://graph.microsoft.com/.defaultvégez bejelentkezést: . A válasz paramétere alapján scopes az alkalmazás kódja azt észleli, hogy csak Mail.Read a megadott. 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 kényszeríti a használatával prompt=consent. Ha a felhasználó engedélyt kap az alkalmazás által regisztrált összes engedély jóváhagyására, megjelenik a hozzájárulási kérés. (Ha nem, hibaüzenet jelenik meg, vagy a rendszergazdai hozzájárulási kérelem űrlapja.) Mindkettőt Contacts.Read , és Mail.Read megjelenik a hozzájárulási kérésben. Ha a hozzájárulás meg van adva, és a bejelentkezés folytatódik, a visszaadott jogkivonat a Microsoft Graph számára készült, és tartalmazza Mail.Read és Contacts.Read.

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

Bizonyos esetekben az ügyfél saját hatókört .default 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=00001111-aaaa-2222-bbbb-3333cccc4444
    &scope=9ada6f8a-6d83-41bc-b169-a306c21527a5/.default
    &redirect_uri=https%3A%2F%2Flocalhost
    &state=1234

Ez a példakód egy hozzájárulási oldalt hoz létre az összes regisztrált engedélyhez, ha a hozzájárulás .default előző leírásai érvényesek a forgatókönyvre. Ezután a kód egy id_token, és nem hozzáférési jogkivonatot ad vissza.

Ezt a beállítást nem használhatják a Microsoft Identitásplatform megcélzott új ügyfelek. Ügyeljen arra, hogy az Azure AD Authentication Libraryből (ADAL) migráljon a Microsoft Authentication Library (MSAL) szolgáltatásba.

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

A másik lehetőség 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ő adataival engedélyezi a folyamatot egy 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 ügyfél hitelesítő adataira vonatkozó kérések egyéni alkalmazásengedélyek (szerepkörök) használatával történő kiadása nem támogatott. A webes API-hoz megadott összes alkalmazásszerepkör (alkalmazásengedély) szerepel a visszaadott hozzáférési jogkivonatban.

Ha hozzáférést szeretne adni a megadott alkalmazásszerepkörökhöz, 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/ például nem https://contoso.com. 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 záró perjele azt jelenti, hogy a perjelnek jelen kell lennie a jogkivonat ké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ánosságban elmondható, hogy ha ellenőrzi, hogy a jogkivonat kiadása folyamatban van-e, és ha a jogkivonatot az API elutasítja, amelyet el kell fogadnia, fontolja meg egy második perjel hozzáadását, és próbálja újra.

Lásd még