Web アカウント マネージャー (WAM) での MSAL.NET の使用

MSAL は、OS に付属する Windows コンポーネントである Web アカウント マネージャー (WAM) を呼び出すことが可能です。 このコンポーネントは認証ブローカーとして機能し、アプリのユーザーは、Windows セッションにサインインしたアカウントなど、Windows知られているアカウントとの統合の恩恵を受けることができます。

Note

WAM は、Windows 10 (バージョン 1703 - Creators Update) 以降およびWindows Server 2019以降の MSAL.NET ベースのアプリケーションで使用できます。 WAM を使用できない場合、MSAL は自動的にブラウザーにフォールバックします。

ブローカーとは

認証ブローカーは、接続されているアカウントの認証ハンドシェイクとトークンメンテナンスを管理するユーザーのマシン上で実行されるアプリケーションです。 Windows オペレーティング システムは、認証ブローカーとして Web アカウント マネージャー (WAM) を使用します。 開発者と顧客にとって、次のような多くの利点があります。

• セキュリティの強化。 多くのセキュリティ強化は、アプリケーション ロジックを更新することなく、ブローカーと共に提供されます。
• 機能のサポート。 ブローカー開発者の助けを借りて、余分なスキャフォールディング コードを記述することなく、Windows Hello、条件付きアクセス ポリシー、FIDO キーなどの豊富な OS およびサービス機能にアクセスできます。
• システム統合。 組み込みのアカウント ピッカーでブローカー プラグ アンド プレイを使用するアプリケーションにより、ユーザーは同じ資格情報を何度も再入力する代わりに、既存のアカウントをすばやく選択できます。
• トークン保護。 WAM では、更新トークンがデバイスバインドされ、アプリがデバイスバインドアクセストークンを取得 できるようにします 。 「トークン保護」を参照してください。

WAM の有効化

Important

ブローカーのサポートを得るには、MSAL.NET 4.52.0 以降を使用します。

Important

WAM では、Microsoft Entra IDのみがサポートされ、サード パーティの ID プロバイダー (IDP) では機能しません。

WAM のサポートは、次の 2 つのパッケージに分割されます。

• Microsoft。Identity.Client (つまり、MSAL) - トークン取得用のコア ライブラリ。
• Microsoft。Identity.Client.Broker - ブローカーでの認証のサポートを追加します。

Note

移行のために、両方の WAM と 埋め込みブラウザー を使用する必要がある .NET 6、.NET Core、または .NET Standard のアプリケーションでは、Microsoft.Identity.Client.Desktop パッケージも使用する必要があります。 追加すると、開発者はパブリック クライアント アプリケーションを設定するときに WithWindowsDesktopFeatures を使用できます。

アプリケーションがnet-windows (Windows のバージョン依存のターゲット フレームワーク モニカー) をターゲットとする場合、WAM は MSAL.NET パッケージに含まれます。

関連するパッケージを参照した後、ブローカー構成オプションとブローカーがバインドされるWithBroker(BrokerOptions)使用してを呼び出します。

Note

ほとんどのアプリでは、この統合を使用するには Microsoft.Identity.Client.Broker パッケージを参照する必要があります。 適切なusing Microsoft.Identity.Client.Broker;オーバーロードを使用できるように、アプリケーション コードに WithBroker ステートメントを追加してください。 .NET MAUIアプリケーションでは、機能が MSAL に埋め込まれているため、依存関係を追加する必要はありません。

var scopes = new[] { "User.Read" };

BrokerOptions options = new BrokerOptions(BrokerOptions.OperatingSystems.Windows);
options.Title = "My Awesome Application";

IPublicClientApplication app =
    PublicClientApplicationBuilder.Create("YOUR_CLIENT_ID")
    .WithDefaultRedirectUri()
    .WithParentActivityOrWindow(GetConsoleOrTerminalWindow)
    .WithBroker(options)
    .Build();

AuthenticationResult result = null;

// Try to use the previously signed-in account from the cache
IEnumerable<IAccount> accounts = await app.GetAccountsAsync();
IAccount existingAccount = accounts.FirstOrDefault();

try
{    
    if (existingAccount != null)
    {
        result = await app.AcquireTokenSilent(scopes, existingAccount).ExecuteAsync();
    }
    // Next, try to sign in silently with the account that the user is signed into Windows
    else
    {    
        result = await app.AcquireTokenSilent(scopes, PublicClientApplication.OperatingSystemAccount)
                            .ExecuteAsync();
    }
}
// Can't get a token silently, go interactive
catch (MsalUiRequiredException ex)
{
    result = await app.AcquireTokenInteractive(scopes).ExecuteAsync();
}

ブローカーを使用する場合、使用する機関がMicrosoft Entra IDと個人のMicrosoft アカウントを対象としている場合、ユーザーはまず、組み込みのシステム アカウント ピッカーを使用してアカウントを選択するように求められます。

