Web 認証ブローカーWeb authentication broker

この記事では、OpenID や OAuth などの認証プロトコルを使うオンライン ID プロバイダー (Facebook、Twitter、Flickr、Instagram など) にユニバーサル Windows プラットフォーム (UWP) アプリを接続する方法について説明します。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 メソッドは、要求をオンライン ID プロバイダーに送信し、アプリがアクセスできるプロバイダー リソースを示すアクセス トークンを返します。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.

注意

動作する完全なコード例が必要な場合は、GitHub の WebAuthenticationBroker リポジトリをコピーしてください。For a complete, working code sample, clone the WebAuthenticationBroker repo on GitHub.

アプリのオンライン プロバイダーへの登録Register your app with your online provider

アプリを接続先のオンライン ID プロバイダーに登録する必要があります。You must register your app with the online identity provider to which you want to connect. アプリを登録する方法については、ID プロバイダーに確認してください。You can find out how to register your app from the identity provider. 通常、登録すると、オンライン プロバイダーからアプリの ID や秘密鍵が提供されます。After registering, the online provider typically gives you an Id or secret key for your app.

認証要求の URI の作成Build the authentication request URI

要求の URI は、オンライン プロバイダーに対する認証要求の送信先のアドレスと、必要なその他の情報 (アプリ ID またはシークレット、認証後にユーザーが転送されるリダイレクト 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 は、AuthenticateAsync メソッドの requestUri パラメーターとして送信されます。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 メソッドを呼び出してオンライン ID プロバイダーに接続し、アクセス トークンを取得します。You call the AuthenticateAsync method to connect to the online identity provider and get an access token. このメソッドは、前の手順で作った URI を requestUri パラメーターとして受け取り、ユーザーのリダイレクト先の URI を callbackUri パラメーターとして受け取ります。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 Windows10.

シングル サインオン (SSO) を使った接続Connecting with single sign-on (SSO).

既定では、Web 認証ブローカーは 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. SSO を使ってログインするには、オンライン ID プロバイダーが Web 認証ブローカーに対して SSO を有効にしており、*callbackUri * パラメーターを受け取らない **AuthenticateAsync ** のオーバーロードをアプリで呼び出す必要があります。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. これで Web 認証ブローカーが永続 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).

SSO をサポートするには、オンライン プロバイダーが ms-app://<appSID> という形式のリダイレクト URI の登録を許可している必要があります。<appSID> は、アプリの SID です。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. アプリの SID は、アプリ開発者のページか、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

Web 認証ブローカー API のトラブルシューティングには、操作ログの確認や Fiddler を使った Web 要求と応答の確認など、いくつかの方法があります。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. Web サイト開発者向けの専用のイベント ログ チャネルである Microsoft-Windows-WebAuth\Operational を使うと、Web 認証ブローカーで Web ページが処理される過程を把握できます。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 を起動し、アプリケーションとサービス ログvices\Microsoft\Windows\WebAuth で操作ログを有効にします。To enable it, launch eventvwr.exe and enable Operational log under the Application and Services\Microsoft\Windows\WebAuth. また、Web 認証ブローカーは Web サーバー上で自身を識別するために、ユーザー エージェント文字列に一意の文字列を追加します。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. 生成されたログ エントリで、Web 認証ブローカーの動作を把握することができます。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 と終了 URL に関する情報が含まれています。Navigation Start: Logs when the AuthHost is started and contains information about the start and termination URLs.
    • ナビゲーションの開始の例
    • ナビゲーションの完了: Web ページの読み込み完了時のログ。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 が HttpStatusCode を含む URL でナビゲーション エラーを検出。Navigation Error: AuthHost encounters a navigation error at a URL including HttpStatusCode.
    • ナビゲーションの終了: 終了 URL を検出。Navigation End: Terminating URL is encountered.

FiddlerFiddler

Fiddler Web デバッガーはアプリに対して使うことができます。The Fiddler web debugger can be used with apps.

  1. 独自のアプリ コンテナー内であるため、AuthHost が実行されるとので、プライベート ネットワーク機能を提供する必要があります設定するレジストリ キー: Windows レジストリ エディター Version 5.00 というSince 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_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Image File Execution Options\authhost.exe\EnablePrivateNetwork = 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 であるため、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.