.NET 用 Azure Identity Brokered Authentication クライアント ライブラリ - バージョン 1.0.0

このライブラリは、認証ブローカーのサポートを提供するために Azure.Identity ライブラリを拡張します。 これには必要な依存関係が含まれており、 クラスが提供されます InteractiveBrowserCredentialBrokerOptions 。 このオプション クラスを使用すると、使用可能な InteractiveBrowserCredential 場合は、システム ブラウザーの代わりにシステム認証ブローカーを使用できる を作成できます。

ソースコード | パッケージ (nuget) | API リファレンス ドキュメント | Microsoft Entra ID のドキュメント

作業の開始

パッケージをインストールする

NuGet を使用して .NET 用 Azure Identity クライアント ライブラリをインストールします。

dotnet add package Azure.Identity.Broker

前提条件

• Azure.Identity ライブラリは、Azure.Identity.Broker の依存関係です。

クライアントを認証する

主要な概念

このパッケージでは、 を使用したInteractiveBrowserCredentialBrokerOptions認証ブローカーのサポートが、パッケージ内で Azure.Identity とInteractiveBrowserCredential組み合わせて有効になります。

親ウィンドウ ハンドル

を使用して構築された を介して InteractiveBrowserCredential 対話形式で InteractiveBrowserCredentialBrokerOptions認証する場合は、要求ウィンドウで認証ダイアログが正しく表示されるように、親ウィンドウ ハンドルが必要です。 デバイス上のグラフィカル ユーザー インターフェイスのコンテキストでは、ウィンドウ ハンドルはオペレーティング システムが各ウィンドウに割り当てる一意の識別子です。 Windows オペレーティング システムの場合、このハンドルは特定のウィンドウへの参照として機能する整数値です。

Microsoft アカウント (MSA) パススルー

Microsoft アカウント (MSA) は、ユーザーが Microsoft サービスにアクセスするために作成した個人アカウントです。 MSA パススルーは従来の構成であり、ユーザーは通常 MSA ログインを受け入れないリソースにトークンを取得できます。 この機能は、ファースト パーティのアプリケーションでのみ使用できます。 MSA パススルーを使用するように構成されたアプリケーションで認証するユーザーは、 プロパティを InteractiveBrowserCredentialBrokerOptions.IsLegacyMsaPassthroughEnabled に設定して true 、これらの個人アカウントを WAM で一覧表示できるようにします。

リダイレクト URI

Microsoft Entraアプリケーションは、リダイレクト URI に依存して、ユーザーがログインした後に認証応答を送信する場所を決定します。 WAM によるブローカー認証を有効にするには、次のパターンに一致するリダイレクト URI をアプリケーションに登録する必要があります。

ms-appx-web://Microsoft.AAD.BrokerPlugin/{client_id}

例

InteractiveBrowserCredentialシステム認証ブローカーを使用するように を構成する

この例では、ブローカー認証を InteractiveBrowserCredential 有効にするために特殊化されたオプションの種類 InteractiveBrowserCredentialBrokerOptions を使用して を構成する方法を示します。

IntPtr parentWindowHandle = GetForegroundWindow();

// Create an interactive browser credential which will use the system authentication broker
var credential = new InteractiveBrowserCredential(new InteractiveBrowserCredentialBrokerOptions(parentWindowHandle));

// Use the credential to authenticate a secret client
var client = new SecretClient(new Uri("https://myvault.vault.azure.net/"), credential);

トラブルシューティング

さまざまな障害シナリオを診断する方法の詳細については、 トラブルシューティング ガイド を参照してください。

エラー処理

認証に起因するエラーは、サービスに対する要求を行う任意のサービス クライアントメソッドで発生する可能性があります。 これは、資格情報からトークンが初めて要求されるときがサービスの最初の呼び出しであり、後続の呼び出しでトークンを更新する必要がある可能性があるためです。 これらのエラーをサービス クライアントの Azure Identity クラスのエラーと区別するために、 AuthenticationFailedException 例外メッセージのエラーの原因と、場合によってはエラー メッセージに詳細を付けて を発生させます。 アプリケーションによっては、これらのエラーが回復可能な場合とそうでない場合があります。

using Azure.Identity;
using Azure.Security.KeyVault.Secrets;

// Create a secret client using the DefaultAzureCredential
var client = new SecretClient(new Uri("https://myvault.vault.azure.net/"), new DefaultAzureCredential());

try
{
    KeyVaultSecret secret = await client.GetSecretAsync("secret1");
}
catch (AuthenticationFailedException e)
{
    Console.WriteLine($"Authentication Failed. {e.Message}");
}

Microsoft Entra ID またはマネージド ID エンドポイントへの要求の失敗に起因するエラーの処理の詳細については、承認エラー コードに関するMicrosoft Entra ID のドキュメントを参照してください。

ログ記録

Azure Identity ライブラリには、Azure SDK の残りの部分と同じ ログ機能 が用意されています。

認証の問題をデバッグするのに役立つログを表示する最も簡単な方法は、コンソールログを有効にすることです。

// Setup a listener to monitor logged events.
using AzureEventSourceListener listener = AzureEventSourceListener.CreateConsoleLogger();

すべての資格情報は、SDK の他のクライアントと同じ方法で診断オプションを使用して構成できます。

DefaultAzureCredentialOptions options = new DefaultAzureCredentialOptions()
{
    Diagnostics =
    {
        LoggedHeaderNames = { "x-ms-request-id" },
        LoggedQueryParameters = { "api-version" },
        IsLoggingContentEnabled = true
    }
};

注意: Azure Identity ライブラリの要求と応答には、機密情報が含まれています。 アカウントのセキュリティを損なわないように出力をカスタマイズするときは、ログを保護するために予防措置を講じなければなりません。

スレッド セーフ

すべての資格情報インスタンス メソッドがスレッド セーフであり、相互に独立していることを保証します (ガイドライン)。 これにより、資格情報インスタンスを再利用するという推奨事項は、スレッド間でも常に安全になります。

その他の概念

クライアント オプション | 応答 | へのアクセス診断 | あざける | クライアントの有効期間

次のステップ

Azure Identity での認証をサポートするクライアント ライブラリ

ここに記載されているクライアント ライブラリの多くは、 と Azure Identity ライブラリを使用TokenCredentialした認証をサポートしています。 また、追加のドキュメントやサンプルなど、その使用方法の詳細を確認できるリンクもあります。

の既知の問題

このライブラリでは、現在 、AAD B2C サービスに関連するシナリオはサポートされていません。

Azure.Identity ライブラリの現在開いている問題については、 こちらを参照してください。

共同作成

このプロジェクトでは、共同作成と提案を歓迎しています。 ほとんどの共同作成では、共同作成者使用許諾契約書 (CLA) にご同意いただき、ご自身の共同作成内容を使用する権利を Microsoft に供与する権利をお持ちであり、かつ実際に供与することを宣言していただく必要があります。 詳細については、 https://cla.microsoft.com を参照してください。

pull request を送信すると、CLA を提供して PR (ラベル、コメントなど) を適宜装飾する必要があるかどうかを CLA ボットが自動的に決定します。 ボットによって提供される手順にそのまま従ってください。 この操作は、Microsoft の CLA を使用するすべてのリポジトリについて、1 回だけ行う必要があります。

このプロジェクトでは、Microsoft オープン ソースの倫理規定を採用しています。 詳しくは、「Code of Conduct FAQ (倫理規定についてよくある質問)」を参照するか、opencode@microsoft.com 宛てに質問またはコメントをお送りください。