Web-Authentifizierungs-Broker

In diesem Artikel wird erläutert, wie Sie Ihre UWP-App (Universelle Windows-Plattform) mit einem Onlineidentitätsanbieter verbinden, der Authentifizierungsprotokolle wie OpenID oder OAuth verwendet. Die AuthenticateAsync Methode sendet eine Anforderung an den Onlineidentitätsanbieter und ruft ein Zugriffstoken zurück, das die Anbieterressourcen beschreibt, auf die die App Zugriff hat.

Hinweis

Um ein vollständiges, funktionierendes Codebeispiel zu erhalten, klonen Sie das WebAuthenticationBroker-Repository auf GitHub.

 

Registrieren Sie Ihre App bei Ihrem Onlineanbieter

Sie müssen Ihre App beim Onlineidentitätsanbieter registrieren, mit dem Sie eine Verbindung herstellen möchten. Erfahren Sie, wie Sie Ihre App beim Identitätsanbieter registrieren. Nach der Registrierung gibt Ihnen der Onlineanbieter in der Regel einen ID- oder geheimen Schlüssel für Ihre App.

Den URI für die Authentifizierungsanfrage erstellen

Der Anforderungs-URI besteht aus der Adresse, an die Sie die Authentifizierungsanfrage an Ihren Onlineanbieter senden, zusammen mit anderen erforderlichen Informationen, wie einer App-ID oder einem geheimen Schlüssel, einem Umleitungs-URI, an den der Benutzer nach Abschluss der Authentifizierung gesendet wird, und dem erwarteten Antworttyp. Sie können von Ihrem Anbieter herausfinden, welche Parameter erforderlich sind.

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

Das folgende Beispiel zeigt, wie der Anforderungs-URI erstellt wird.

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

Mit dem Onlineanbieter verbinden.

Sie rufen die AuthenticateAsync Methode auf, um eine Verbindung mit dem Onlineidentitätsanbieter herzustellen und ein Zugriffstoken abzurufen. 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. Es ist ab Windows Server 10 veraltet. Verwenden Sie stattdessen AuthenticateAsync.

Verbinden per Single Sign-on (SSO).

Standardmäßig lässt der Webauthentifizierungsbroker keine Speicherung von Cookies zu. Selbst wenn der App-Benutzer angibt, dass er angemeldet bleiben soll (z. B. durch Aktivieren eines Kontrollkästchens im Anmeldedialogfeld des Anbieters), muss er sich jedes Mal anmelden, wenn er auf Ressourcen für diesen Anbieter zugreifen möchte. 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 können beibehaltene Cookies vom Webauthentifizierungsbroker gespeichert werden, sodass zukünftige Authentifizierungsaufrufe von derselben App keine wiederholte Anmeldung durch den Benutzer erfordern (der Benutzer wird effektiv "angemeldet" bis zum Ablauf des Zugriffstokens).

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 indem Sie die Methode GetCurrentApplicationCallbackUri aufrufen.

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

Fehlersuche

Es gibt verschiedene Möglichkeiten zur Fehlerbehebung der Webauthentifizierungsbroker-APIs, darunter das Prüfen von Betriebsprotokollen und das Analysieren von Webanforderungen und -antworten mithilfe von Fiddler.

Betriebsprotokolle

Häufig können Sie ermitteln, was nicht funktioniert, indem Sie die Betriebsprotokolle verwenden. Es gibt einen dedizierten Ereignisprotokollkanal Microsoft-Windows-WebAuth\Operational, mit dem Websiteentwickler verstehen können, wie ihre Webseiten vom Webauthentifizierungsbroker 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 Webauthentifizierungsbroker eine eindeutige Zeichenfolge an die Benutzer-Agent-Zeichenfolge an, um sich selbst auf dem Webserver zu identifizieren. Die Zeichenfolge lautet MSAuthHost/1.0. Beachten Sie, dass sich die Versionsnummer in Zukunft ändern kann, daher sollten Sie nicht von dieser Versionsnummer in Ihrem Code abhängen. 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)

  1. Aktivieren Sie die Operational-Log-Dateien.
  2. Führen Sie die Contoso-Anwendung für soziale Netzwerke aus. Ereignisanzeige, die die Webauth-Betriebsprotokolle anzeigt
  3. Die generierten Protokolleinträge können verwendet werden, um das Verhalten des Webauthentifizierungsbrokers genauer zu verstehen. In diesem Fall können folgende Elemente enthalten sein:
    • Navigation Start: Protokolliert, wenn der AuthHost gestartet wird und Informationen über die Start- und End-URLs enthält.
    • veranschaulicht die Details des Navigationsstarts
    • Navigation Complete: Protokolliert den Abschluss des Ladens einer Webseite.
    • Metatag: Protokolliert, wann ein Metatag gefunden wird, einschließlich der Details.
    • Navigation Terminate: Die Navigation wurde vom Benutzenden abgebrochen.
    • Navigationsfehler: AuthHost stößt auf einen Navigationsfehler bei einer URL mit HttpStatusCode.
    • Navigation End: Beendende URL wird angetroffen.

Geiger

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

  1. Da AuthHost in einem eigenen App-Container ausgeführt wird und Sie ihm die Fähigkeit für ein privates Netzwerk geben müssen, sollten Sie einen Registrierungsschlüssel festlegen: Windows-Registrierungs-Editor, Version 5.00

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

    Wenn Sie nicht über diesen Registrierungsschlüssel verfügen, können Sie ihn in einer Eingabeaufforderung mit Administratorrechten erstellen.

    REG ADD "HKLM\Software\Microsoft\Windows NT\CurrentVersion\Image File Execution Options\authhost.exe" /v EnablePrivateNetwork /t REG_DWORD /d 1 /f
    
  2. 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
    
  3. Fügen Sie eine Firewallregel für eingehenden Datenverkehr zu Fiddler hinzu.

    Sie können die Firewallregel entweder über die Befehlszeile oder die Windows Defender Firewall-GUI erstellen:

    Option A: Verwendung des netsh-Befehls (als Administrator ausführen):

    netsh advfirewall firewall add rule name="Fiddler for AuthHost Debugging" dir=in action=allow program="C:\Program Files\Fiddler\Fiddler.exe" enable=yes
    

    Wenn Fiddler an einem anderen Speicherort installiert ist, passen Sie den Pfad entsprechend an. Alternativ können Sie eine portbasierte Regel erstellen:

    netsh advfirewall firewall add rule name="Fiddler Port for AuthHost" dir=in action=allow protocol=TCP localport=8888
    

    Option B: Verwenden der Windows Defender-Firewall mit erweiterter Sicherheit:

    1. Öffnen von Windows Defender Firewall mit erweiterter Sicherheit (wf.msc ausführen)
    2. Klicken Sie im linken Bereich auf "Eingehende Regeln".
    3. Klicken Sie auf "Neue Regel..." im rechten Bereich
    4. Wählen Sie "Programm" aus, und klicken Sie auf "Weiter".
    5. Navigieren Sie zur ausführbaren Datei von Fiddler (in der Regel C:\Program Files\Fiddler\Fiddler.exe in einer Installation pro Computer), und klicken Sie auf "Weiter".
    6. Wählen Sie "Verbindung zulassen" aus, und klicken Sie auf "Weiter".
    7. Überprüfen Sie alle Netzwerktypen (Domäne, Privat, Öffentlich) und klicken Sie auf "Weiter".
    8. Geben Sie der Regel einen Namen wie "Fiddler für AuthHost Debugging", und klicken Sie auf "Fertig stellen".