Získání a ukládání tokenů do mezipaměti pomocí knihovny Microsoft Authentication Library (MSAL)

  • Článek

Přístupové tokeny umožňují klientům bezpečně volat webová rozhraní API chráněná Azure. Token můžete získat několika způsoby pomocí knihovny MSAL (Microsoft Authentication Library). Některé vyžadují interakci uživatele prostřednictvím webového prohlížeče, zatímco jiné nevyžadují interakci uživatele. Metoda používaná k získání tokenu obvykle závisí na tom, jestli je aplikace veřejná klientská aplikace (desktopová nebo mobilní), nebo důvěrná klientská aplikace (webová aplikace, webové rozhraní API nebo aplikace démona).

Služba MSAL ukládá token do mezipaměti po jeho získání. Kód aplikace by se měl nejprve pokusit získat token bezobslužně z mezipaměti před pokusem o získání tokenu jinými prostředky.

Mezipaměť tokenů můžete také vymazat odebráním účtů z mezipaměti. Tím se ale neodebere soubor cookie relace, který je v prohlížeči.

Obory při získávání tokenů

Obory jsou oprávnění, ke kterým webové rozhraní API zpřístupňuje, aby klientské aplikace mohly požádat o přístup. Klientské aplikace požadují souhlas uživatele s těmito obory při provádění žádostí o ověření, aby získaly tokeny pro přístup k webovým rozhraním API. MSAL umožňuje získat tokeny pro přístup k rozhraním API platformy Microsoft Identity Platform. Protokol v2.0 používá obory místo prostředků v požadavcích. Na základě konfigurace webového rozhraní API verze tokenu, která přijímá, koncový bod v2.0 vrátí přístupový token do knihovny MSAL.

Několik metod získávání tokenů MSAL vyžaduje scopes parametr. Parametr scopes je seznam řetězců, které deklarují požadovaná oprávnění a požadované prostředky. Dobře známé obory jsou oprávnění Microsoft Graphu.

Rozsahy požadavků pro webové rozhraní API

Když vaše aplikace potřebuje požádat o přístupový token s konkrétními oprávněními pro rozhraní API prostředku, předejte obory obsahující identifikátor URI ID aplikace rozhraní API ve formátu <app ID URI>/<scope>.

Příklady hodnot rozsahu pro různé prostředky:

  • Microsoft Graph API: https://graph.microsoft.com/User.Read
  • Vlastní webové rozhraní API: api://11111111-1111-1111-1111-111111111111/api.read

Formát hodnoty oboru se liší v závislosti na prostředku (rozhraní API) přijímajícím přístupový token a aud hodnotách deklarací identity, které přijímá.

Pouze pro Microsoft Graph se user.read obor mapuje na https://graph.microsoft.com/User.Readformáty oborů a oba formáty oborů lze zaměnitelně.

