Брокер веб-проверки подлинностиWeb authentication broker

В этой статье описывается, как подключить ваше приложение универсальной платформы Windows (UWP) к поставщику сетевых удостоверений, использующему такие протоколы проверки подлинности, как OpenID или OAuth, например, Facebook, Twitter, Flickr, Instagram, и т. д.This article explains how to connect your Universal Windows Platform (UWP) app to an online identity provider that uses authentication protocols like OpenID or OAuth, such as Facebook, Twitter, Flickr, Instagram, and so on. Метод AuthenticateAsync отправляет запрос поставщику сетевых удостоверений и получает маркер доступа, описывающий ресурсы поставщика, к которым имеет доступ приложение.The AuthenticateAsync method sends a request to the online identity provider and gets back an access token that describes the provider resources to which the app has access.

Примечание

Чтобы получить полный рабочий примера кода, клонируйте репозиторий WebAuthenticationBroker на GitHub.For a complete, working code sample, clone the WebAuthenticationBroker repo on GitHub.

 

Регистрация приложения у поставщикаRegister your app with your online provider

Вам нужно зарегистрировать приложение у поставщика сетевых удостоверений, к которому вы хотите подключиться.You must register your app with the online identity provider to which you want to connect. Узнать, как это делается, можно у поставщика сетевых удостоверений.You can find out how to register your app from the identity provider. После регистрации поставщик обычно передает идентификатор или секретный ключ для вашего приложения.After registering, the online provider typically gives you an Id or secret key for your app.

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

URI запроса состоит из адреса, по которому поставщику отправляется запрос проверки подлинности, и другой необходимой информации (например, идентификатора приложения или секретных данных), а также URI перенаправления, по которому переходит пользователь, завершивший проверку подлинности, и ожидаемого типа ответа.The request URI consists of the address where you send the authentication request to your online provider appended with other required information, such as an app ID or secret, a redirect URI where the user is sent after completing authentication, and the expected response type. Вы можете выяснить у поставщика, какие именно параметры необходимы.You can find out from your provider what parameters are required.

URI запроса отправляется как параметр requestUri метода AuthenticateAsync.The request URI is sent as the requestUri parameter of the AuthenticateAsync method. Это должен быть безопасный адрес (который начинается с https://).It must be a secure address (it must start with https://)

В следующем примере показано, как составляется URI запроса.The following example shows how to build the request 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);

Подключение к поставщикуConnect to the online provider

Для подключения к поставщику сетевых удостоверений и получения маркера доступа вызывается метод AuthenticateAsync.You call the AuthenticateAsync method to connect to the online identity provider and get an access token. В этом методе в качестве параметра requestUri берется URI, созданный на предыдущем шаге, а в качестве параметра callbackUri — URI, выбранный для перенаправления пользователя.The method takes the URI constructed in the previous step as the requestUri parameter, and a URI to which you want the user to be redirected as the callbackUri parameter.

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

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

Помимо AuthenticateAsync пространство имен Windows.Security.Authentication.Web включает метод AuthenticateAndContinue.In addition to AuthenticateAsync, the Windows.Security.Authentication.Web namespace contains an AuthenticateAndContinue method. Этот метод не следует вызывать.Do not call this method. Он разработан для приложений, предназначенных для Windows Phone 8.1, и, начиная с Windows 10, считается устаревшим.It is designed for apps targeting Windows Phone 8.1 only and is deprecated starting with Windows 10.

Подключение с единым входомConnecting with single sign-on (SSO).

