Web 認証ブローカー

[アーティクル]
07/13/2023

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

注意

動作する完全なコード例が必要な場合は、GitHub の WebAuthenticationBroker リポジトリをコピーしてください。

アプリのオンラインプロバイダーへの登録

アプリを接続先のオンライン ID プロバイダーに登録する必要があります。アプリを登録する方法については、ID プロバイダーに確認してください。通常、登録すると、オンラインプロバイダーからアプリの ID や秘密鍵が提供されます。

認証要求の URI の作成

要求の URI は、オンラインプロバイダーに対する認証要求の送信先のアドレスと、必要なその他の情報 (アプリ ID またはシークレット、認証後にユーザーが転送されるリダイレクト URI、必要な応答の型など) で構成されます。必要なパラメーターについては、プロバイダーに確認してください。

要求の URI は、AuthenticateAsync メソッドの requestUri パラメーターとして送信されます。また、セキュリティで保護されたアドレスである (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);

オンラインプロバイダーへの接続

AuthenticateAsync メソッドを呼び出してオンライン ID プロバイダーに接続し、アクセストークンを取得します。このメソッドは、前の手順で作った 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;
}

警告

AuthenticateAsync に加え、Windows.Security.Authentication.Web 名前空間には AuthenticateAndContinue メソッドが含まれています。このメソッドは呼び出さないでください。これは Windows Phone 8.1 のみを対象とするアプリ用に設計されたもので、Windows 10 以降では推奨されません。

シングルサインオン (SSO) を使った接続

既定では、Web 認証ブローカーは Cookie の保存を許可していません。そのため、アプリユーザーは (たとえば、プロバイダーのログインダイアログのチェックボックスをオンにして) ログオン状態を維持することを示した場合でも、そのプロバイダーのリソースにアクセスするたびにログインする必要があります。 SSO を使ってログインするには、オンライン ID プロバイダーが Web 認証ブローカーに対して SSO を有効にしており、callbackUri パラメーターを受け取らない AuthenticateAsync のオーバーロードをアプリで呼び出す必要があります。これで Web 認証ブローカーが永続 cookie を保存でき、これ以降に同じアプリから認証を求められたときに、ユーザーは再びサインインを行う必要がありません (アクセストークンの期限が切れるまで、ユーザーは実質的に "ログイン" した状態になります)。

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

デバッグ

Web 認証ブローカー API のトラブルシューティングには、操作ログの確認や Fiddler を使った Web 要求と応答の確認など、いくつかの方法があります。

操作ログ

問題の原因の多くは、操作ログを使って特定できます。 Web サイト開発者向けの専用のイベントログチャネルである Microsoft-Windows-WebAuth\Operational を使うと、Web 認証ブローカーで Web ページが処理される過程を把握できます。これを有効にするには、eventvwr.exe を起動し、アプリケーションと Services\Microsoft\Windows\WebAuth で操作ログを有効にします。また、Web 認証ブローカーは Web サーバー上で自身を識別するために、ユーザーエージェント文字列に一意の文字列を追加します。その文字列は、"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 ソーシャルアプリを実行します。
生成されたログエントリで、Web 認証ブローカーの動作を把握することができます。この場合、これらには次のものが含まれます。
- ナビゲーションの開始: AuthHost が開始された時点のログ。開始 URL と終了 URL に関する情報が含まれています。
- ナビゲーションの完了: Web ページの読み込み完了時のログ。
- メタタグ: メタタグが検出されたときのログ。詳しい情報を含みます。
- ナビゲーションの停止: ユーザーによって停止されたナビゲーション。
- ナビゲーションエラー: AuthHost が HttpStatusCode を含む URL でナビゲーションエラーを検出。
- ナビゲーションの終了: 終了 URL を検出。

Fiddler

Fiddler Web デバッガーはアプリに対して使うことができます。詳細については、Fiddler のドキュメントを参照してください。

AuthHost はプライベートネットワーク機能を実現するために専用のアプリコンテナー内で実行されるため、Windows Registry Editor Version 5.00 というレジストリキーを設定する必要があります。

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Image File 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 であるため、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 への受信トラフィック用のファイアウォール規則を追加します。

Web 認証ブローカー

アプリのオンラインプロバイダーへの登録

認証要求の URI の作成

オンラインプロバイダーへの接続

シングルサインオン (SSO) を使った接続

デバッグ

操作ログ

Fiddler

フィードバック

フィードバック

その他のリソース

Web 認証ブローカー

アプリのオンライン プロバイダーへの登録

認証要求の URI の作成

オンライン プロバイダーへの接続

シングル サインオン (SSO) を使った接続

デバッグ

操作ログ

Fiddler

フィードバック

フィードバック

その他のリソース

アプリのオンラインプロバイダーへの登録

オンラインプロバイダーへの接続

シングルサインオン (SSO) を使った接続