Брокер веб-аутентификации
В этой статье объясняется, как подключить приложение универсальная платформа 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 Телефон 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.
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по