Jogkivonatok beszerzé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öbbféleképpen is beszerezheti 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 a 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 jogkivonat-gyorsítótár törléséhez távolítsa el 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 jogkivonatok beszerzésekor

A hatókörök azok az engedélyek, amelyekhez az ügyfélalkalmazások hozzáférést kérhetnek a webes API-k számára. 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 jogkivonatokat szerezzen be 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 paraméter szükséges scopes . 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://11111111-1111-1111-1111-111111111111/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 hatókör leképezi user.read a hatókört https://graph.microsoft.com/User.Read, é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 jogkivonat célközönségi jogcímébenaud () 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árják, például:

11111111-1111-1111-1111-111111111111/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 bejelentkezik a felhasználóba, de kezdetben megtagadja az erőforrásokhoz való hozzáférést. 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 hatókörök és https://graph.microsoft.com/Calendar.Read a https://graph.microsoft.com/User.Read hatókörök kérésével.

Jogkivonatok csendes beszerzé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. A jogkivonat csendes lekérésének megkísérlése sok esetben egy másik, a gyorsítótárban lévő jogkivonaton alapuló hatókörökkel rendelkező jogkivonatot fog beszerezni. 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 csendesen lekérni egy jogkivonatot a gyorsítótárból. Ha a metódushí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 jogkivonatot beszerezni.

Két folyamat van, amelyekben nem szabad csendesen megszerezni egy jogkivonatot:

  • 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 Csatlakozás 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 jogkivonat-gyorsítótárral, testreszabott szerializálással.
  • A jogkivonat beszerzése az engedélyezési kód folyamatával

Jogkivonatok 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:

  • A jogkivonatok interaktív lekéréséhez a felhasználó egy felhasználói felületen vagy előugró ablakban jelentkezzen be.
  • Ha az asztali alkalmazás tartományhoz vagy Azure-hoz csatlakoztatott Windows-számítógépen fut, csendes jogkivonatot kérhet le a bejelentkezett felhasználóhoz integrált Windows-hitelesítéssel (IWA/Kerberos).
  • Szerezzen be egy felhasználónevet és jelszót tartalmazó jogkivonatot .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ód folyamatán olyan 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 jogkivonatot 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 ügyfél hitelesítő adatainak folyamatával jogkivonatokat szerezhet be magának az alkalmazásnak, és nem egy felhasználónak. 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.
  • A webes API nevében történő (OBO) folyamat használatával meghívhat egy API-t a felhasználó nevében. 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 jogkivonatokat munkamenet alapján kell gyorsítótárazni, nem felhasználói alapon.
  • Jogkivonatok beszerzése a webalkalmazások engedélyezési kódfolyamatával , miután a felhasználó bejelentkezett az engedélyezési kérelem URL-címén keresztül. Az OpenID Csatlakozás alkalmazás általában ezt a mechanizmust használja, amely lehetővé teszi, hogy a felhasználó openID Csatlakozás használatával jelentkezzen be, majd a felhasználó nevében hozzáférjen a webes API-khoz. A jogkivonatok gyorsítótárazhatók felhasználó vagy munkamenet alapján. Ha felhasználói alapon gyorsítótáraz jogkivonatokat, javasoljuk, hogy korlátozza a munkamenet élettartamát, hogy a Microsoft Entra-azonosító gyakran ellenőrizze 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 Egy 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. Kapcsolatok kód írása az ügyfél hozzáférési jogkivonat-tartalmától függően az egyik leggyakoribb hibaforrás és az ügyféllogika megszakadása.
  • 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ó nem az egyedi bérlő, hanem a vendégbérlelő. 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 (az alkalmazáshoz) kérnek jogkivonatokat, ezek 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 jogkivonatainak 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ó jogkivonat-gyorsítótárának elérése háttéralkalmazásokból, API-kból és szolgáltatásokból

Lásd még

Az MSAL által támogatott platformok közül több is rendelkezik további jogkivonat-gyorsítótárral kapcsolatos információkkal a platform kódtárának dokumentációjában. Példa: