Sdílet prostřednictvím

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

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.

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

Rozsahy oprávnění jsou oprávnění, která webové rozhraní API zpřístupňuje, aby mohly klientské aplikace žá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 verze tokenu webového rozhraní API, kterou přijímá, vrátí koncový bod v2.0 přístupový token pro knihovnu 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á oprávnění 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 API určitého prostředku, předejte rozsahy obsahující identifikátor URI ID aplikace daného 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://00001111-aaaa-2222-bbbb-3333cccc4444/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í (claimů), které akceptuje.

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

Některá webová rozhraní API, jako je rozhraní API Azure Resource Manager (https://management.core.windows.net/), očekávají koncové lomítko (/) v deklaraci příjemce (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 nebyly zahrnuty ani schéma, ani hostitel, a očekávala pouze identifikátor aplikace (GUID) a název oboru, například:

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

Návod

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 obdržíte 401 nebo jiné chyby při předávání přístupového tokenu prostředku.

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.

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 vám pokus tiše získat token přinese další token s více rozsahy 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 klientských přihlašovacích údajů, který nepoužívá uživatelskou mezipaměť tokenů, ale aplikační mezipaměť tokenů. Tato metoda se postará o ověření mezipaměti tokenů aplikace před odesláním požadavku službě tokenů zabezpečení (STS).
  • Průběh autorizačního kódu ve webových aplikacích tím, že uplatní kód, který aplikace získala přihlášením uživatele a udělením souhlasu s větším rozsahem. Jelikož je jako parametr předán kód a ne účet, metoda nemůže před uplatněním kódu kontrolovat mezipaměť, což znamená, že musí vyvolat volání služby.

Pro webové aplikace, které používají autorizační kódový tok OpenID Connect, je doporučený vzor v kontrolerech:

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

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 pomocí procesu kódu zařízení v aplikacích běžící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 démonová aplikace, jako je služba Windows), můžete:

  • Získejte tokeny pro samotnou aplikaci a ne 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.
  • Pro volání rozhraní API jménem uživatele použijte tok on-behalf-of (OBO) pro webové rozhraní API. Aplikace je identifikována pomocí přihlašovacích údajů klienta, aby získala token na základě uživatelského tvrzení (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. Aplikace OpenID Connect obvykle používá tento mechanismus, který uživateli umožňuje přihlásit se pomocí OpenID Connect a pak přistupovat k webovým rozhraním API jménem uživatele. Tokeny mohou být ukládány do mezipaměti na úrovni uživatele nebo relace. Pokud se tokeny ukládají do mezipaměti na základě uživatele, doporučujeme omezit dobu životnosti relace, aby mohla identita Microsoft Entra č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 lze jej zašifrovat pro zdroj. Lidé, kteří píší kód 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 udává datum a čas, kdy token vyprší.
  • ID tenanta obsahuje tenanta, ve kterém byl uživatel nalezen. Pro hostující uživatele (scénáře Microsoft Entra B2B) je ID tenanta hostitelským tenantem, nikoli jedinečným tenantem. 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í dnes používá oprávnění aplikace k práci s daty uživatele, aniž by uživatel musel být přítomen pro ověření nebo znovu ověření. 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: