Broker uwierzytelniania sieci Web

2025-06-10

W tym artykule wyjaśniono, jak połączyć aplikację platformy uniwersalnej systemu Windows (UWP) z dostawcą tożsamości online korzystającym z protokołów uwierzytelniania, takich jak OpenID lub OAuth. Metoda AuthenticationAsync wysyła żądanie do dostawcy tożsamości online i pobiera token dostępu opisujący zasoby dostawcy, do których aplikacja ma dostęp.

Uwaga / Notatka

Aby uzyskać pełny, działający przykładowy kod, sklonuj repozytorium WebAuthenticationBroker na GitHubie.

Rejestrowanie aplikacji u dostawcy online

Musisz zarejestrować aplikację u dostawcy tożsamości online, z którym chcesz się połączyć. Możesz dowiedzieć się, jak zarejestrować aplikację u dostawcy tożsamości. Po zarejestrowaniu dostawca online zazwyczaj udostępnia identyfikator lub klucz tajny aplikacji.

Tworzenie identyfikatora URI żądania uwierzytelniania

Identyfikator URI żądania składa się z adresu, pod który wysyłasz żądanie uwierzytelniania do dostawcy online, oraz dołączonych innych wymaganych informacji, takich jak identyfikator aplikacji lub tajny klucz, identyfikator URI przekierowania, na który użytkownik jest wysyłany po zakończeniu uwierzytelniania, oraz oczekiwany typ odpowiedzi. Możesz dowiedzieć się od dostawcy, jakie parametry są wymagane.

Identyfikator URI żądania jest wysyłany jako parametr requestUri metody AuthenticateAsync . Musi to być bezpieczny adres (musi zaczynać się od https://)

W poniższym przykładzie pokazano, jak utworzyć identyfikator URI żądania.

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

Nawiązywanie połączenia z dostawcą online

Wywołasz metodę AuthenticationAsync , aby nawiązać połączenie z dostawcą tożsamości online i uzyskać token dostępu. Metoda przyjmuje identyfikator URI skonstruowany w poprzednim kroku jako parametr requestUri i identyfikator URI, do którego użytkownik ma zostać przekierowany jako parametr callbackUri .

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

Ostrzeżenie

Oprócz AuthenticateAsyncprzestrzeń nazw Windows.Security.Authentication.Web zawiera metodę AuthenticateAndContinue. Nie należy wywoływać tej metody. Jest przeznaczony tylko dla aplikacji przeznaczonych dla systemu Windows Phone 8.1 i jest przestarzały począwszy od systemu Windows 10.

Nawiązywanie połączenia przy użyciu logowania jednokrotnego (SSO).

Domyślnie broker uwierzytelniania sieci Web nie zezwala na utrwalanie plików cookie. W związku z tym, nawet jeśli użytkownik aplikacji wskazuje, że chce pozostać zalogowany (na przykład po wybraniu pola wyboru w oknie dialogowym logowania dostawcy), będzie musiał zalogować się za każdym razem, gdy chce uzyskać dostęp do zasobów dla tego dostawcy. Aby zalogować się z użyciem SSO (logowanie jednokrotne), dostawca tożsamości online musi mieć włączone SSO dla brokera uwierzytelniania w sieci Web, a aplikacja musi wywołać przeciążenie AuthenticateAsync, które nie ma parametru callbackUri. Pozwoli to przechowywać utrwalone pliki cookie przez brokera uwierzytelniania internetowego, dzięki czemu przyszłe wywołania uwierzytelniania przez tę samą aplikację nie będą wymagały wielokrotnego logowania przez użytkownika (użytkownik jest skutecznie "zalogowany" do momentu wygaśnięcia tokenu dostępu).

Aby obsługiwać logowanie jednokrotnego, dostawca online musi zezwolić na zarejestrowanie identyfikatora URI przekierowania w formacie ms-app://<appSID>, gdzie <appSID> jest SIDem aplikacji. Identyfikator SID aplikacji można znaleźć na stronie dewelopera aplikacji lub wywołując metodę 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;
}

Debugowanie

Istnieje kilka sposobów rozwiązywania problemów z interfejsami API brokera uwierzytelniania internetowego, w tym przeglądania dzienników operacyjnych i przeglądania żądań internetowych i odpowiedzi przy użyciu programu Fiddler.

Dzienniki operacyjne

Często można określić, co nie działa przy użyciu dzienników operacyjnych. Istnieje dedykowany kanał dziennika zdarzeń Microsoft-Windows-WebAuth\Operational, który umożliwia deweloperom witryn internetowych zrozumienie sposobu przetwarzania stron internetowych przez brokera uwierzytelniania sieci Web. Aby ją włączyć, uruchom eventvwr.exe i włącz dziennik operacyjny w obszarze Application and Services\Microsoft\Windows\WebAuth. Ponadto broker uwierzytelniania sieci Web dołącza unikatowy ciąg do ciągu agenta użytkownika w celu zidentyfikowania się na serwerze internetowym. Ciąg znaków to "MSAuthHost/1.0". Należy pamiętać, że numer wersji może ulec zmianie w przyszłości, dlatego nie należy zależeć od tego numeru wersji w kodzie. Przykład pełnego ciągu agenta użytkownika, po którym następują pełne kroki debugowania, jest następujący.

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

Włącz dzienniki operacyjne.
Uruchom aplikację społeczną firmy Contoso.
Wygenerowane wpisy dzienników mogą służyć do lepszego zrozumienia zachowania brokera uwierzytelniania sieci Web. W takim przypadku mogą to być:
- Start nawigacji: rejestruje, kiedy AuthHost jest uruchomiony i zawiera informacje o adresach URL rozpoczęcia i zakończenia.
- Zakończenie nawigacji: rejestruje ukończenie ładowania strony internetowej.
- Meta Tag: rejestruje, gdy napotkano metatag, w tym szczegóły.
- Zakończenie nawigacji: nawigacja zakończona przez użytkownika.
- Błąd nawigacji: AuthHost napotyka problem z nawigacją pod adresem URL zawierającym HttpStatusCode.
- Koniec nawigacji: napotkano końcowy adres URL.

Skrzypek

Debuger internetowy programu Fiddler może być używany z aplikacjami. Aby uzyskać więcej informacji, zobacz dokumentację programu Fiddler

Ponieważ AuthHost działa we własnym kontenerze aplikacji, aby zapewnić mu możliwość sieci prywatnej, należy ustawić klucz rejestru: Edytor rejestru Systemu Windows w wersji 5.00

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Opcje wykonywania plików obrazu\authhost.exe\EnablePrivateNetwork = 00000001

Jeśli nie masz tego klucza rejestru, możesz go utworzyć w wierszu polecenia z uprawnieniami administratora.
```
REG ADD "HKLM\Software\Microsoft\Windows NT\CurrentVersion\Image File Execution Options\authhost.exe" /v EnablePrivateNetwork /t REG_DWORD /d 1 /f
```

Dodaj regułę dla AuthHost, ponieważ to on generuje ruch wychodzący.

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

Dodaj regułę zapory dla ruchu przychodzącego do programu Fiddler.

Udostępnij za pośrednictwem