Desktopová aplikace, která volá webová rozhraní API: Získání tokenu pomocí WAM

  • Článek

Microsoft Authentication Library (MSAL) volá Správce webových účtů (WAM), komponentu Windows 10+, která funguje jako zprostředkovatel ověřování. Zprostředkovatel umožňuje uživatelům vaší aplikace využívat integraci s účty známými pro Windows, například účet, který jste se přihlásili k relaci Windows.

Návrh hodnoty WAM

Použití zprostředkovatele ověřování, jako je WAM, má řadu výhod:

  • Lepší zabezpečení. Viz Ochrana tokenů.
  • Podpora klíčů Windows Hello, podmíněného přístupu a FIDO
  • Integrace se zobrazením e-mailů a účtů systému Windows
  • Rychlé jednotné přihlašování.
  • Možnost přihlásit se bezobslužně pomocí aktuálního účtu Windows.
  • Opravy chyb a vylepšení dodávaná s Windows

Omezení WAM

  • WAM je k dispozici ve Windows 10 a novějších verzích a v systémech Windows Server 2019 a novějších. V systémech Mac, Linux a starších verzích Windows se knihovna MSAL automaticky vrátí do prohlížeče.
  • Autority Azure Active Directory B2C (Azure AD B2C) a Active Directory Federation Services (AD FS) (AD FS) se nepodporují. Knihovna MSAL se vrátí do prohlížeče.

Integrační balíček WAM

Většina aplikací musí odkazovat na Microsoft.Identity.Client.Broker balíček, aby tuto integraci používala. Aplikace .NET MAUI to nemusí dělat, protože funkce se nachází uvnitř knihovny MSAL, pokud je net6-windows cíl a novější.

Model volání WAM

Pro WAM můžete použít následující vzor:

    // 1. Configuration - read below about redirect URI
    var pca = PublicClientApplicationBuilder.Create("client_id")
                    .WithBroker(new BrokerOptions(BrokerOptions.OperatingSystems.Windows))
                    .Build();

    // Add a token cache; see https://learn.microsoft.com/azure/active-directory/develop/msal-net-token-cache-serialization?tabs=desktop

    // 2. Find an account for silent login

    // Is there an account in the cache?
    IAccount accountToLogin = (await pca.GetAccountsAsync()).FirstOrDefault();
    if (accountToLogin == null)
    {
        // 3. No account in the cache; try to log in with the OS account
        accountToLogin = PublicClientApplication.OperatingSystemAccount;
    }

    try
    {
        // 4. Silent authentication 
        var authResult = await pca.AcquireTokenSilent(new[] { "User.Read" }, accountToLogin)
                                    .ExecuteAsync();
    }
    // Cannot log in silently - most likely Azure AD would show a consent dialog or the user needs to re-enter credentials
    catch (MsalUiRequiredException) 
    {
        // 5. Interactive authentication
        var authResult = await pca.AcquireTokenInteractive(new[] { "User.Read" })
                                    .WithAccount(accountToLogin)
                                    // This is mandatory so that WAM is correctly parented to your app; read on for more guidance
                                    .WithParentActivityOrWindow(myWindowHandle) 
                                    .ExecuteAsync();
                                    
        // Consider allowing the user to re-authenticate with a different account, by calling AcquireTokenInteractive again                                  
    }

Pokud zprostředkovatel není (například Windows 8.1, Mac nebo Linux), MSAL se vrátí do prohlížeče, kde platí pravidla identifikátoru URI přesměrování.

URI pro přesměrování

V knihovně MSAL nemusíte konfigurovat identifikátory URI přesměrování WAM, ale musíte je nakonfigurovat v registraci aplikace:

ms-appx-web://microsoft.aad.brokerplugin/{client_id}

Trvalost mezipaměti tokenů

Je důležité zachovat mezipaměť tokenů MSAL, protože SLUŽBA MSAL tam nadále ukládá tokeny ID a metadata účtu. Další informace naleznete v tématu Serializace mezipaměti tokenů v MSAL.NET.

Účet pro tiché přihlášení

Pokud chcete najít účet pro tiché přihlášení, doporučujeme tento vzor:

  • Pokud se uživatel dříve přihlásil, použijte tento účet. Pokud ne, použijte PublicClientApplication.OperatingSystemAccount pro aktuální účet Windows.
  • Umožňuje uživateli přejít na jiný účet interaktivním přihlášením.

