Verwenden von Webbrowsern (MSAL.NET)

Wir empfehlen die Verwendung von Brokern zur Authentifizierung, da sie im Vergleich zu den Browsern mehr Vorteile bieten. Auf Windows-Computern ist der Broker Web Account Manager (WAM), unter Android und iOS ist der Broker Microsoft Authenticator oder Intune Unternehmensportal. Für die interaktive Authentifizierung ist die Verwendung eines Brokers oder eines Webbrowsers erforderlich. MSAL.NET unterstützt einen Systemwebbrowser oder eine eingebettete Webansicht.

Webbrowser in MSAL.NET

Interaktion erfolgt in einem Webbrowser

Es ist wichtig zu verstehen, dass beim interaktiven Abrufen eines Tokens der Inhalt des Dialogfelds nicht von der Bibliothek, sondern von Microsoft Entra ID bereitgestellt wird. Der Authentifizierungsendpunkt sendet HTML und JavaScript zurück, das die Interaktion steuert, die in einem Webbrowser oder einem Websteuerelement gerendert wird. Das Zulassen der Microsoft Entra ID zur Behandlung der HTML-Interaktion hat viele Vorteile:

• Das Kennwort, wenn ein Kennwort eingegeben wurde, wird nie von der Anwendung oder der Authentifizierungsbibliothek gespeichert.
• Sie ermöglicht die Umleitung an andere Identitätsanbieter (z. B. Anmeldung mit einem Geschäfts-, Schul- oder Unikonto oder ein persönliches Konto mit MSAL oder mit einem sozialen Konto mit Azure AD B2C).
• Dadurch kann Microsoft Entra ID den Bedingten Zugriff steuern, z. B. indem der Benutzer während der Authentifizierungsphase eine Multi-Faktor-Authentifizierung (MFA) durchführt (wie etwa durch Eingeben einer Windows Hello-PIN oder indem er auf seinem Telefon oder über eine Authentifizierungs-App auf seinem Telefon angerufen wird). In Fällen, in denen die erforderliche mehrstufige Authentifizierung noch nicht eingerichtet ist, kann der Benutzer sie im selben Dialogfeld einrichten. Der Benutzer gibt seine Mobiltelefonnummer ein und wird geführt, um eine Authentifizierungsanwendung zu installieren und ein QR-Tag zu scannen, um sein Konto hinzuzufügen. Diese servergesteuerte Interaktion ist eine großartige Erfahrung!
• Er ermöglicht es dem Benutzer, sein Kennwort in diesem Dialogfeld zu ändern, wenn das Kennwort abgelaufen ist (zusätzliche Felder für das alte Kennwort und das neue Kennwort).
• Dies ermöglicht das Branding des Mandanten oder der Anwendung (Bilder), das vom Microsoft Entra-Mandantenadministrator oder einem Anwendungsbesitzer verwaltet wird.
• Sie ermöglicht es den Benutzern, zuzustimmen, dass die Anwendung direkt nach der Authentifizierung auf Ressourcen und Bereiche in ihrem Namen zugreifen kann.

Eingebettete Webansicht im Vergleich zum Systembrowser

MSAL.NET ist eine Bibliothek mit mehreren Frameworks und verfügt über frameworkspezifischen Code zum Hosten eines Browsers in einem Benutzeroberflächensteuerelement (z. B. für .NET WinForms oder WebView2; für .NET MAUI, systemeigene mobile Steuerelemente usw.). Dieses Steuerelement wird als eingebettete Webansicht bezeichnet. Alternativ kann MSAL.NET auch einen Systemwebbrowser öffnen.

Im Allgemeinen wird empfohlen, die Plattformstandardeinstellung zu verwenden, und dies ist in der Regel der Systembrowser. Der Systembrowser ist besser, sich an die Benutzer zu erinnern, die sich zuvor angemeldet haben. Um dieses Verhalten zu ändern, verwenden Sie WithUseEmbeddedWebView(Boolean)

Browserverfügbarkeit

† Systembrowser erfordert http://localhost Umleitungs-URI.

†† Ziel net6.0-windows oder höher, um den eingebetteten Browser zu verwenden.

††† Verweisen Sie auf Microsoft.Identity.Client.Desktop und rufen Sie WithWindowsDesktopFeatures auf, um den eingebetteten Browser zu verwenden.

Systemwebbrowser

Die Verwendung des Systembrowsers hat den erheblichen Vorteil, den Single Sign-On (SSO)-Zustand mit Webanwendungen und anderen Anwendungen zu teilen, ohne einen Broker (WAM, Unternehmensportal, Authenticator usw.) zu benötigen.