WithTenantIdを使用してテナントごとに構成が設定されている場合、または権限が個人のMicrosoft アカウントを含まない対象ユーザーに設定されている場合、ネイティブ Windows アカウント ピッカーは表示されず、代わりにユーザーに一般的なMicrosoft認証プロンプトが表示されます。

アカウントが追加または選択されると、以前にアプリケーションを使用したことがない場合、またはアプリケーションに追加のアクセス許可が必要な場合、ユーザーは追加の同意を求められます。

親ウィンドウのハンドル

ブローカーを使用するには、WithParentActivityOrWindow API を使用して、WAM モーダル ダイアログの親ウィンドウとなるウィンドウ ハンドルを指定することが必須になりました。 ウィンドウ ハンドルは、MSAL 自体が親ウィンドウを推論することは不可能であるため、開発者が提供する必要があります。これは、以前は、認証ウィンドウがアプリケーション ウィンドウの背後に隠れていたという不適切なユーザー エクスペリエンスを引き起こしたためです。

Windows フォーム、Windows Presentation Foundation (WPF)、WinUI3 を使用する UI アプリについては、「ウィンドウ ハンドルの取得 (HWND)」を参照してください。

コンソール アプリケーションの場合は、次のスニペットのようなコードを使用できます。

enum GetAncestorFlags
{   
    GetParent = 1,
    GetRoot = 2,
    /// <summary>
    /// Retrieves the owned root window by walking the chain of parent and owner windows returned by GetParent.
    /// </summary>
    GetRootOwner = 3
}

/// <summary>
/// Retrieves the handle to the ancestor of the specified window.
/// </summary>
/// <param name="hwnd">A handle to the window whose ancestor is to be retrieved.
/// If this parameter is the desktop window, the function returns NULL. </param>
/// <param name="flags">The ancestor to be retrieved.</param>
/// <returns>The return value is the handle to the ancestor window.</returns>
[DllImport("user32.dll", ExactSpelling = true)]
static extern IntPtr GetAncestor(IntPtr hwnd, GetAncestorFlags flags);

[DllImport("kernel32.dll")]
static extern IntPtr GetConsoleWindow();

// This is your window handle!
public IntPtr GetConsoleOrTerminalWindow()
{
    IntPtr consoleHandle = GetConsoleWindow();
    IntPtr handle = GetAncestor(consoleHandle, GetAncestorFlags.GetRootOwner );
    
    return handle;
}

所持証明アクセストークン

WAM ブローカーでは、パブリック クライアント フローの PoP トークンを取得できます。 詳細については 、所有証明トークンを 参照してください。

リダイレクト URI

WAM リダイレクト URI は MSAL で構成する必要はありませんが、アプリの登録で構成する必要があります。 次のパターンに従う必要があります。

ms-appx-web://microsoft.aad.brokerplugin/{client_id}

Note

Azure portalでリダイレクト URL を構成する場合は、[Mobile and desktop applications]\(モバイルアプリケーションとデスクトップ アプリケーション\) セクションで設定していることを確認します。

ユーザー名とパスワードのフロー

このフロー (リソース所有者パスワード資格情報 (ROPC) とも呼ばれます) は、テスト シナリオや、リソースへのサービス プリンシパル アクセスによってアクセスが多くなりすぎて、ユーザー フローでのみスコープを絞り込むことができるシナリオを除き、推奨されません。 WAM を使用する場合、 AcquireTokenByUsernamePassword は WAM がプロトコルを管理し、トークンをフェッチできるようにします。

Warning

Microsoftは、ユーザー名とパスワードのフローを使用することはお勧めしません。これはセキュリティで保護されていないパターンであり、アプリケーションがユーザーに直接パスワードを求めるのでです。 さらに、ROPC フローでは、個人のMicrosoft アカウントと、多要素認証が有効なMicrosoft Entra アカウントはサポートされません。 完全な概要については、Microsoft ID プラットフォームと OAuth 2.0 リソース所有者のパスワード資格情報を確認してください。

WAM の制限事項

• Azure B2C および Active Directory フェデレーション サービス (AD FS) (ADFS) 機関はサポートされていません。 MSAL は、ユーザー認証にブラウザーを使用するようにフォールバックします。
• Mac、Linux、および 10 より前のバージョンのWindowsまたはWindows Server 2019では、MSAL はブラウザーにフォールバックします。

パッケージの可用性

ブローカーを使用するには、開発者は、WithBroker(PublicClientApplicationBuilder, BrokerOptions) パッケージでホストされているMicrosoft.Identity.Client.Brokerを呼び出す必要があります。 MSAL.NET でサポートされている.NETプラットフォームバリアントのほとんどは、そのパッケージのみを必要としますが、いくつかの例外があります。 詳細なマッピングについては、次の表を参照してください。

