Jogkivonatok beszerzése és gyorsítótárazása a Microsoft Authentication Library (MSAL) használatával
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://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 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:
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
.
Dinamikus hatókörök kérése növekményes hozzájáruláshoz
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).
Ajánlott hívásminta nyilvános ügyfélalkalmazásokhoz
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.
Ajánlott hívásminta a webalkalmazásokban az engedélyezési kódfolyamat használatával
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:
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: