Verwenden von MSAL.NET mit Web Account Manager (WAM)

MSAL kann Web Account Manager (WAM) aufrufen, eine Windows Komponente, die mit dem Betriebssystem ausgeliefert wird. Diese Komponente fungiert als Authentifizierungsbroker, der es den Benutzern Ihrer App ermöglicht, von der Integration mit Konten zu profitieren, die Windows bekannt sind, z. B. das Konto, das Sie bei Ihrer Windows Sitzung angemeldet haben.

Was ist ein Broker?

Ein Authentifizierungsbroker ist eine Anwendung, die auf dem Computer eines Benutzers ausgeführt wird, der die Authentifizierungs-Handshakes und die Tokenwartung für verbundene Konten verwaltet. Das Windows-Betriebssystem verwendet den Web Account Manager (WAM) als Authentifizierungsbroker. Es bietet entwicklern und Kunden viele Vorteile, darunter:

• Verbesserte Sicherheit. Viele Sicherheitsverbesserungen werden mit dem Broker bereitgestellt, ohne die Anwendungslogik aktualisieren zu müssen.
• Unterstützte Funktionen Mit Hilfe des Brokers können Entwickler auf umfangreiche Betriebssystem- und Dienstfunktionen wie Windows Hello, Richtlinien für bedingten Zugriff und FIDO-Schlüssel zugreifen, ohne zusätzlichen Gerüstcode zu schreiben.
• Systemintegration. Anwendungen, die das Broker-Plug-and-Play mit der integrierten Kontoauswahl verwenden, sodass der Benutzer schnell ein vorhandenes Konto auswählen kann, anstatt die gleichen Anmeldeinformationen immer wieder einzugeben.
• Tokenschutz. WAM stellt sicher, dass die Aktualisierungstoken gerätegebunden sind und apps das Abrufen von gerätegebundenen Zugriffstoken ermöglichen. Siehe Tokenschutz.

Aktivieren von WAM

DIE WAM-Unterstützung ist auf zwei Pakete aufgeteilt:

• Microsoft. Identity.Client (d. h. MSAL) – Kernbibliothek für die Tokenerfassung.
• Microsoft. Identity.Client.Broker – fügt Unterstützung für die Authentifizierung mit dem Broker hinzu.

Rufen Sie WithBroker(BrokerOptions) nach dem Verweisen auf die relevanten Pakete mit Brokerkonfigurationsoptionen und einem Fensterhandle auf, an das der Broker gebunden wird.

var scopes = new[] { "User.Read" };

BrokerOptions options = new BrokerOptions(BrokerOptions.OperatingSystems.Windows);
options.Title = "My Awesome Application";

IPublicClientApplication app =
    PublicClientApplicationBuilder.Create("YOUR_CLIENT_ID")
    .WithDefaultRedirectUri()
    .WithParentActivityOrWindow(GetConsoleOrTerminalWindow)
    .WithBroker(options)
    .Build();

AuthenticationResult result = null;

// Try to use the previously signed-in account from the cache
IEnumerable<IAccount> accounts = await app.GetAccountsAsync();
IAccount existingAccount = accounts.FirstOrDefault();

try
{    
    if (existingAccount != null)
    {
        result = await app.AcquireTokenSilent(scopes, existingAccount).ExecuteAsync();
    }
    // Next, try to sign in silently with the account that the user is signed into Windows
    else
    {    
        result = await app.AcquireTokenSilent(scopes, PublicClientApplication.OperatingSystemAccount)
                            .ExecuteAsync();
    }
}
// Can't get a token silently, go interactive
catch (MsalUiRequiredException ex)
{
    result = await app.AcquireTokenInteractive(scopes).ExecuteAsync();
}

Bei Verwendung des Brokers wird der Benutzer zuerst aufgefordert, ein Konto mithilfe der integrierten Systemkontoauswahl auszuwählen, wenn die verwendete Autorität auf Microsoft Entra ID sowie persönliche Microsoft-Konten ausgerichtet ist.

Wenn die Konfiguration mithilfe von WithTenantId pro Mandant festgelegt wird oder wenn die Autorität auf eine Zielgruppe festgelegt ist, die keine persönlichen Microsoft-Konten einschließt, wird die native Windows-Kontoauswahl nicht angezeigt; stattdessen wird dem Benutzer eine allgemeine Microsoft-Authentifizierungsaufforderung angezeigt.

Nachdem das Konto hinzugefügt oder ausgewählt wurde, wird der Benutzer zur zusätzlichen Zustimmung aufgefordert, wenn er die Anwendung noch nie verwendet hat oder die Anwendung zusätzliche Berechtigungen benötigt.

Übergeordnete Fensterhandle

Um den Broker zu verwenden, muss jetzt das Fensterhandle angegeben werden, dem das modale WAM-Dialogfeld mithilfe von WithParentActivityOrWindow-APIs untergeordnet wird. Das Fensterhandle muss vom Entwickler bereitgestellt werden, da es für MSAL selbst nicht möglich ist, das übergeordnete Fenster abzuleiten, und in der Vergangenheit hat dies zu schlechten Benutzeroberflächen geführt, bei denen das Authentifizierungsfenster hinter dem Anwendungsfenster verborgen war.

Weitere Informationen zu UI-Apps, z. B. solchen, die Windows Forms, Windows Presentation Foundation (WPF) oder WinUI 3 verwenden, finden Sie unter Fensterhandle (HWND) abrufen.

Für Konsolenanwendungen können Sie Code wie den folgenden Codeausschnitt verwenden.

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

Zugriffstoken für den Nachweis des Besitzes

Der WAM-Broker ermöglicht den Erwerb von PoP-Token für öffentliche Clientflüsse. Weitere Details finden Sie unter Proof-of-Possession-Token .

