Web-APIs aufrufende Desktop-App – Abrufen eines Tokens mithilfe von WAM

Artikel
02/08/2024

Die Microsoft Authentication Library (MSAL) ruft den Web Account Manager (WAM) auf, eine Komponente von Windows 10+, die als Authentifizierungsbroker fungiert. Der Broker ermöglicht es den Benutzern Ihrer App, von der Integration mit Konten zu profitieren, die Windows bekannt sind, wie z. B. das Konto, mit dem Sie sich bei Ihrer Windows-Sitzung angemeldet haben.

WAM-Wertversprechen

Die Verwendung eines Authentifizierungsbrokers wie WAM hat zahlreiche Vorteile:

Erhöhte Sicherheit. Siehe Tokenschutz.
Unterstützung für Windows Hello, bedingten Zugriff und FIDO-Schlüssel.
Integration in die Ansicht E-Mail und Konten.
Schnelles einmaliges Anmelden.
Möglichkeit zur automatischen Anmeldung mit dem aktuellen Windows-Konto.
In Windows enthaltene Fehlerbehebungen und Verbesserungen.

WAM-Einschränkungen

WAM ist unter Windows 10 und höher sowie unter Windows Server 2019 und höher verfügbar. Unter Mac, Linux und früheren Windows-Versionen führt MSAL automatisch ein Fallback auf einen Browser durch.
Azure Active Directory B2C (Azure AD B2C) und Active Directory-Verbunddienste (AD FS)-Autoritäten werden nicht unterstützt. MSAL führt ein Fallback auf einen Browser durch.

WAM-Integrationspaket

Die meisten Apps müssen auf das Microsoft.Identity.Client.Broker-Paket verweisen, um diese Integration zu verwenden. .NET MAUI-Apps müssen dies nicht tun, da sich die Funktionalität innerhalb von MSAL befindet, wenn das Ziel net6-windows und höher ist.

WAM-Aufrufmuster

Sie können das folgende Muster für WAM verwenden:

    // 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                                  
    }

Wenn kein Broker vorhanden ist (z. B. Windows 8.1, Mac oder Linux), führt MSAL ein Fallback auf einen Browser durch, für den Umleitungs-URI-Regeln gelten.

Umleitungs-URI

Sie müssen WAM-Umleitungs-URIs in MSAL nicht konfigurieren, aber Sie müssen sie in der App-Registrierung konfigurieren:

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

Tokencachepersistenz

Es ist wichtig, den Tokencache von MSAL beizubehalten, da MSAL weiterhin ID-Token und Kontometadaten dort speichert. Weitere Informationen finden Sie unter Serialisierung des Tokencaches in MSAL.NET.

Um ein Konto für die automatische Anmeldung zu finden, empfehlen wir das folgende Muster:

Wenn sich Benutzer*innen zuvor angemeldet haben, verwenden Sie dieses Konto. Verwenden Sie andernfalls PublicClientApplication.OperatingSystemAccount für das aktuelle Windows-Konto.
Ermöglichen Sie Benutzern, zu einem anderen Konto zu wechseln, indem sie sich interaktiv anmelden.

Übergeordnete Fensterhandle

Sie müssen MSAL mithilfe von WithParentActivityOrWindow-APIs mit dem Fenster konfigurieren, das der interaktiven Benutzeroberfläche übergeordnet werden soll.

Benutzeroberflächenanwendungen

Informationen zu UI-Apps wie Windows Forms (WinForms), Windows Presentation Foundation (WPF) oder Windows UI Library Version 3 (WinUI3) finden Sie unter Abrufen eines Fensterhandles.

Konsolenanwendungen

Für Konsolenanwendungen ist die Konfiguration aufgrund des Terminalfensters und seiner Registerkarten etwas komplizierter. Verwenden Sie den folgenden Code:

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;
}

Problembehandlung

Fehlermeldung „WAM-Kontoauswahl hat kein Konto zurückgegeben.“

Die Meldung „Die WAM-Kontoauswahl hat kein Konto zurückgegeben“ gibt an, dass entweder die Anwendungsbenutzer*innen das Dialogfeld geschlossen haben, in dem Konten angezeigt werden, oder dass das Dialogfeld selbst abgestürzt ist. Es kann zu einem Absturz kommen, wenn das Windows-Steuerelement „AccountsControl“ unter Windows falsch registriert ist. Dieses Problem lässt sich wie folgt beheben:

Klicken Sie auf der Taskleiste mit der rechten Maustaste auf Start, und wählen Sie dann Windows PowerShell (Administrator) aus.
Wenn Sie in einem Dialogfeld zur Benutzerkontensteuerung aufgefordert werden, wählen Sie Ja aus, um PowerShell zu starten.

Kopieren Sie das folgende Skript, und führen Sie es aus:

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

Fehlermeldung „MsalClientException: ErrorCode: wam_runtime_init_failed“ während der Bereitstellung mit einer einzelnen Datei

Beim Packen Ihrer Anwendung in ein einzelnes Dateipaket wird möglicherweise der folgende Fehler angezeigt:

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

Diese Fehlermeldung gibt an, dass die nativen Binärdateien von Microsoft.Identity.Client.NativeInterop nicht in das einzelne Dateipaket gepackt wurden. Um diese Dateien für die Extrahierung einzubetten und eine Ausgabedatei zu erhalten, legen Sie die Eigenschaft IncludeNativeLibrariesForSelfExtract auf true fest. Erfahren Sie mehr darüber, wie Sie native Binärdateien in eine einzelne Datei packen.

Verbindungsprobleme

Wenn dem Anwendungsbenutzer regelmäßig eine Fehlermeldung wie „Bitte überprüfen Sie Ihre Verbindung, und versuchen Sie es erneut“ angezeigt wird, lesen Sie den Leitfaden zur Problembehandlung für Office. In diesem Leitfaden zur Problembehandlung wird auch der Broker verwendet.

Beispiel

Ein WPF-Beispiel, das WAM verwendet, finden Sie auf GitHub.

Nächste Schritte

Fahren Sie mit dem nächsten Artikel in diesem Szenario fort: Aufrufen einer Web-API von der Desktop-App.

Freigeben über