Bei Desktopanwendungen führt das Starten eines Systembrowsers jedoch zu einer untergeordneten Benutzererfahrung, da der Benutzer den Browser sieht, wo er möglicherweise bereits andere Registerkarten geöffnet hat. Und wenn die Authentifizierung erfolgt ist, erhalten die Benutzer eine Seite, auf der sie aufgefordert werden, dieses Fenster zu schließen. Wenn der Benutzer nicht aufpasst, kann der gesamte Prozess geschlossen werden (einschließlich anderer Registerkarten, die nichts mit der Authentifizierung zu tun haben). Die Nutzung des Systembrowsers auf dem Desktop erfordert auch das Öffnen lokaler Ports und das Überwachen dieser Ports, was möglicherweise erweiterte Berechtigungen für die Anwendung erfordert. Sie könnten als Entwickler, Benutzer oder Administrator Bedenken gegenüber dieser Anforderung haben.

Verwenden des Standardsystembrowsers

Auf .NET startet MSAL den Systembrowser als separaten Prozess. MSAL.NET hat keine Kontrolle über diesen Browser, aber sobald der Benutzer die Authentifizierung abgeschlossen hat, wird die Webseite so umgeleitet, dass MSAL.NET den Aufruf an den Umleitungs-URI abfangen kann, der beim Erstellen einer öffentlichen Clientinstanz angegeben wurde.

MSAL.NET können nicht erkennen, ob der Benutzer weg navigiert oder einfach den Browser schließt. Apps, die diese Technik verwenden, sollten ein Timeout mit CancellationToken definieren. Es wird empfohlen, ein Timeout von mindestens ein paar Minuten zu berücksichtigen, um Fälle zu berücksichtigen, in denen der Benutzer aufgefordert wird, das Kennwort zu ändern oder eine mehrstufige Authentifizierung durchzuführen.

MSAL.NET muss auf http://localhost:port lauschen, um den Code abzufangen, den Microsoft Entra ID zurückgibt, wenn der Benutzer die Anmeldung abgeschlossen hat. Details finden Sie unter Autorisierungscodefluss .

So aktivieren Sie den Systembrowser:

1. Konfigurieren Sie http://localhost während der App-Registrierung im Portal als Umleitungs-URI (derzeit nicht von Azure B2C unterstützt).
2. Wenn Sie Ihre öffentliche Client-App erstellen, geben Sie diesen Umleitungs-URI an.
3. Fügen Sie .WithUseEmbeddedWebView(false)hinzu.

var pca = PublicClientApplicationBuilder
            .Create("<CLIENT_ID>")
            // or use a known port if you wish "http://localhost:1234"
            .WithRedirectUri("http://localhost")
            .Build();

var result = await pca.AcquireTokenInteractive(s_scopes)
                    .WithUseEmbeddedWebView(false)
                    .ExecuteAsync();

Wenn Sie konfigurierenhttp://localhost, findet MSAL.NET einen zufällig geöffneten Port und verwendet ihn. Die Verwendung http://localhost als Umleitungs-URI ist sicher. Ein anderer Prozess kann nicht auf einen lokalen Socket lauschen, der bereits von MSAL überwacht wird. Es erfolgt keine Netzwerkkommunikation, wenn der Browser zu diesem URI umleitet. Selbst wenn eine schädliche App den Authentifizierungscode abfangen (keine solchen bekannten Angriffe, aber es ist möglich, wenn eine schädliche App Administratorzugriff auf den Computer hat), kann sie nicht für ein Token ausgetauscht werden, da es einen temporären Geheimschlüssel benötigt, den nur Ihre App kennt, wie im PKCE-Protokoll beschrieben. Die App kann nicht auf den HTTPS-Localhost-Endpunkt (https://localhost) lauschen, da Port 443 reserviert ist und MSAL nicht darauf lauschen kann.

Einschränkungen

Azure B2C und ADFS 2019 implementieren noch keine Portoption. Sie können also keinen http://localhost-Umleitungs-URI (ohne Port) festlegen, sondern nur einen http://localhost:1234-URI (mit Port). Dies bedeutet, dass Sie ihre eigene Portverwaltung durchführen müssen, z. B. können Sie einige Ports reservieren und als Umleitungs-URIs konfigurieren. Dann kann Ihre App sie durchlaufen, bis ein Port kostenlos ist – dies kann dann von MSAL verwendet werden.

Weitere Informationen finden Sie unter Localhost-Ausnahmen.

Linux und macOS

Unter Linux öffnet MSAL.NET den Standardsystembrowser mit einem Tool wie xdg-open. Das Öffnen des Browsers mit sudo wird von MSAL nicht unterstützt und führt dazu, dass MSAL eine Ausnahme auslöst.

Unter macOS wird der Browser durch Aufrufen open <url>geöffnet.

Anpassen der Benutzeroberfläche

MSAL.NET können mit einer HTTP-Nachricht oder einer HTTP-Umleitung reagieren, wenn ein Token empfangen wird oder ein Fehler auftritt.

var options = new SystemWebViewOptions()
{
    HtmlMessageError = "<p> An error occurred: {0}. Details {1}</p>",
    BrowserRedirectSuccess = new Uri("https://www.microsoft.com");
}

await pca.AcquireTokenInteractive(s_scopes)
         .WithUseEmbeddedWebView(false)
         .WithSystemWebViewOptions(options)
         .ExecuteAsync();

Öffnen eines bestimmten Browsers

Sie können die Art und Weise anpassen, wie MSAL.NET den Browser öffnet. Anstatt beispielsweise den Standardbrowser zu verwenden, können Sie das Öffnen eines bestimmten Browsers erzwingen:

var options = new SystemWebViewOptions()
{
    OpenBrowserAsync = SystemWebViewOptions.OpenWithEdgeBrowserAsync
}

Webansichten in mobilen Anwendungen

Eingebettete Webansichten können in .NET MAUI Anwendungen aktiviert werden. Sie können entweder eingebettete Webansichten oder Systembrowser verwenden. Dies ist Ihre Wahl je nach Benutzerfreundlichkeit und Sicherheitsbedenken, die Sie als Ziel festlegen möchten.

Unterschiede zwischen eingebetteter Webansicht und Systembrowser

Es gibt einige visuelle Unterschiede zwischen der eingebetteten Webansicht und dem Systembrowser in MSAL.NET.

Interaktive Anmeldung mit MSAL.NET mithilfe der eingebetteten Webansicht:

Interaktive Anmeldung mit MSAL.NET über den Systembrowser:

Entwickleroptionen

Als Entwickler mit MSAL.NET haben Sie mehrere Optionen zum Anzeigen des interaktiven Anmeldedialogfelds aus Microsoft Entra ID:

• Systembrowser. Der Systembrowser wird standardmäßig in der Bibliothek festgelegt. Wenn Sie Android verwenden, finden Sie unter Systembrowser spezifische Informationen dazu, welche Browser für die Authentifizierung unterstützt werden. Wenn Sie den Systembrowser unter Android verwenden, empfehlen wir, dass auf dem Gerät ein Browser installiert ist, der Chrome Custom Tabs unterstützt; andernfalls kann die Authentifizierung fehlschlagen.
• Eingebettete Webansicht. Um nur die eingebettete Webansicht in MSAL.NET zu verwenden, enthält der AcquireTokenInteractive Generator eine WithUseEmbeddedWebView Methode.

In einer iOS-App:

var result = app.AcquireTokenInteractive(scopes)
                .WithUseEmbeddedWebView(useEmbeddedWebview)
                .ExecuteAsync();

In einer Android-App:

var result = app.AcquireTokenInteractive(scopes)
                .WithParentActivityOrWindow(activity)
                .WithUseEmbeddedWebView(useEmbeddedWebview)
                .ExecuteAsync();

Auswählen zwischen eingebetteter Webansicht oder Systembrowser unter iOS

In Ihrer iOS-App können Sie in AppDelegate.cs die ParentWindow auf null initialisieren. Es wird nicht in iOS verwendet.

App.ParentWindow = null; // no UI parent on iOS

Auswählen zwischen eingebetteter Webansicht oder Systembrowser unter Android

In Ihrer Android-App können Sie in MainActivity.cs die übergeordnete Aktivität so festlegen, dass das Authentifizierungsergebnis an diese zurückgegeben wird:

 App.ParentWindow = this;

Dann im MainPage.xaml.cs:

var result = await App.PCA.AcquireTokenInteractive(App.Scopes)
                      .WithParentActivityOrWindow(App.ParentWindow)
                      .WithUseEmbeddedWebView(true)
                      .ExecuteAsync();

Erkennen von Custom Tabs auf Android

Wenn Sie den System-Webbrowser verwenden möchten, um Single Sign-On mit den Apps zu aktivieren, die im Browser ausgeführt werden, sich aber Sorgen um die Benutzerfreundlichkeit auf Android-Geräten machen, die keinen Browser mit Unterstützung für benutzerdefinierte Tabs haben, können Sie dies durch Aufrufen von IPublicClientApplication.IsSystemWebViewAvailable festlegen. Diese Methode gibt true zurück, wenn der Android-Paketmanager benutzerdefinierte Tabs auf dem Gerät erkennt, und false, wenn sie auf dem Gerät nicht erkannt werden.

Basierend auf dem von dieser Methode zurückgegebenen Wert und Ihren Anforderungen können Sie eine Entscheidung treffen:

• Sie können eine benutzerdefinierte Fehlermeldung an den Benutzer zurückgeben, z. B. "Bitte installieren Sie Chrome, um mit der Authentifizierung fortzufahren", oder
• Sie können zurückkehren, um die Anmeldeseite in einer eingebetteten Webansicht zu starten.

bool useSystemBrowser = app.IsSystemWebViewAvailable();

authResult = await App.PCA.AcquireTokenInteractive(App.Scopes)
                      .WithParentActivityOrWindow(App.ParentWindow)
                      .WithUseEmbeddedWebView(!useSystemBrowser)
                      .ExecuteAsync();