Umleitungs-URI

WAM-Umleitungs-URIs müssen nicht in MSAL konfiguriert werden, müssen aber in der App-Registrierung konfiguriert werden. Sie sollten dem folgenden Muster folgen:

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

Benutzername/Kennwortfluss

Dieser Fluss, auch als RoPC (Resource Owner Password Credentials) bezeichnet, wird nicht empfohlen, außer in Testszenarien oder in Szenarien, in denen der Dienstprinzipalzugriff auf eine Ressource zu viel Zugriff gewährt, und Sie können ihn nur mit Benutzerflüssen einschränken. Bei Verwendung von WAM lässt AcquireTokenByUsernamePassword WAM das Protokoll verwalten und Token abrufen.

WAM-Einschränkungen

• Azure B2C- und Active Directory-Verbunddienste (AD FS) (ADFS)-Autoritäten werden nicht unterstützt. MSAL wird auf die Verwendung eines Browsers für die Benutzerauthentifizierung zurückgreifen.
• Unter Mac, Linux und Versionen von Windows vor 10 oder Windows Server 2019 fällt MSAL auf einen Browser zurück.

Paketverfügbarkeit

Um den Broker zu verwenden, müssen Entwickler WithBroker(PublicClientApplicationBuilder, BrokerOptions) aufrufen, das im Paket Microsoft.Identity.Client.Broker gehostet wird. Die meisten .NET Plattformvarianten, die von MSAL.NET unterstützt werden, benötigen dieses Paket nur mit wenigen Ausnahmen. Eine detaillierte Zuordnung finden Sie in der nachstehenden Tabelle.

†Microsoft.Identity.Client Versionen 4.61.0 und höher enthalten net6.0-windows7.0 keine Binärdateien mehr. Vorhandene Desktopanwendungen, die auf net6.0-windows abzielen, sollten bei Verwendung der interaktiven Authentifizierung mit Windows Broker auf Microsoft.Identity.Client.Broker verweisen und WithBroker(PublicClientApplicationBuilder, BrokerOptions) aufrufen; oder auf Microsoft.Identity.Client.Desktop verweisen, wenn sie sich mit dem Browser authentifizieren, und WithWindowsEmbeddedBrowserSupport(PublicClientApplicationBuilder) aufrufen.

Bewährte Methoden für die Integration

Um sicherzustellen, dass Ihre Kunden eine großartige Erfahrung mit WAM haben, empfehlen wir Ihnen dringend, die folgenden Prinzipien einzuhalten:

1. Geben Sie dem Benutzer vor der Authentifizierung Kontext. Zeichnen Sie eine Benutzeroberfläche oder ein Fenster, die den Benutzer darüber informiert, dass er sich authentifizieren muss, zusammen mit Gründen für die Authentifizierung. Erläutern Sie die Vorteile Ihrer Anwendung, wenn es sich um einen Hintergrunddienst handelt.
2. Rufen Sie die Authentifizierung basierend auf der Benutzeraktion auf. Der Benutzer sollte sich bewusst sein, dass er den Authentifizierungsprozess in einer bestimmten Anwendung ausgelöst hat, indem er auf einen Link oder eine Schaltfläche klickt oder eine andere Geste ausführt. Benutzer sollten keine Anmeldeinformationen in Fenstern eingeben, die im Betriebssystem ohne angefügten Kontext oder Aktionen angezeigt werden.
3. Versuchen Sie zunächst, das Token still abzurufen, und greifen Sie auf eine interaktive Eingabeaufforderung zurück, wenn dies fehlschlägt. Kunden sollten nur zur interaktiven Authentifizierung aufgefordert werden, wenn eine explizite Notwendigkeit besteht, Anmeldeinformationen erneut einzugeben oder eine Richtlinienanforderung zu erfüllen.

Troubleshooting

„MsalClientException (ErrCode 5376): Mindestens ein Scope muss für diesen Authentifizierungsablauf angefordert werden.“ Fehlermeldung

Diese Meldung gibt an, dass Sie mindestens einen Anwendungsbereich (z. B. user.read) zusammen mit anderen OIDC-Bereichen (profileemailoder offline_access) anfordern müssen.

var authResult = await pca.AcquireTokenInteractive(new[] { "user.read" })
                 .ExecuteAsync();

Die Kontoauswahl wird nicht angezeigt.

Manchmal kann sich ein Windows Update unbeabsichtigt auf die Kontoauswahlkomponente auswirken, die die Liste der Konten in Windows und die Option zum Hinzufügen neuer Konten anzeigt. Das Problem besteht darin, dass der Auswahldialog bei einer kleinen Anzahl von Benutzern nicht angezeigt wird.

Eine mögliche Problemumgehung besteht darin, die Komponente erneut zu registrieren. Führen Sie dieses Skript über das Terminal mit Administratorberechtigungen aus:

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

Get-AppxPackage Microsoft.AccountsControl

Verbindungsprobleme

Der Anwendungsbenutzer sieht eine Fehlermeldung ähnlich wie Please check your connection and try again. Wenn dieses Problem regelmäßig auftritt, lesen Sie das Handbuch zur Problembehandlung für Office, das auch WAM verwendet.

WAM-Fehlercodes

Details zu WAM-Fehlern finden Sie unter "Fehler im Zusammenhang mit Web Account Manager(WAM )".

Da WAM eine relativ neue Komponente ist, empfehlen wir, beim Auftreten von Fehlern Daten von AdditionalExceptionData zu protokollieren. Dies kann dabei helfen, bestimmte Probleme mit der Konfiguration oder der WAM-Komponente zu bestimmen. Wenn bei Ihnen Probleme mit WAM auftreten, melden Sie bitte einen Fehler – so können wir sicherstellen, dass wir uns zeitnah um das Problem kümmern.