Nadřazené úchyty oken

Nástroj MSAL musíte nakonfigurovat s oknem, na které má být interaktivní prostředí nadřazené pomocí WithParentActivityOrWindow rozhraní API.

Aplikace uživatelského rozhraní

U aplikací uživatelského rozhraní, jako jsou model Windows Forms (WinForms), Windows Presentation Foundation (WPF) nebo Windows UI Library verze 3 (WinUI3), najdete v tématu Načtení popisovače okna.

Konzolové aplikace

Pro konzolové aplikace je konfigurace více zapojena z důvodu okna terminálu a jeho karet. Použijte následující kód:

enum GetAncestorFlags
{   
    GetParent = 1,
    GetRoot = 2,
    /// <summary>
    /// Retrieves the owned root window by walking the chain of parent and owner windows returned by GetParent.
    /// </summary>
    GetRootOwner = 3
}

/// <summary>
/// Retrieves the handle to the ancestor of the specified window.
/// </summary>
/// <param name="hwnd">A handle to the window whose ancestor will be retrieved.
/// If this parameter is the desktop window, the function returns NULL. </param>
/// <param name="flags">The ancestor to be retrieved.</param>
/// <returns>The return value is the handle to the ancestor window.</returns>
[DllImport("user32.dll", ExactSpelling = true)]
static extern IntPtr GetAncestor(IntPtr hwnd, GetAncestorFlags flags);

[DllImport("kernel32.dll")]
static extern IntPtr GetConsoleWindow();

// This is your window handle!
public IntPtr GetConsoleOrTerminalWindow()
{
   IntPtr consoleHandle = GetConsoleWindow();
   IntPtr handle = GetAncestor(consoleHandle, GetAncestorFlags.GetRootOwner );
  
   return handle;
}

Řešení problému

Chybová zpráva "Výběr účtu WAM nevrátil účet"

Zpráva "Výběr účtu WAM nevrátila účet" značí, že buď uživatel aplikace zavřel dialogové okno, ve které se zobrazují účty, nebo samotný dialog se chybově ukončil. K chybovému ukončení může dojít, pokud AccountsControlje v systému Windows nesprávně zaregistrován ovládací prvek Windows. Tento problém vyřešíte takto:

  1. Na hlavním panelu klikněte pravým tlačítkem na Start a pak vyberte Prostředí Windows PowerShell (Správa).

  2. Pokud se zobrazí výzva dialogového okna Řízení uživatelských účtů, vyberte Ano a spusťte PowerShell.

  3. Zkopírujte a spusťte následující skript:

    if (-not (Get-AppxPackage Microsoft.AccountsControl)) { Add-AppxPackage -Register "$env:windir\SystemApps\Microsoft.AccountsControl_cw5n1h2txyewy\AppxManifest.xml" -DisableDevelopmentMode -ForceApplicationShutdown } Get-AppxPackage Microsoft.AccountsControl

Chybová zpráva MsalClientException: ErrorCode: wam_runtime_init_failed během nasazení jednoho souboru

Při balení aplikace do jedné sady souborů se může zobrazit následující chyba:

MsalClientException: wam_runtime_init_failed: The type initializer for 'Microsoft.Identity.Client.NativeInterop.API' threw an exception. See https://aka.ms/msal-net-wam#troubleshooting

Tato chyba značí, že nativní binární soubory z Microsoft.Identity.Client.NativeInterop nebyly zabaleny do jedné sady souborů. Chcete-li vložit tyto soubory pro extrakci a získat jeden výstupní soubor, nastavte vlastnost IncludeNativeLibrariesForSelfExtract na true. Přečtěte si další informace o tom, jak zabalit nativní binární soubory do jednoho souboru.

Problémy s připojením

Pokud se uživateli aplikace pravidelně zobrazuje chybová zpráva podobná "Zkontrolujte připojení a zkuste to znovu", přečtěte si průvodce odstraňováním potíží pro Office. Tento průvodce odstraňováním potíží používá také zprostředkovatele.

Vzorek

Ukázku WPF, která používá WAM , najdete na GitHubu.

Další kroky

Přejděte k dalšímu článku v tomto scénáři volání webového rozhraní API z desktopové aplikace.