フレームワーク	Microsoft.Identity.Client	Microsoft。Identity.Client.Broker	Microsoft。Identity.Client.Desktop
.NET 6 以降	⛔ いいえ	✅ はい	⛔ いいえ
.NET 6 以上のWindows†	⛔ いいえ	✅ はい	✅ はい (推奨されません)
.NET MAUI	✅ はい	⛔ いいえ	⛔ いいえ
.NET 4.6.2 以降	⛔ いいえ	✅ はい	✅ はい (推奨されません)
.NET Standard	⛔ いいえ	✅ はい	✅ はい (推奨されません)
.NET コア	⛔ いいえ	✅ はい	✅ はい (推奨されません)

†Microsoft.Identity.Client バージョン 4.61.0 以降には、バイナリ net6.0-windows7.0 含まれていません。 net6.0-windowsを対象とする既存のデスクトップ アプリケーションは、Windows Broker で対話型認証を使用する場合はMicrosoft.Identity.Client.Brokerを参照し、WithBroker(PublicClientApplicationBuilder, BrokerOptions)を呼び出すか、Microsoft.Identity.Client.Desktopしてを呼び出すときにWithWindowsEmbeddedBrowserSupport(PublicClientApplicationBuilder)を参照する必要があります。

統合のベスト プラクティス

Important

WAM を使用する場合、アプリケーションはアクティブで対話型のWindowsユーザー セッションのコンテキストで実行され、UI を表示できる必要があります。 Windows サービスとして実行中、タスク スケジューラを使用して (特にログインユーザーとして実行している場合を除く)、またはを使用して別runasアカウントを偽装しているときに、WAM を使用してトークンを取得しようとすると、設計上エラーが発生します。

お客様が WAM の優れた経験を持っていることを確認するために、次の原則に従うことが強くお勧めします。

1. 認証の前にユーザー コンテキストを指定します。 認証の理由と共に、認証が必要であることをユーザーに通知する UI またはウィンドウを描画します。 アプリケーションがバックグラウンド サービスである場合の利点について説明します。
2. ユーザー アクションに基づいて認証を呼び出します。 ユーザーは、リンクまたはボタンをクリックするか、別のジェスチャを実行して、特定のアプリケーションで認証プロセスをトリガーしたことを認識する必要があります。 ユーザーは、コンテキストやアクションがアタッチされていないオペレーティング システム内にポップアップ表示されるウィンドウに資格情報を入力しないでください。
3. 最初に トークンを自動的に取得 し、失敗した場合は 対話型プロンプト にフォールバックします。 お客様は、資格情報を再入力するか、ポリシー要件を満たす明示的な必要がある場合にのみ、対話型認証を求めるメッセージを表示する必要があります。

Troubleshooting

"MsalClientException (ErrCode 5376): この認証フローでは、少なくとも 1 つのスコープを要求する必要があります。" というエラー メッセージ

このメッセージは、他の OIDC スコープ (user.read、profile、またはemail) と共に、少なくとも 1 つのアプリケーション スコープ (offline_access など) を要求する必要があることを示します。

var authResult = await pca.AcquireTokenInteractive(new[] { "user.read" })
                 .ExecuteAsync();

アカウント選択画面が表示されない

Windowsの更新がアカウント ピッカー コンポーネントに誤って影響を与えることがあり、Windowsのアカウントの一覧と新しいアカウントを追加するオプションが表示されます。 症状としては、ごく一部のユーザーではピッカーが表示されません。

考えられる回避策は、コンポーネントを再登録することです。 管理者のアクセス許可でターミナルから次のスクリプトを実行します。

if (-not (Get-AppxPackage Microsoft.AccountsControl))
{ 
    Add-AppxPackage -Register "$env:windir\SystemApps\Microsoft.AccountsControl_cw5n1h2txyewy\AppxManifest.xml" -DisableDevelopmentMode -ForceApplicationShutdown 
}

Get-AppxPackage Microsoft.AccountsControl

接続に関する問題

アプリケーション ユーザーに、 Please check your connection and try againのようなエラー メッセージが表示されます。 この問題が定期的に発生する場合は、WAM も使用する Office のトラブルシューティング ガイドを参照してください。

WAM エラー コード

WAM エラーの詳細については、 Web アカウント マネージャー (WAM) に関連付けられている エラーを参照してください。

WAM は比較的新しいコンポーネントであるため、エラーが発生した場合は、 AdditionalExceptionDataからデータをログに記録することをお勧めします。 これは、構成または WAM コンポーネントに関する特定の問題を特定するのに役立ちます。 WAM の問題が発生した場合は、 バグをログに記録 してください。これは、問題にタイムリーに対処するのに役立ちます。