Брокер веб-аутентификации

Статья
03/12/2024

В этой статье объясняется, как подключить приложение универсальная платформа Windows (UWP) к интернет-поставщику удостоверений, использующего протоколы проверки подлинности, такие как OpenID или OAuth. Метод AuthenticationAsync отправляет запрос поставщику удостоверений в Интернете и возвращает маркер доступа, описывающий ресурсы поставщика, к которым имеет доступ приложение.

Примечание.

Полный пример рабочего кода клонируйте репозиторий WebAuthenticationBroker на GitHub.

Регистрация приложения в интернет-поставщике

Необходимо зарегистрировать приложение в веб-поставщике удостоверений, к которому требуется подключиться. Вы можете узнать, как зарегистрировать приложение из поставщика удостоверений. После регистрации интернет-поставщик обычно предоставляет идентификатор или секретный ключ для приложения.

Создание URI запроса проверки подлинности

URI запроса состоит из адреса, в котором отправляется запрос проверки подлинности поставщику в Интернете, добавленным с другими необходимыми сведениями, такими как идентификатор приложения или секрет, URI перенаправления, в котором пользователь отправляется после завершения проверки подлинности, и ожидаемый тип ответа. Вы можете узнать у поставщика необходимые параметры.

URI запроса отправляется в качестве параметра requestUri метода AuthenticateAsync. Он должен быть безопасным адресом (он должен начинаться с https://)

В следующем примере показано, как создать универсальный код ресурса (URI) запроса.

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

Подключение к интернет-поставщику

Метод AuthenticationAsync вызывается для подключения к поставщику удостоверений в Интернете и получения маркера доступа. Метод принимает URI, созданный на предыдущем шаге в качестве параметра requestUri , и URI, к которому пользователь будет перенаправлен в качестве параметра 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;
}

Предупреждение

Помимо AuthenticationAsync пространство имен Windows.Security.Authentication.Web содержит метод AuthenticationAndContinue. Не вызывайте этот метод. Он предназначен для приложений, предназначенных только для Windows Phone 8.1 и не рекомендуется использовать начиная с Windows 10.

Подключение с помощью единого входа.

По умолчанию брокер веб-проверки подлинности не позволяет сохранять файлы cookie. Из-за этого, даже если пользователь приложения указывает, что он хочет оставаться в системе (например, установив флажок в диалоговом окне входа поставщика), им придется войти каждый раз, когда они хотят получить доступ к ресурсам для этого поставщика. Чтобы войти с помощью единого входа, поставщик удостоверений в Сети должен включить единый вход для брокера веб-проверки подлинности, и приложение должно вызвать перегрузку AuthenticationAsync, которая не принимает параметр callbackUri. Это позволит сохранять сохраненные файлы cookie брокером веб-проверки подлинности, чтобы последующие вызовы проверки подлинности с помощью того же приложения не требовали повторного входа пользователем (пользователь фактически "вошел" до истечения срока действия маркера доступа).

Для поддержки единого входа интернет-поставщик должен разрешить зарегистрировать URI перенаправления в форме ms-app://<appSID>, где <appSID> находится идентификатор безопасности для вашего приложения. Идентификатор безопасности приложения можно найти на странице разработчика приложения или путем вызова метода 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;
}

Отладка

Существует несколько способов устранения неполадок API-интерфейсов брокера веб-проверки подлинности, включая просмотр операционных журналов и просмотр веб-запросов и ответов с помощью Fiddler.

Операционные журналы

Часто можно определить, что не работает с помощью операционных журналов. Существует выделенный канал журнала событий Microsoft-Windows-WebAuth\Operational, позволяющий разработчикам веб-сайтов понять, как обрабатываются веб-страницы брокером веб-проверки подлинности. Чтобы включить его, запустите eventvwr.exe и включите операционный журнал в разделе "Приложения и службы\Microsoft\Windows\WebAuth". Кроме того, брокер веб-проверки подлинности добавляет уникальную строку к строке агента пользователя, чтобы идентифицировать себя на веб-сервере. Строка — MSAuthHost/1.0. Обратите внимание, что номер версии может измениться в будущем, поэтому не следует зависеть от этого номера версии в коде. Ниже приведен пример полной строки агента пользователя, а затем полной отладки.

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

Включите операционные журналы.
Запустите социальное приложение Contoso.
Созданные записи журналов можно использовать для более подробного понимания поведения брокера веб-проверки подлинности. В этом случае они могут включать:
- Запуск навигации: журналы при запуске AuthHost и содержат сведения о URL-адресах начала и завершения.
- Завершение навигации: регистрирует завершение загрузки веб-страницы.
- Мета тег: журналы при обнаружении мета-тега, включая сведения.
- Завершение навигации: навигация завершена пользователем.
- Ошибка навигации: AuthHost обнаруживает ошибку навигации по URL-адресу, включая HttpStatusCode.
- Конец навигации: возникает конечный URL-адрес.

Fiddler

Веб-отладчик Fiddler можно использовать с приложениями. Дополнительные сведения см . в документации по Fiddler

Так как AuthHost работает в собственном контейнере приложений, чтобы предоставить ему возможность частной сети, необходимо задать раздел реестра: редактор реестра Windows версии 5.00

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

Если у вас нет этого раздела реестра, его можно создать в командной строке с правами администратора.
```
REG ADD "HKLM\Software\Microsoft\Windows NT\CurrentVersion\Image File Execution Options\authhost.exe" /v EnablePrivateNetwork /t REG_DWORD /d 1 /f
```

Добавьте правило для AuthHost, так как это то, что создает исходящий трафик.

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

Добавьте правило брандмауэра для входящего трафика в Fiddler.

Поделиться через