По умолчанию брокер веб-проверки подлинности не разрешает сохранять файлы cookie.By default, Web authentication broker does not allow cookies to persist. Из-за этого даже в том случае, когда пользователь приложения указывает, что не хочет выходить из приложения (например, установив флажок в диалоговом окне входа в систему поставщика), ему придется выполнять вход каждый раз при обращении к ресурсам данного поставщика.Because of this, even if the app user indicates that they want to stay logged in (for example, by selecting a check box in the provider's login dialog), they will have to login each time they want to access resources for that provider. Чтобы выполнить вход с помощью единого входа, ваш поставщик сетевых удостоверений должен включить единый вход для брокера веб-проверки подлинности, а ваше приложение должно вызвать перегруженный метод AuthenticateAsync, где не применяется параметр callbackUri parameter.To login with SSO, your online identity provider must have enabled SSO for Web authentication broker, and your app must call the overload of AuthenticateAsync that does not take a callbackUri parameter. Это позволит брокеру веб-проверки подлинности хранить сохраненные файлы cookie, чтобы для будущих вызовов проверки подлинности, совершаемых тем же приложением, пользователю не требовалось выполнять повторный вход (пользователь фактически остается в системе до истечения срока действия маркера доступа).This will allow persisted cookies to be stored by the web authentication broker, so that future authentication calls by the same app will not require repeated sign-in by the user (the user is effectively "logged in" until the access token expires).

В целях поддержки единого входа поставщик должен разрешить вам зарегистрировать URI перенаправления в форме ms-app://<appSID>, где <appSID> — это идентификатор безопасности для вашего приложения.To support SSO, the online provider must allow you to register a redirect URI in the form ms-app://<appSID>, where <appSID> is the SID for your app. Идентификатор безопасности приложения можно найти на странице разработчика вашего приложения или путем вызова метода GetCurrentApplicationCallbackUri.You can find your app's SID from the app developer page for your app, or by calling the GetCurrentApplicationCallbackUri method.

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

ОтладкаDebugging

Существует несколько способов выполнить диагностику API брокера веб-проверки подлинности, включая просмотр операционных журналов, веб-запросов и ответов с помощью веб-отладчика Fiddler.There are several ways to troubleshoot the web authentication broker APIs, including reviewing operational logs and reviewing web requests and responses using Fiddler.

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

Нередко определить, что именно не работает, помогают операционные журналы.Often you can determine what is not working by using the operational logs. Существует выделенный канал журнала событий Microsoft-Windows- \ Web AUTH, позволяющий разработчикам веб-сайтов понять, как веб-страницы обрабатываются брокером веб-проверки подлинности.There is a dedicated event log channel Microsoft-Windows-WebAuth\Operational that allows website developers to understand how their web pages are being processed by the Web authentication broker. Чтобы включить его, запустите eventvwr.exe и включите операционный журнал в приложении и службах \ Microsoft \ Windows веб \ AUTH.To enable it, launch eventvwr.exe and enable Operational log under the Application and Services\Microsoft\Windows\WebAuth. Брокер веб-проверки подлинности также добавляет уникальную строку к строке агента пользователя, чтобы идентифицировать себя на веб-сервере.Also, the Web authentication broker appends a unique string to the user agent string to identify itself on the web server. Это строка "MSAuthHost/1.0".The string is "MSAuthHost/1.0". Обратите внимание, что номер версии в дальнейшем может меняться, поэтому ваш код не должен зависеть от номера версии.Note that the version number may change in the future, so you should not to depend on that version number in your code. Ниже приведен пример полной строки агента пользователя и полной процедуры отладки.An example of the full user agent string, followed by full debugging steps, is as follows.

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

  1. Включите операционные журналы.Enable operational logs.
  2. Запустите социальное приложение Contoso.Run Contoso social application. Средство просмотра событий, отображающее операционные журналы WebAuth
  3. Записи, созданные в журналах, помогают глубже вникнуть в особенности поведения брокера веб-проверки подлинности.The generated logs entries can be used to understand the behavior of Web authentication broker in greater detail. В нашем случае записи могут содержать следующую информацию.In this case, these can include:
    • Навигация начата: регистрирует время запуска AuthHost и содержит сведения о URL-адресах начала и окончания навигации.Navigation Start: Logs when the AuthHost is started and contains information about the start and termination URLs.
    • Иллюстрация к сведениям о начале навигации
    • Навигация выполнена: регистрирует выполнение загрузки веб-страницы.Navigation Complete: Logs the completion of loading a web page.
    • Метатег: регистрирует подробную информацию в случае обнаружения метатега.Meta Tag: Logs when a meta-tag is encountered including the details.
    • Завершение навигации: навигация завершена пользователем.Navigation Terminate: Navigation terminated by the user.
    • Ошибка навигации: AuthHost обнаруживает ошибку навигации в URL-адресе, включая код состояния HttpStatusCode.Navigation Error: AuthHost encounters a navigation error at a URL including HttpStatusCode.
    • Завершение навигации: обнаружен завершающий URL-адрес.Navigation End: Terminating URL is encountered.

FiddlerFiddler

Веб-отладчик Fiddler можно использовать с приложениями.The Fiddler web debugger can be used with apps.

  1. Поскольку AuthHost выполняется в собственном контейнере приложения, чтобы предоставить ему возможность частной сети, необходимо задать раздел реестра: редактор реестра Windows версии 5,00Since the AuthHost runs in its own app container, to give it the private network capability you must set a registry key: Windows Registry Editor Version 5.00

    HKey _ _ \ SOFTWARE \ Microsoft \ Windows NT \ CurrentVersion \ Параметры выполнения файлов образа Microsoft Windows NT CurrentVersion по локальному компьютеру \ authhost.exe \ енаблеприватенетворк = 00000001HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Image File Execution Options\authhost.exe\EnablePrivateNetwork = 00000001

    Если этот раздел реестра отсутствует, его можно создать в командной строке с правами администратора.If you do not have this registry key, you can create it in a Command Prompt with administrator privileges.

    REG ADD "HKLM\Software\Microsoft\Windows NT\CurrentVersion\Image File Execution Options\authhost.exe" /v EnablePrivateNetwork /t REG_DWORD /d 1 /f
    
  2. Добавьте правило для AuthHost, поскольку эта служба создает исходящий трафик.Add a rule for the AuthHost as this is what is generating the outbound traffic.

    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. Добавьте правило брандмауэра для входящего трафика в Fiddler.Add a firewall rule for incoming traffic to Fiddler.