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

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

The Microsoft identity platform implements the OAuth 2.0 authorization protocol. 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. A Microsoft identitásplatformjával integrálható webes erőforrások erőforrás-azonosítóval vagy alkalmazásazonosító URI-val rendelkeznek.

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 levelezési API: https://outlook.office.com
  • Azure Key Vault: https://vault.azure.net

Ugyanez vonatkozik a Microsoft identitásplatformjával integrálható külső erőforrásokra is. Ezen erőforrások bármelyike meghatározhat olyan engedélyeket is, amelyek az erőforrás funkcióit kisebb adattömbökre osztják. As an example, Microsoft Graph defines permissions to do the following tasks, among others:

  • Felhasználó naptárának olvasása
  • Írj a felhasználó naptárába
  • 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.

In OAuth 2.0, these types of permission sets are called scopes. They're also often referred to as permissions. A Microsoft Identitásplatformon egy engedély egy sztringértékként van ábrázolva. 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 Connect-hatókört és erőforrás-alapú engedélyt 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.

Admin-restricted permissions

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

Note

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. Instead, the client application is granted permissions directly. 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ásplatformjának 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 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, amelyeket a Microsoft Graph is üzemeltet: openid, email, profileés offline_access. A(z) address és phone OpenID Connect-hatókörök nem támogatottak. Ezek a hatókörök néha opcionálisak, és figyelembe veszik az ID tokenek gazdagítására. Ezek a hatókörök nem mindig jelennek meg külön sorokban a felhasználónak adott hozzájárulási kérésben.

If you request the OpenID Connect scopes and a token, you get a token to call the UserInfo endpoint.

A openid hatókör

If an app signs in by using OpenID Connect, it must request the openid scope. A openid hatókör a munkahelyi fiók hozzájárulási lapján jelenik meg a Bejelentkezési engedélyként.

Az alkalmazások ezzel az engedéllyel kapják meg a felhasználó egyedi azonosítóját 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 email hatókört használja, képesnek kell lennie kezelni az alkalmazásnak egy olyan esetet, amelyben nincs email állítás 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.

A profile találja az adott felhasználó számára a id_tokens paraméterben elérhető jogcímek teljes listáját id_tokens.

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 .

Ha bármilyen delegált engedélyt kap meg, az offline hozzáférés implicit módon megadott. Feltételezheti, hogy az alkalmazás rendelkezik offline_access, ha vannak delegált engedélyek. 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.

Note

This permission currently appears on all consent pages, even for flows that don't provide a refresh token (such as the implicit flow). 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) megköveteli, hogy az alkalmazás explicit módon kérje le a offline_access hatókört, hogy frissítési jogkivonatokat kapjon. Így amikor felhasznál egy engedélyezési kódot az OAuth 2.0 engedélyezési kódfolyamatában, egy hozzáférési tokent kap a /token végponttól.

A hozzáférési jogkivonat 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 90 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 frissítési jogkivonat válaszba való felvétele több tényezőtől is függhet, beleértve az alkalmazás adott konfigurációját és az engedélyezési folyamat során kért hatóköröket. Ha a válaszban frissítési jogkivonatot vár, de nem sikerül, vegye figyelembe a következő tényezőket:

  • Scope requirements: Ensure that you're requesting the offline_access scopes along with any other necessary scopes.
  • Engedélyezési engedély típusa: A frissítési jogkivonat az engedélyezési kód megadásának típusa esetén van megadva. Ha az áramlat eltér, a válaszra hatással lehet.
  • Client configuration: Check your application's settings in the identity platform. Bizonyos konfigurációk korlátozhatják a refresh_tokens kiállítását.

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 beleegyezés, a .default használatával jelezzük, hogy minden szükséges engedélyhez beleegyezést kell kérni, amely az alkalmazásregisztrációban fel van sorolva (a listában szereplő összes API esetében).

A hatókör paraméterértékét az erőforrás azonosító URI-jával hozzák létre, és azt egy perjel (.default) választja el (/). 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 be kell illeszteni egy második perjelet a token helyes lekéréséhez, tekintse meg a záró perjelekről szóló szakaszt.

Az scope={resource-identifier}/.default használata funkcionálisan ugyanaz, mint resource={resource-identifier} az 1.0-s végponton (ahol {resource-identifier} az API azonosító URI-ja található, például https://graph.microsoft.com a Microsoft Graph esetében).

The .default scope can be used in any OAuth 2.0 flow and to initiate admin consent. Its use is required in the On-Behalf-Of flow and client credentials flow.

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 egy hozzájárulási kérést, ha a bejelentkezett felhasználó nevében nem történt más delegált engedélyhez hozzájárulás az ügyfél és az erőforrás között.

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 van 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. 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, nem jelenik meg hozzájárulási kérés scope=https://graph.microsoft.com/.default, függetlenül attól, hogy az ügyfélalkalmazás regisztrált engedélyei tartalmazzák-e a Microsoft Graphot. A visszaadott jogkivonat tartalmazza a hatóköröket Mail.Read és User.Read.

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álva van a User.Read és Contacts.Read engedélyekre, és regisztrálva van az Azure Key Vault hatókörére https://vault.azure.net/user_impersonation.

Amikor az ügyfél scope=https://graph.microsoft.com/.default jogkivonatot kér, a felhasználónak megjelenik egy hozzájárulási oldal a Microsoft Graph User.Read és Contacts.Read hatókörök, valamint az Azure Key Vault user_impersonation hatókörök számára. A visszaadott jogkivonat csak a User.Read és Contacts.Read hatóköröket tartalmazza, és csak a Microsoft Graph szolgáltatással 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 ahhoz, hogy a kliens megkapja a Mail.Read szolgáltatást. 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 scopes paramétere alapján az alkalmazás kódja észleli, hogy csak Mail.Read engedélyezett. 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 vagy a rendszergazdai hozzájárulási kérelem űrlapja jelenik meg.) Mind Contacts.Read mind Mail.Read szerepel a hozzájárulási promptban. Ha a hozzájárulás megadott, és a bejelentkezés folytatódik, a visszaadott jogkivonat a Microsoft Graph-hez tartozik, és az alábbiakat 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 ad vissza, ahelyett hogy egy hozzáférési jogkivonatot.

A Microsoft identitásplatformját megcélzó új ügyfelek nem használhatják ezt a beállítást. Győződjön meg arról, hogy az Azure AD Authentication Libraryből (ADAL) áttér a Microsoft Authentication Libraryre (MSAL).

Ügyfél-hitelesítő adatok engedélyezési folyamata és .default

Another use of .default is to request app roles (also known as application permissions) in a non-interactive application like a daemon app that uses the client credentials grant flow to call a web API.

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.

Client credentials requests in your client service must include 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. Issuing a client credentials request by using individual application permissions (roles) is not supported. 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 tokent kérnek az Azure Resource Managerhez (https://management.azure.com/).

Ebben az esetben az erőforrás-URI végén lévő perjel azt jelenti, hogy a perjelnek ott kell lennie, amikor a jogkivonat kérése történik. Tehát amikor jogkivonatot kér https://management.azure.com/ és használ .default, akkor https://management.azure.com//.default-t kell kérnie (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.

See also

  • Last updated on