Sdílet prostřednictvím

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

platí pro: zelený kruh s bílým zaškrtnutím. zaměstnanecké prostory bílý kruh s šedým X. externí nájemci (další informace)

Microsoft Authentication Library (MSAL) volá na Správce webových účtů (WAM), což je součást Windows 10 a novějších, 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 ve Windows, například účet, kterým jste se přihlásili do svého Windows účtu.

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. Na systémech Mac, Linux a starších verzích Windows se MSAL automaticky přepne na prohlížeč.
  • Autority Azure Active Directory B2C (Azure AD B2C) a Active Directory Federation Services (AD FS) nejsou podporovány. Knihovna MSAL přepne na použití 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 funkcionalita je součástí knihovny MSAL, když je cíleno na net6-windows nebo 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í přítomen (například, Windows 8.1, Mac nebo Linux), MSAL se přepne na prohlížeč, kde platí pravidla identifikátoru URI přesměrování.

URI pro přesměrování

V MSAL nemusíte konfigurovat přesměrovací URI WAM, ale v registraci aplikace je nakonfigurovat musíte.

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.

Identifikátory nadřazených oken

MSAL musíte nakonfigurovat s oknem, ke kterému má být interaktivní prostředí připojeno pomocí WithParentActivityOrWindow rozhraní API.

Aplikace uživatelského rozhraní

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

Konzolové aplikace

Pro konzolové aplikace je konfigurace složitější kvůli oknu terminálu a jeho kartám. 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 nenalezl žádný účet“

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

  1. Na hlavním panelu klikněte pravým tlačítkem na Start a pak vyberte Windows PowerShell (správce).

  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 při nasazování jednotlivého 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.