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

Jogkivonatok megszerzése és gyorsítótárazása a Microsoft Authentication Library (MSAL) használatával

  • Cikk

A hozzáférési jogkivonatok lehetővé teszik az ügyfelek számára az Azure által védett webes API-k biztonságos meghívását. A jogkivonatot több módon is megszerezheti a Microsoft Authentication Library (MSAL) használatával. Egyes felhasználók webböngészőn keresztüli interakciót igényelnek, míg mások nem igényelnek felhasználói beavatkozást. A jogkivonat beszerzéséhez használt módszer általában attól függ, hogy az alkalmazás nyilvános ügyfélalkalmazás (asztali vagy mobil), vagy bizalmas ügyfélalkalmazás (webalkalmazás, webes API vagy démonalkalmazás).

Az MSAL gyorsítótárazza a jogkivonatot annak beszerzése után. Az alkalmazáskódnak először meg kell próbálnia csendesen lekérni egy jogkivonatot a gyorsítótárból, mielőtt más módon próbálná meg beszerezni a jogkivonatot.

A token gyorsítótár törléséhez törölje a fiókokat a gyorsítótárból. Ez azonban nem távolítja el a böngészőben található munkamenet-cookie-t.

Hatókörök a jogkivonatok beszerzésekor

A hatókörök azok az engedélyek, amelyeket egy webes API tesz elérhetővé, és amelyekhez az ügyfélalkalmazások hozzáférést kérhetnek. Az ügyfélalkalmazások a felhasználói hozzájárulást kérik ezekhez a hatókörökhöz, amikor hitelesítési kéréseket intéznek a webes API-k eléréséhez szükséges jogkivonatok lekéréséhez. Az MSAL lehetővé teszi, hogy hozzáférési tokent szerezzen be a Microsoft identitásplatform API-k eléréséhez. A v2.0 protokoll erőforrás helyett hatóköröket használ a kérésekben. A webes API által elfogadott jogkivonat-verzió konfigurációja alapján a 2.0-s verziójú végpont visszaadja a hozzáférési jogkivonatot az MSAL-nek.

Az MSAL több jogkivonat-beszerzési metódusához scopes paraméter szükséges. A scopes paraméter azoknak a sztringeknek a listája, amelyek deklarálják a kívánt engedélyeket és a kért erőforrásokat. A jól ismert hatókörök a Microsoft Graph-engedélyek.

Webes API hatóköreinek kérése

Ha az alkalmazásnak egy adott engedélyekkel rendelkező hozzáférési jogkivonatot kell kérnie egy erőforrás API-hoz, adja át az API alkalmazásazonosítójának URI-ját tartalmazó hatóköröket a formátumban <app ID URI>/<scope>.

Néhány példa hatókörértékek különböző erőforrásokhoz:

  • Microsoft Graph API: https://graph.microsoft.com/User.Read
  • Egyéni webes API: api://00001111-aaaa-2222-bbbb-3333cccc4444/api.read

A hatókör értékének formátuma attól függően változik, hogy az erőforrás (az API) megkapja-e a hozzáférési jogkivonatot és az aud általa elfogadott jogcímértékeket.

Csak a Microsoft Graph esetében a user.read hatókör a https://graph.microsoft.com/User.Read hatókörrel van leképezve, és mindkét hatókörformátum felcserélhető.