Některá webová rozhraní API, jako je rozhraní API Azure Resource Manageru (https://management.core.windows.net/), očekávají koncové lomítko (/) v deklaraci identity cílové skupiny (aud) přístupového tokenu. V tomto případě předejte rozsah jako https://management.core.windows.net//user_impersonation, včetně dvojitého lomítka (//).

Jiná rozhraní API můžou vyžadovat, aby v hodnotě oboru nebyla zahrnuta žádná schémata nebo hostitel , a očekávat pouze ID aplikace (GUID) a název oboru, například:

11111111-1111-1111-1111-111111111111/api.read

Tip

Pokud podřízený prostředek není pod vaší kontrolou, možná budete muset vyzkoušet různé formáty hodnot oboru (například se schématem nebo bez schématu a hostitele), pokud při předávání přístupového tokenu prostředku dojde 401 k jiným chybám.

Vzhledem k tomu, že se funkce poskytované vaší aplikací nebo jejími požadavky mění, můžete podle potřeby požádat o další oprávnění pomocí parametru oboru. Tyto dynamické obory umožňují uživatelům poskytovat přírůstkový souhlas s obory.

Můžete se například přihlásit k uživateli, ale zpočátku mu odepřít přístup k jakýmkoli prostředkům. Později jim můžete dát možnost zobrazit si svůj kalendář vyžádáním rozsahu kalendáře v metodě získání tokenu a získáním souhlasu uživatele. Například vyžádáním rozsahů https://graph.microsoft.com/User.Read a https://graph.microsoft.com/Calendar.Read oborů.

Bezobslužné získání tokenů (z mezipaměti)

Služba MSAL udržuje mezipaměť tokenů (nebo dvě mezipaměti pro důvěrné klientské aplikace) a ukládá token do mezipaměti po jeho získání. V mnoha případech se pokus o bezobslužné získání tokenu získá další token s více obory na základě tokenu v mezipaměti. Je také schopen aktualizovat token, když se blíží vypršení platnosti (protože mezipaměť tokenů obsahuje také obnovovací token).

Zdrojový kód aplikace by se měl nejprve pokusit získat token bezobslužně z mezipaměti. Pokud volání metody vrátí chybu nebo výjimku "vyžaduje uživatelské rozhraní", zkuste získat token jiným způsobem.

Existují dva toky, ve kterých byste se neměli pokoušet bezobslužně získat token:

  • Tok přihlašovacích údajů klienta, který nepoužívá mezipaměť tokenů uživatele, ale mezipaměť tokenů aplikace. Tato metoda se postará o ověření mezipaměti tokenů aplikace před odesláním požadavku službě tokenů zabezpečení (STS).
  • Tok autorizačního kódu ve webových aplikacích, protože uplatní kód, který aplikace získala přihlášením uživatele a udělením souhlasu s větším rozsahem. Vzhledem k tomu, že kód a ne účet se předává jako parametr, metoda nemůže před uplatněním kódu hledat v mezipaměti, což vyvolá volání služby.

U webových aplikací, které používají tok autorizačního kódu OpenID Připojení, je doporučeným vzorem v kontrolerů:

  • Vytvořte instanci důvěrné klientské aplikace s mezipamětí tokenů s přizpůsobenou serializací.
  • Získání tokenu pomocí toku autorizačního kódu

Získávání tokenů

Metoda získání tokenu závisí na tom, jestli se jedná o veřejného klienta nebo důvěrnou klientskou aplikaci.

Veřejné klientské aplikace

Ve veřejných klientských aplikacích (desktopových a mobilních) můžete:

  • Získejte tokeny interaktivně tím, že se uživatel přihlásí přes uživatelské rozhraní nebo automaticky otevírané okno.
  • Pokud je desktopová aplikace spuštěná na počítači s Windows připojeným k doméně nebo k Azure, získejte token bezobslužně pro přihlášeného uživatele pomocí integrovaného ověřování systému Windows (IWA/Kerberos).
  • Získání tokenu s uživatelským jménem a heslem v desktopových klientských aplikacích rozhraní .NET Framework (nedoporučuje se). Nepoužívejte uživatelské jméno a heslo v důvěrných klientských aplikacích.
  • Získejte token prostřednictvím toku kódu zařízení v aplikacích spuštěných na zařízeních, která nemají webový prohlížeč. Uživatel má adresu URL a kód, který pak přejde do webového prohlížeče na jiném zařízení a zadá kód a přihlásí se. Microsoft Entra ID pak odešle token zpět do zařízení bez prohlížeče.

Důvěrné klientské aplikace

Pro důvěrné klientské aplikace (webová aplikace, webové rozhraní API nebo aplikace démona, jako je služba Windows), můžete;

  • Získání tokenů pro samotnou aplikaci, nikoli pro uživatele, pomocí toku přihlašovacích údajů klienta. Tuto techniku lze použít pro synchronizační nástroje nebo nástroje, které zpracovávají uživatele obecně, a ne pro konkrétního uživatele.
  • Použijte tok on-behalf-of (OBO) pro webové rozhraní API k volání rozhraní API jménem uživatele. Aplikace je identifikována pomocí přihlašovacích údajů klienta, aby získala token na základě kontrolního výrazu uživatele (například SAML nebo tokenU JWT). Tento tok používají aplikace, které potřebují přístup k prostředkům konkrétního uživatele při volání mezi službami. Tokeny by se měly ukládat do mezipaměti na základě relace, ne na základě uživatele.
  • Získejte tokeny pomocí toku autorizačního kódu ve webových aplikacích po přihlášení uživatele prostřednictvím adresy URL žádosti o autorizaci. OpenID Připojení aplikace obvykle používá tento mechanismus, který uživateli umožňuje přihlásit se pomocí OpenID Připojení a pak přistupovat k webovým rozhraním API jménem uživatele. Tokeny se dají ukládat do mezipaměti uživatele nebo relace. Pokud se tokeny ukládají do mezipaměti na základě uživatele, doporučujeme omezit dobu životnosti relace, aby ID Microsoft Entra mohl často kontrolovat stav zásad podmíněného přístupu.

Výsledky ověřování

Když klient požádá o přístupový token, vrátí ID Microsoft Entra také výsledek ověřování, který obsahuje metadata o přístupovém tokenu. Tyto informace zahrnují dobu vypršení platnosti přístupového tokenu a rozsahy, pro které je platný. Tato data umožňují vaší aplikaci provádět inteligentní ukládání přístupových tokenů do mezipaměti, aniž by bylo nutné analyzovat samotný přístupový token. Výsledek ověřování zveřejňuje:

  • Přístupový token pro webové rozhraní API pro přístup k prostředkům. Tento řetězec je obvykle kódovaný JWT s kódováním Base64, ale klient by nikdy neměl hledat uvnitř přístupového tokenu. Formát není zaručený, že zůstane stabilní a může být pro prostředek zašifrovaný. Lidé psaní kódu v závislosti na obsahu přístupového tokenu v klientovi je jedním z nejběžnějších zdrojů chyb a přerušení logiky klienta.
  • Token ID pro uživatele (JWT).
  • Vypršení platnosti tokenu sděluje datum a čas vypršení platnosti tokenu.
  • ID tenanta obsahuje tenanta, ve kterém byl uživatel nalezen. Pro uživatele typu host (scénáře Microsoft Entra B2B) je ID tenanta typu host, nikoli jedinečný tenant. Když se token doručí jménem uživatele, výsledek ověření obsahuje také informace o tomto uživateli. V případě důvěrných toků klientů, u kterých jsou tokeny požadovány bez uživatele (pro aplikaci), mají tyto informace o uživateli hodnotu null.
  • Obory, pro které byl token vystaven.
  • Jedinečné ID uživatele.

(Upřesnit) Přístup k tokenům uživatele uloženým v mezipaměti v aplikacích a službách na pozadí

Implementaci mezipaměti tokenů MSAL můžete použít k tomu, aby aplikace, rozhraní API a služby na pozadí mohly používat mezipaměť přístupových tokenů a nadále jednat jménem uživatelů v jejich nepřítomnosti. To je užitečné zejména v případě, že aplikace a služby na pozadí musí pokračovat v práci jménem uživatele poté, co uživatel ukončí front-endovou webovou aplikaci.

Většina procesů na pozadí v současné době používá oprávnění aplikace, když potřebují pracovat s daty uživatele, aniž by je bylo možné ověřit nebo znovu ověřit. Vzhledem k tomu, že oprávnění aplikací často vyžadují souhlas správce, což vyžaduje zvýšení oprávnění, dochází k zbytečným třením, protože vývojář neměl v úmyslu získat oprávnění nad rámec toho, ke kterému uživatel původně souhlasil pro svou aplikaci.

Tento ukázkový kód na GitHubu ukazuje, jak se vyhnout nepotřebným třením tím, že přistupujete k mezipaměti tokenů MSAL z aplikací na pozadí:

Přístup k mezipaměti tokenů přihlášeného uživatele z aplikací na pozadí, rozhraní API a služeb

Viz také

Několik platforem podporovaných knihovnou MSAL obsahuje další informace související s mezipamětí tokenů v dokumentaci pro knihovnu dané platformy. Příklad: