Webauthentifizierungsbroker

Artikel
03/15/2024

Dieser Artikel erklärt, wie Sie Ihre UWP-App (Universal Windows Platform) mit einem Online-Identitätsanbieter verbinden, der Authentifizierungsprotokolle wie OpenID oder OAuth verwendet. Die AuthenticateAsync-Methode sendet eine Anforderung an den Onlineidentitätsanbieter und erhält als Antwort ein Zugriffstoken, das die für die App zugänglichen Anbieterressourcen beschreibt.

Hinweis

Für ein vollständiges, funktionierendes Code-Beispiel klonen Sie das WebAuthenticationBroker-Repo auf GitHub.

Registrieren Sie Ihre App bei Ihrem Online-Anbieter

Sie müssen Ihre App bei dem Online-Identitätsanbieter registrieren, mit dem Sie sich verbinden möchten. Wie Sie Ihre App registrieren können, erfahren Sie vom Identitätsanbieter. Nach der Registrierung erhalten Sie vom Online-Anbieter in der Regel eine ID oder einen geheimen Schlüssel für Ihre App.

Erstellen des URI der Authentifikationsanforderung

Der Anforderungs-URI besteht aus der Adresse, an die Sie die Authentifizierungsanfrage an Ihren Online-Anbieter senden, ergänzt um andere erforderliche Informationen, wie eine App-ID oder ein Secret, ein Umleitungs-URI, an die Benutzende nach Abschluss der Authentifizierung weitergeleitet werden, und den erwarteten Antworttyp. Welche Parameter erforderlich sind, erfahren Sie von Ihrem Anbieter.

Der Anfrage-URI wird als requestUri-Parameter der AuthenticateAsync-Methode gesendet. Es muss eine sichere Adresse sein (sie muss mit https:// beginnen).

Das folgende Beispiel zeigt, wie Sie den Anforderungs-URI erstellen.

string startURL = "https://<providerendpoint>?client_id=<clientid>&scope=<scopes>&response_type=token";
string endURL = "http://<appendpoint>";

System.Uri startURI = new System.Uri(startURL);
System.Uri endURI = new System.Uri(endURL);

Verbinden mit dem Online-Anbieter

Sie rufen die Methode AuthenticateAsync auf, um sich mit dem Online-Identitätsanbieter zu verbinden und ein Token für den Zugriff zu erhalten. Die Methode nimmt den im vorherigen Schritt erstellten URI als requestUri-Parameter und einen URI, zu dem der/die Benutzende umgeleitet werden soll, als callbackUri-Parameter entgegen.

string result;

try
{
    var webAuthenticationResult = 
        await Windows.Security.Authentication.Web.WebAuthenticationBroker.AuthenticateAsync( 
        Windows.Security.Authentication.Web.WebAuthenticationOptions.None, 
        startURI, 
        endURI);

    switch (webAuthenticationResult.ResponseStatus)
    {
        case Windows.Security.Authentication.Web.WebAuthenticationStatus.Success:
            // Successful authentication. 
            result = webAuthenticationResult.ResponseData.ToString(); 
            break;
        case Windows.Security.Authentication.Web.WebAuthenticationStatus.ErrorHttp:
            // HTTP error. 
            result = webAuthenticationResult.ResponseErrorDetail.ToString(); 
            break;
        default:
            // Other error.
            result = webAuthenticationResult.ResponseData.ToString(); 
            break;
    } 
}
catch (Exception ex)
{
    // Authentication failed. Handle parameter, SSL/TLS, and Network Unavailable errors here. 
    result = ex.Message;
}

Warnung

Zusätzlich zu AuthenticateAsync enthält der Windows.Security.Authentication.Web-Namespace eine AuthenticateAndContinue-Methode. Rufen Sie diese Methode nicht auf. Sie ist nur für Apps gedacht, die für Windows Phone 8.1 bestimmt sind, und ist ab Windows 10 veraltet.

Verbinden per Single Sign-on (SSO).

Standardmäßig lässt der Web-Authentifizierungs-Broker keine dauerhaften Cookies zu. Selbst wenn Benutzende einer App angeben, dass sie angemeldet bleiben möchten (z. B. durch Aktivieren eines Kontrollkästchens im Anmeldedialog des Anbieters), müssen sie sich daher jedes Mal neu anmelden, wenn sie auf Ressourcen dieses Anbieters zugreifen möchten. Um sich mit SSO anzumelden, muss Ihr Online-Identitätsanbieter SSO für den Web-Authentication-Broker aktiviert haben, und Ihre App muss die Überladung von AuthenticateAsync aufrufen, die keinen callbackUri-Parameter benötigt. Dadurch wird zugelassen, dass der Web-Authentifizierungs-Broker persistente Cookies speichert, sodass künftige Authentifizierungsaufrufe derselben App keine wiederholte Anmeldung des/der Benutzenden erfordern (der/die Benutzer*in ist effektiv „angemeldet“, bis das Token für den Zugriff abläuft).

Um SSO zu unterstützen, muss der Online-Anbieter Ihnen die Möglichkeit bieten, einen Umleitungs-URI in dem Formular ms-app://<appSID> zu registrieren, wobei <appSID> die SID für Ihre App ist. Sie finden die SID Ihrer App auf der App-Entwicklerseite für Ihre App oder durch Aufruf der Methode GetCurrentApplicationCallbackUri.

string result;

try
{
    var webAuthenticationResult = 
        await Windows.Security.Authentication.Web.WebAuthenticationBroker.AuthenticateAsync( 
        Windows.Security.Authentication.Web.WebAuthenticationOptions.None, 
        startURI);

    switch (webAuthenticationResult.ResponseStatus)
    {
        case Windows.Security.Authentication.Web.WebAuthenticationStatus.Success:
            // Successful authentication. 
            result = webAuthenticationResult.ResponseData.ToString(); 
            break;
        case Windows.Security.Authentication.Web.WebAuthenticationStatus.ErrorHttp:
            // HTTP error. 
            result = webAuthenticationResult.ResponseErrorDetail.ToString(); 
            break;
        default:
            // Other error.
            result = webAuthenticationResult.ResponseData.ToString(); 
            break;
    } 
}
catch (Exception ex)
{
    // Authentication failed. Handle parameter, SSL/TLS, and Network Unavailable errors here. 
    result = ex.Message;
}

Debuggen

Es gibt mehrere Möglichkeiten zur Fehlerbehebung bei den Web-Authentifizierungs-Broker-APIs, einschließlich der Überprüfung von Operational-Log-Dateien und der Überprüfung von Web-Anforderungen und -Antworten mit Fiddler.

Betriebsprotokolle

Oft können Sie anhand der Operational-Log-Dateien feststellen, was nicht funktioniert. Es gibt einen speziellen Ereignis-Log-Kanal Microsoft-Windows-WebAuth\Operational, der Website-Entwickler*innen die Möglichkeit bietet, zu verstehen, wie ihre Webseiten vom Web-Authentifizierungs-Broker verarbeitet werden. Um ihn zu aktivieren, starten Sie eventvwr.exe und aktivieren Sie die Log-Datei Operational unter Anwendung und Dienste\Microsoft\Windows\WebAuth. Außerdem fügt der Web-Authentifizierungs-Broker eine eindeutige Zeichenfolge an die Zeichenfolge des User-Agents an, um sich auf dem Webserver zu identifizieren. Die Zeichenfolge lautet MSAuthHost/1.0. Beachten Sie, dass sich die Versionsnummer in Zukunft ändern kann. Sie sollten sich also in Ihrem Code nicht auf diese Versionsnummer verlassen. Ein Beispiel für die vollständige Zeichenfolge des User-Agents, gefolgt von den vollständigen Debugging-Schritten, lautet wie folgt.

User-Agent: Mozilla/5.0 (compatible; MSIE 10.0; Windows NT 6.2; Win64; x64; Trident/6.0; MSAuthHost/1.0)

Aktivieren Sie die Operational-Log-Dateien.
Führen Sie die Social-Anwendung von Contoso aus.
Anhand der generierten Log-Dateien können Sie das Verhalten des Web-Authentifizierungs-Brokers im Detail nachvollziehen. In diesem Fall können diese Folgendes enthalten:
- Navigation Start: Protokolliert, wenn der AuthHost gestartet wird und Informationen über die Start- und End-URLs enthält.
- Navigation Complete: Protokolliert den Abschluss des Ladens einer Webseite.
- Meta Tag: Protokolliert, wenn ein Meta-Tag angetroffen wird, einschließlich der Details.
- Navigation Terminate: Die Navigation wurde vom Benutzenden abgebrochen.
- Navigation Error: AuthHost stößt auf einen Navigationsfehler bei einer URL einschließlich HttpStatusCode.
- Navigation End: Beendende URL wird angetroffen.

Fiddler

Der Fiddler-Web-Debugger kann mit Apps verwendet werden. Weitere Informationen finden Sie in der Fiddler-Dokumentation

Da der AuthHost in einem eigenen App-Container ausgeführt wird, müssen Sie einen Registrierungsschlüssel festlegen, um ihm die Funktionalitäten des privaten Netzwerks einzuräumen: Windows-Registrierungseditor Version 5.00

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Image File Execution Options\authhost.exe\EnablePrivateNetwork = 00000001

Ohne diesen Registrierungsschlüssel können Sie ihn in einer Eingabeaufforderung mit Administrator*innen-Rechten erstellen.
```
REG ADD "HKLM\Software\Microsoft\Windows NT\CurrentVersion\Image File Execution Options\authhost.exe" /v EnablePrivateNetwork /t REG_DWORD /d 1 /f
```

Fügen Sie eine Regel für den AuthHost hinzu, da dieser den ausgehenden Datenverkehr erzeugt.

CheckNetIsolation.exe LoopbackExempt -a -n=microsoft.windows.authhost.a.p_8wekyb3d8bbwe
CheckNetIsolation.exe LoopbackExempt -a -n=microsoft.windows.authhost.sso.p_8wekyb3d8bbwe
CheckNetIsolation.exe LoopbackExempt -a -n=microsoft.windows.authhost.sso.c_8wekyb3d8bbwe
D:\Windows\System32>CheckNetIsolation.exe LoopbackExempt -s
List Loopback Exempted AppContainers
[1] -----------------------------------------------------------------
    Name: microsoft.windows.authhost.sso.c_8wekyb3d8bbwe
    SID:  S-1-15-2-1973105767-3975693666-32999980-3747492175-1074076486-3102532000-500629349
[2] -----------------------------------------------------------------
    Name: microsoft.windows.authhost.sso.p_8wekyb3d8bbwe
    SID:  S-1-15-2-166260-4150837609-3669066492-3071230600-3743290616-3683681078-2492089544
[3] -----------------------------------------------------------------
    Name: microsoft.windows.authhost.a.p_8wekyb3d8bbwe
    SID:  S-1-15-2-3506084497-1208594716-3384433646-2514033508-1838198150-1980605558-3480344935

Fügen Sie eine Firewall-Regel für den eingehenden Datenverkehr zu Fiddler hinzu.

Freigeben über