Bizonyos webes API-k, például az Azure Resource Manager API (https://management.core.windows.net/), a hozzáférési token célközönség jogcímében (aud) egy záró perjelet (/) várnak. Ebben az esetben adja át a hatókört a következőként https://management.core.windows.net//user_impersonation, beleértve a kettős perjelet (//).

Más API-k megkövetelhetik, hogy a hatókör értéke ne tartalmazzon sémát vagy gazdagépet, és csak az alkalmazásazonosítót (GUID) és a hatókör nevét várhatják, például:

00001111-aaaa-2222-bbbb-3333cccc4444/api.read

Tipp.

Ha az alsóbb rétegbeli erőforrás nincs az Ön felügyelete alatt, előfordulhat, hogy különböző hatókörérték-formátumokat kell kipróbálnia (például séma és gazdagép nélkül), ha a hozzáférési jogkivonatnak az erőforrásnak való átadásakor hibaüzenetet kap 401 .

Ahogy az alkalmazás által biztosított funkciók vagy azok követelményei megváltoznak, szükség szerint további engedélyeket kérhet a hatókör paraméterrel. Az ilyen dinamikus hatókörök lehetővé teszik a felhasználók számára, hogy növekményes hozzájárulást adjanak a hatókörökhöz.

Előfordulhat például, hogy bejelentkezteti a felhasználót, de kezdetben nem ad nekik hozzáférést az erőforrásokhoz. Később lehetővé teheti számukra a naptár megtekintését a naptár hatókörének lekérésével a jogkivonat beszerzésének módjában, és a felhasználó hozzájárulásának beszerzéséhez. Például a https://graph.microsoft.com/User.Read és https://graph.microsoft.com/Calendar.Read hatókörök kérésével.

Tokenek csendes megszerzése (a gyorsítótárból)

Az MSAL a jogkivonat-gyorsítótárat (vagy a bizalmas ügyfélalkalmazások két gyorsítótárát) tartja fenn, és a jogkivonatot a beszerzése után gyorsítótárazza. Sok esetben egy jogkivonat csendes lekérése a gyorsítótárban lévő jogkivonaton alapuló, több hatókörrel rendelkező másik jogkivonat beszerzését eredményezi. Akkor is képes frissíteni egy jogkivonatot, ha közel van a lejárathoz (mivel a jogkivonat gyorsítótára is tartalmaz frissítési jogkivonatot).

Az alkalmazás forráskódjának először meg kell próbálnia észrevétlenül lekérni egy jogkivonatot a gyorsítótárból. Ha a metódus hívás "felhasználói felület szükséges" hibát vagy kivételt ad vissza, próbáljon meg más módon tokent beszerezni.

Két folyamat van, amelyekben nem szabad észrevétlenül megszerezni egy token-t:

  • Az ügyfél hitelesítő adatainak folyamata, amely nem a felhasználói jogkivonat-gyorsítótárat, hanem az alkalmazásjogkivonat-gyorsítótárat használja. Ez a módszer gondoskodik az alkalmazásjogkivonat-gyorsítótár ellenőrzéséről, mielőtt kérést küldene a biztonsági jogkivonat-szolgáltatásnak (STS).
  • A webalkalmazások engedélyezési kódfolyamata , mivel a felhasználó bejelentkeztetésével és további hatókörökhöz való hozzájárulásukkal az alkalmazás által beszerzett kódot beváltja. Mivel a rendszer nem paraméterként ad át egy kódot, hanem egy fiókot, a metódus nem tud a gyorsítótárban keresni a kód beváltása előtt, amely meghívja a szolgáltatás hívását.

Az OpenID Connect engedélyezési kódfolyamatot használó webalkalmazások esetében a vezérlőkben javasolt minta a következő:

  • Bizalmas ügyfélalkalmazás példányosítása token gyorsítótárral és testreszabott szerializálással.
  • A token beszerzése az engedélyezési kód folyamat használatával

Tokenek beszerzése

A jogkivonatok beszerzésének módja attól függ, hogy nyilvános vagy bizalmas ügyfélalkalmazásról van-e szó.

Nyilvános ügyfélalkalmazások

Nyilvános ügyfélalkalmazásokban (asztali és mobil) az alábbiakat végezheti el:

  • Az interaktív tokenlekéréshez a felhasználó jelentkezzen be a felhasználói felületen vagy egy felugró ablakon keresztül.
  • Ha az asztali alkalmazás egy tartományhoz vagy Azure-hoz csatlakoztatott Windows-számítógépen fut, egy csendes művelettel jogkivonatot szerezhet a bejelentkezett felhasználó számára, integrált Windows-hitelesítéssel (IWA/Kerberos).
  • Szerezzen be egy jogkivonatot felhasználónév és jelszó használatával .NET-keretrendszer asztali ügyfélalkalmazásokban (nem ajánlott). Ne használjon felhasználónevet/jelszót bizalmas ügyfélalkalmazásokban.
  • Jogkivonat lekérése az eszközkódos hitelesítési folyamatban eszközökön futó alkalmazásokban, amelyek nem rendelkeznek webböngészővel. A felhasználó egy URL-címet és egy kódot kapott, aki ezután egy másik eszközön lévő webböngészőbe megy, és beírja a kódot, és bejelentkezik. A Microsoft Entra ID ezután egy tokent küld vissza a böngésző nélküli eszközre.

Bizalmas ügyfélalkalmazások

Bizalmas ügyfélalkalmazások (webalkalmazás, webes API vagy démonalkalmazás, például Windows-szolgáltatás) esetén a következőket teheti:

  • Az alkalmazás számára, és nem egy felhasználó számára szerezzen jogkivonatokat az ügyfél-hitelesítési folyamat segítségével. Ez a technika olyan eszközök szinkronizálására használható, amelyek általában a felhasználókat dolgozzák fel, és nem egy adott felhasználót.
  • Az OBO-áramlást használva egy webes API-nál tud meghívást intézni a felhasználó nevében egy API-hoz. Az alkalmazás ügyfél-hitelesítő adatokkal van azonosítva, hogy jogkivonatot szerezzen be egy felhasználói állítás (PÉLDÁUL SAML vagy JWT-jogkivonat) alapján. Ezt a folyamatot olyan alkalmazások használják, amelyeknek egy adott felhasználó erőforrásaihoz kell hozzáférni a szolgáltatásközi hívásokban. A tokeneket munkamenet szinten kell gyorsítótárazni, nem felhasználói szinten.
  • Miután a felhasználó bejelentkezett az engedélyezési kérelem URL-címén keresztül, szerezzünk tokeneket a webalkalmazások az engedélyezési kódfolyamatot használva. Az OpenID Connect-alkalmazás általában ezt a mechanizmust használja, amely lehetővé teszi, hogy a felhasználó az OpenID Connect használatával jelentkezzen be, majd a felhasználó nevében hozzáférjen a webes API-khoz. A tokenek gyorsítótárazhatók felhasználók vagy munkamenetek alapján. Ha felhasználói alapon tárol gyorsítótáraz jogkivonatokat, javasoljuk, hogy korlátozza a munkamenet élettartamát, hogy a Microsoft Entra ID gyakrabban ellenőrizhesse a feltételes hozzáférési szabályzatok állapotát.

Hitelesítési eredmények

Amikor az ügyfél hozzáférési jogkivonatot kér, a Microsoft Entra ID egy olyan hitelesítési eredményt is ad vissza, amely metaadatokat tartalmaz a hozzáférési jogkivonatról. Ezek az információk tartalmazzák a hozzáférési jogkivonat lejárati idejét és az érvényes hatóköröket. Ezek az adatok lehetővé teszik az alkalmazás számára a hozzáférési jogkivonatok intelligens gyorsítótárazását anélkül, hogy magát a hozzáférési jogkivonatot kellene elemeznie. A hitelesítési eredmény a következőt teszi elérhetővé:

  • A webes API hozzáférési jogkivonata az erőforrások eléréséhez. Ez a sztring általában Base64 kódolású JWT, de az ügyfélnek soha nem szabad belenéznie a hozzáférési jogkivonatba. A formátum nem garantáltan stabil marad, és titkosítható az erőforrás számára. A kliens hozzáférési token tartalmától függően kódot írni az egyik leggyakoribb hibaforrás és a kliens logikájának megszakadásának oka.
  • A felhasználó azonosító jogkivonata (JWT).
  • A jogkivonat lejárata, amely a jogkivonat lejárati dátumát/időpontját jelzi.
  • A bérlőazonosító tartalmazza azt a bérlőt, amelyben a felhasználó megtalálható. Vendégfelhasználók (Microsoft Entra B2B-forgatókönyvek) esetén a bérlőazonosító a vendégbérlő, nem az egyedi bérlő. Amikor a jogkivonatot egy felhasználó nevében kézbesítik, a hitelesítési eredmény a felhasználóra vonatkozó információkat is tartalmaz. Az olyan bizalmas ügyfélfolyamatok esetében, ahol a jogkivonatok felhasználó nélkül kérvényezhetők az alkalmazáshoz, a felhasználói adatok null értékűek.
  • Azok a hatókörök, amelyekhez a jogkivonatot kiadták.
  • A felhasználó egyedi azonosítója.

(Speciális) A felhasználó gyorsítótárazott tokenjeinek elérése háttéralkalmazásokban és -szolgáltatásokban

Az MSAL jogkivonat-gyorsítótár-implementációjával lehetővé teheti, hogy a háttéralkalmazások, API-k és szolgáltatások a hozzáférési jogkivonat-gyorsítótár használatával továbbra is a felhasználók nevében járjanak el távollétükben. Ez különösen akkor hasznos, ha a háttéralkalmazások és -szolgáltatások továbbra is a felhasználó nevében dolgoznak, miután a felhasználó kilép az előtér-webalkalmazásból.

Ma a legtöbb háttérfolyamat alkalmazásengedélyeket használ, ha anélkül kell dolgozniuk egy felhasználó adataival, hogy a hitelesítéshez vagy az újrahitelesítéshez jelen lennének. Mivel az alkalmazásengedélyek gyakran rendszergazdai hozzájárulást igényelnek, ami jogosultságszint-emelést igényel, szükségtelen súrlódások lépnek fel, mivel a fejlesztő nem kívánt olyan engedélyhez jutni, amelyhez a felhasználó eredetileg hozzájárult az alkalmazáshoz.

Ez a Kódminta a GitHubon bemutatja, hogyan kerülheti el ezt a szükségtelen súrlódást az MSAL jogkivonat-gyorsítótárának háttéralkalmazásokból való elérésével:

A bejelentkezett felhasználó token gyorsítótárának elérése háttéralkalmazásokból, API-kból és szolgáltatásokból

Jegyzet

A jogkivonatok hitelesítési közvetítőhasználatával történő interaktív beszerzésekor a hitelesítési közvetítő először gyorsítótár-keresést végez, és ha elérhető, a gyorsítótárazott jogkivonatot adja vissza (GitHub-probléma – a acquireToken gyorsítótárazásihasznál).

Lásd még

Az MSAL által támogatott platformok dokumentációi közül több is tartalmaz bővebb információt a token gyorsítótárral kapcsolatban a platform könyvtárára vonatkozóan. Példa: