.NET 用アプリ認証クライアントライブラリ - バージョン 1.6.0

[アーティクル]
04/03/2023

Note

Microsoft.Azure.Services.AppAuthentication は廃止され、サポートも保守も終了しました。これは、.NET、Java、TypeScript、Python で使用できる Azure Identity クライアントライブラリ に置き換えられます。 Azure Identity への移行方法の詳細については、Azure Identityに関する記事を参照してください。

サービスプリンシパルを使用して Azure サービスに対して認証するには、Azure Active Directory (Azure AD) 資格情報 (共有シークレットまたは証明書) が必要です。

このような資格情報を管理することは困難な場合があります。資格情報をソースファイルまたは構成ファイルに含めて、アプリにバンドルしたくなります。 .NET 用の Microsoft.Azure.Services.AppAuthentication ライブラリを使うと、この問題が簡略化されます。これにより、ローカルでの開発中は認証に開発者の資格情報が使用されます。その後、ソリューションを Azure にデプロイすると、このライブラリは、自動的にアプリケーションの資格情報に切り替わります。ローカル開発時に開発者の資格情報を使用すると、Azure AD 資格情報を作成したり、開発者間で資格情報を共有したりする必要がないため、より安全です。

Microsoft.Azure.Services.AppAuthentication ライブラリで認証が自動的に管理されます。これにより、資格情報ではなく、ソリューションに重点を置くことができます。これは、Microsoft Visual Studio、Azure CLI、Azure AD の統合認証を使用したローカル開発をサポートしています。マネージド ID をサポートする Azure リソースにデプロイすると、ライブラリでは Azure リソースのマネージド ID が自動的に使用されます。コードまたは構成を変更する必要はありません。マネージド ID を利用できない場合や、ローカル開発中に開発者のセキュリティコンテキストを特定できない場合、ライブラリでは、Azure AD のクライアントの資格情報を直接使用することもサポートされます。

ソースコード | パッケージ (nuget) | Azure Active Directory のドキュメント

前提条件

Visual Studio 2019 または Visual Studio 2017 v15.5.
Visual Studio 用のアプリ認証拡張機能。Visual Studio 2017 Update 5 用の個別の拡張機能として入手可能であり、Update 6 以降の製品にはバンドルされています。 Update 6 以降では、Visual Studio インストーラー内から [Azure Development tools]\(Azure 開発ツール\) を選択して、アプリ認証拡張機能のインストールを確認できます。

ライブラリの使用

.NET アプリケーションの場合、マネージド ID を利用する最も簡単な方法は、Microsoft.Azure.Services.AppAuthentication パッケージを経由する方法です。次のようにして使い始めることができます。

[ツール]>[NuGet パッケージマネージャー]>[ソリューションの NuGet パッケージの管理] を選択して、Microsoft.Azure.Services.AppAuthentication および Microsoft.Azure.KeyVault NuGet パッケージに対する参照をプロジェクトに追加します。

AzureServiceTokenProvider を使用して、次の例のように、Azure クライアントのアクセストークンの要求を簡略化します。

using Microsoft.Azure.Services.AppAuthentication;
using Microsoft.Azure.KeyVault;
using System.Data.SqlClient

// Use AzureServiceTokenProvider’s built-in callback for KeyVaultClient
var azureServiceTokenProvider = new AzureServiceTokenProvider();
var kv = new KeyVaultClient(new KeyVaultClient.AuthenticationCallback(azureServiceTokenProvider.KeyVaultTokenCallback));

// Request an access token for SqlConnection
sqlConnection = new SqlConnection(YourConnectionString)) 
{ 
    sqlConnection.AccessToken = await azureServiceTokenProvider.GetAccessTokenAsync("https://database.windows.net"); 
    sqlConnection.Open(); 
}

スレッドセーフな AzureServiceTokenProvider クラスは、トークンをメモリにキャッシュし、有効期限の直前に Azure AD から取得します。これは、GetAccessTokenAsync メソッドを呼び出す前に、トークンの有効期限を確認する必要がないことを意味します。

GetAccessTokenAsync メソッドには、リソース識別子が必要です。 Microsoft Azure サービスの詳細については、「Azure リソースのマネージド ID とは」を参照してください。

ローカル開発用における認証

ローカル開発向けの主な認証シナリオには、Azure サービスに対する認証とカスタムサービスに対する認証の 2 つがあります。

Azure サービスに対する認証

ローカルコンピューターでは、Azure リソースのマネージド ID はサポートされません。その結果、Microsoft.Azure.Services.AppAuthentication ライブラリは、ローカル開発環境で実行するために開発者の資格情報を使用します。ソリューションを Azure にデプロイすると、このライブラリは、マネージド ID を使用して OAuth 2.0 クライアント資格情報の付与フローに切り替えます。この方法では、同じコードをローカルでもリモートでも、心配せずにテストできます。

ローカル開発では、AzureServiceTokenProvider は、Visual Studio、Azure コマンドラインインターフェイス (CLI)、Azure AD 統合認証を使用してトークンをフェッチします。このライブラリは、各オプションを順番に試行し、最初に成功したオプションを使用します。どのオプションも機能しない場合、詳しい情報と共に AzureServiceTokenProviderException 例外がスローされます。

Visual Studio での認証

Visual Studio を使用して認証するには:

Visual Studio にサインインし、 [ツール]>[オプション] を使用して [オプション] を開きます。
[Azure サービス認証] を選択し、ローカル開発用のアカウントを選んでから [OK] を選択します。

トークンプロバイダーファイルに関連するエラーなど、Visual Studio の使用に関して問題が発生した場合は、前述の手順をよくご確認ください。

開発者トークンの再認証が必要になる場合があります。これを行うには、[ ツール>オプション] を選択し、[ Azure サービス認証] を選択します。選択したアカウントの下にある [再認証] リンクを探します。それを選択して認証してください。

Azure CLI での認証

ローカル開発で Azure CLI を使用する場合は、バージョンが Azure CLI v 2.0.12 以降であることを確認してください。

Azure CLI を使用するには:

Windows タスクバーで Azure CLI を検索して、Microsoft Azure コマンドプロンプトを開きます。
Azure portal にサインインします。az login で Azure にサインインします。
「az account get-access-token --resource https://vault.azure.net」と入力して、アクセスを確認します。エラーが発生した場合は、適切なバージョンの Azure CLI が正しくインストールされていることを確認してください。

Azure CLI が既定のディレクトリにインストールされていない場合は、AzureServiceTokenProvider で Azure CLI のパスが見つけられないことを報告するエラーが発生することがあります。 AzureCLIPath 環境変数を使用して、Azure CLI のインストールフォルダーを定義してください。 AzureServiceTokenProvider は、必要な場合に、AzureCLIPath 環境変数に指定されたディレクトリを Path 環境変数に追加します。
複数のアカウントを使用して Azure CLI にサインインしている場合、または使用しているアカウントで複数のサブスクリプションにアクセスできる場合は、使用するサブスクリプションを指定する必要があります。 コマンド az account set --subscription を入力します。

このコマンドは、エラーが発生した場合にのみ出力を生成します。現在のアカウント設定を確認するには、コマンド az account list を入力します。

Azure AD 認証を使用した認証

Azure AD の認証を使用するには、次の点を確認します。

ご利用のオンプレミスの Active Directory が Azure AD と同期していること。詳細については、「Azure Active Directory でのハイブリッド ID とは」を参照してください。
ご自分のコードが、ドメインに参加しているコンピューターで実行されていること。

カスタムサービスに対する認証

サービスから Azure サービスを呼び出すとき、Azure サービスがユーザーとアプリケーションの両方にアクセスすることを許可するので、前の手順が動作します。

カスタムサービスを呼び出すサービスを作成するときには、ローカル開発における認証に Azure AD のクライアント資格情報を使用します。 2 つのオプションがあります。

次のようにサービスプリンシパルを使用して Azure にサインインします。
1. サービスプリンシパルを作成する。詳細については、「Azure CLI で Azure サービスプリンシパルを作成する」をご覧ください。
2. Azure CLI を使用して、次のコマンドでサインインします。
```
az login --service-principal -u <principal-id> --password <password> --tenant <tenant-id> --allow-no-subscriptions
```
  サービスプリンシパルには、サブスクリプションへのアクセス権がない可能性があるため、--allow-no-subscriptions 引数を使用します。
環境変数を使用して、サービスプリンシパルの詳細を指定します。詳細については、「サービスプリンシパルを使用してアプリケーションを実行する」を参照してください。

Azure にサインインした後、AzureServiceTokenProvider ではサービスプリンシパルを使用して、ローカル開発用のトークンを取得します。

この方法は、ローカル開発に対してのみ適用されます。ソリューションを Azure にデプロイすると、ライブラリは管理 ID 認証に切り替わります。

マネージド ID またはユーザー割り当て ID を使用してアプリケーションを実行する

Azure App Service 上またはマネージド ID が有効な Azure VM 上でコードを実行すると、ライブラリは自動的にマネージド ID を使用します。コードの変更は必要ありませんが、マネージド ID には、アクセスを試みるリソースに対するアクセス許可が必要です。たとえば、マネージド ID がキーコンテナー内のシークレットにアクセスするには、アクセスポリシーが必要です。

また、ユーザー割り当て ID を使用して認証することもできます。ユーザー割り当て ID の詳細については、「Azure リソースのマネージド ID とは」を参照してください。ユーザー割り当て ID を使用して認証するには、接続文字列内でユーザー割り当て ID のクライアント ID を指定する必要があります。接続文字列は、「接続文字列のサポート」で指定されています。

サービスプリンシパルを使用してアプリケーションを実行する

認証のために、Azure AD のクライアント資格情報を作成する必要がある場合があります。この状況は、次の例で発生する可能性があります。

コードはローカル開発環境で実行されるが、開発者の ID の下ではない。たとえば、Service Fabric では、ローカル開発用に NetworkService アカウントを使用します。
コードはローカル開発環境で実行されるが、開発者自身はカスタムサービスに対して認証を行っているため、自分の開発者 ID は使用できない。
コードが、Azure Batch など、Azure リソースのマネージド ID がまだサポートされていない Azure コンピューティングリソース上で実行されている。

サービスプリンシパルを使用してアプリケーションを実行する方法は、主に 3 つあります。そのいずれかを使用するには、最初にサービスプリンシパルを作成する必要があります。詳細については、「Azure CLI で Azure サービスプリンシパルを作成する」をご覧ください。

ローカルキーストア内の証明書を使用して Azure AD にサインインする

Azure CLI の az ad sp create-for-rbac コマンドを使用してサービスプリンシパル証明書を作成します。
```
az ad sp create-for-rbac --create-cert
```
このコマンドでは、ホームディレクトリに格納される .pem ファイル (秘密キー) が作成されます。コマンドを使用して、.pem ファイルを PFX 証明書に変換します。
```
openssl pkcs12 -export -in test.pem -out test.pfx
```
AzureServicesAuthConnectionString という名前の環境変数を次の値に設定します。
```
RunAs=App;AppId={AppId};TenantId={TenantId};CertificateThumbprint={Thumbprint};
      CertificateStoreLocation={CertificateStore}
```
{AppId} 、 {TenantId} 、 {Thumbprint} は、手順 1 で生成された値に置き換えます。デプロイ計画に基づき、 {CertificateStore} を LocalMachine または CurrentUser のいずれかで置き換えます。
アプリケーションを実行します。

共有シークレット資格情報を使用して Azure AD にサインインする

Azure CLI の az ad sp create-for-rbac コマンドを --sdk-auth パラメーターと共に使用して、パスワードでサービスプリンシパル証明書を作成します。
```
az ad sp create-for-rbac --sdk-auth
```
AzureServicesAuthConnectionString という名前の環境変数を次の値に設定します。
```
RunAs=App;AppId={AppId};TenantId={TenantId};AppKey={ClientSecret}
```
{AppId} 、 {TenantId} 、 {ClientSecret} は、手順 1 で生成された値に置き換えます。
アプリケーションを実行します。

すべてを適切に設定した後は、それ以上のコード変更は必要ありません。 AzureServiceTokenProvider では、環境変数と証明書を使用して Azure AD に対する認証が行われます。

Key Vault 内の証明書を使用して Azure AD にサインインする

このオプションでは、サービスプリンシパルのクライアント証明書を Key Vault に格納し、それをサービスプリンシパルの認証に使用できます。このオプションは、次のシナリオに利用できます。

明示的なサービスプリンシパルを使用して認証すると共に、サービスプリンシパル資格情報を安全な状態でキーコンテナー内に保管しておくことが必要なローカル認証。開発者アカウントからキーコンテナーにアクセスできる必要があります。
明示的な資格情報を使用すると共に、サービスプリンシパル資格情報を安全な状態でキーコンテナー内に保管しておくことが必要な Azure からの認証。クロステナントシナリオでこのオプションを使用することができます。マネージド ID でキーコンテナーにアクセスできる必要があります。

マネージド ID または開発者 ID には、Key Vault からクライアント証明書を取得するためのアクセス許可が必要です。取得した証明書は、AppAuthentication ライブラリによってサービスプリンシパルのクライアント証明書として使用されます。

サービスプリンシパル認証にクライアント証明書を使用するには:

サービスプリンシパル証明書を作成し、キーコンテナーに自動的に格納します。 Azure CLI az ad sp create-for-rbac --keyvault keyvaultname <> --cert <certificatename> --create-cert --skip-assignment コマンドを使用します。
```
az ad sp create-for-rbac --keyvault <keyvaultname> --cert <certificatename> --create-cert --skip-assignment
```
証明書の識別子は、https://<keyvaultname>.vault.azure.net/secrets/<certificatename> 形式の URL になります。
次の接続文字列内の {KeyVaultCertificateSecretIdentifier} を証明書の識別子に置き換えます。
```
RunAs=App;AppId={TestAppId};KeyVaultCertificateSecretIdentifier={KeyVaultCertificateSecretIdentifier}
```
たとえば、キーコンテナーの名前が myKeyVault で、myCert という名前の証明書を作成した場合、証明書の識別子は次のようになります。
```
RunAs=App;AppId={TestAppId};KeyVaultCertificateSecretIdentifier=https://myKeyVault.vault.azure.net/secrets/myCert
```

接続文字列のサポート

既定では、トークンを取得するために、AzureServiceTokenProvider によって、次の認証方法が順番に試行されます。

プロセスを制御するには、接続文字列を AzureServiceTokenProvider のコンストラクターに渡すか、AzureServicesAuthConnectionString 環境変数に指定して、使用します。次のオプションがサポートされています。

接続文字列のオプション	シナリオ	説明
`RunAs=Developer;DeveloperTool=AzureCli`	ローカル開発	`AzureServiceTokenProvider` では、AzureCli を使用してトークンを取得します。
`RunAs=Developer;DeveloperTool=VisualStudio`	ローカル開発	`AzureServiceTokenProvider` では、Visual Studio を使用してトークンを取得します。
`RunAs=CurrentUser`	ローカル開発	.NET Core ではサポートされていません。 `AzureServiceTokenProvider` では、Azure AD 統合認証を使用してトークンを取得します。
`RunAs=App`	Azure リソースのマネージド ID	`AzureServiceTokenProvider` では、マネージド ID を使用してトークンを取得します。
`RunAs=App;AppId={ClientId of user-assigned identity}`	Azure リソースのユーザー割り当て ID	`AzureServiceTokenProvider` では、ユーザー割り当て ID を使用してトークンを取得します。
`RunAs=App;AppId={TestAppId};KeyVaultCertificateSecretIdentifier={KeyVaultCertificateSecretIdentifier}`	カスタムサービスの認証	`KeyVaultCertificateSecretIdentifier` は証明書のシークレット識別子です。
`RunAs=App;AppId={AppId};TenantId={TenantId};CertificateThumbprint={Thumbprint};CertificateStoreLocation={LocalMachine or CurrentUser}`	サービスプリンシパル	`AzureServiceTokenProvider` は証明書を使用して Azure AD からトークンを取得します。
`RunAs=App;AppId={AppId};TenantId={TenantId};CertificateSubjectName={Subject};CertificateStoreLocation={LocalMachine or CurrentUser}`	サービスプリンシパル	`AzureServiceTokenProvider` は証明書を使用して Azure AD からトークンを取得します
`RunAs=App;AppId={AppId};TenantId={TenantId};AppKey={ClientSecret}`	サービスプリンシパル	`AzureServiceTokenProvider` はシークレットを使用して Azure AD からトークンを取得します。

サンプル

Microsoft.Azure.Services.AppAuthentication ライブラリの動作を確認する場合は、次のコードサンプルを参照してください。

AppAuthentication のトラブルシューティング

ローカル開発時の一般的な問題

Azure CLI がインストールされていないか、ログインしていないか、または最新バージョンがない

az account get-access-token を実行して、Azure CLI にトークンが表示されるかどうかを確認します。 そのようなプログラムが見つからない場合は、最新バージョンの Azure CLI をインストールします。サインインを要求される場合があります。

AzureServiceTokenProvider で Azure CLI のパスを見つけることができない

AzureServiceTokenProvider では、既定のインストール場所で Azure CLI が検索されます。 Azure CLI が見つからない場合は、環境変数 AzureCLIPath を Azure CLI インストールフォルダーに設定します。 AzureServiceTokenProvider によって、環境変数が Path 環境変数に追加されます。

複数のアカウントを使用して Azure CLI にログインしているか、同じアカウントに複数のテナント内のサブスクリプションへのアクセス権があるか、ローカル開発中に呼び出そうとしたときにアクセス拒否エラーが発生する

Azure CLI を使って、使用するアカウントがあるものに既定のサブスクリプションを設定します。サブスクリプションは、アクセスするリソースと同じテナントに存在する必要があります: az account set --subscription [subscription-id] 。出力が表示されない場合は、成功しています。 az account list を使用して、適切なアカウントが既定値になっていることを確認します。

環境間の一般的な問題

未承認のアクセス、アクセスの拒否、禁止、または同様のエラー

使用されているプリンシパルに、アクセスしようとしているリソースへのアクセス権がありません。ユーザーアカウントまたは App Service の MSI に、リソースへの "共同作成者" アクセス権を付与します。これは、サンプルをローカルコンピューターで実行しているか、Azure の App Service にデプロイしたかによって異なります。キーコンテナーなどの一部のリソースには、ユーザー、アプリ、グループなどのプリンシパルへのアクセス権の付与に使用する独自のアクセスポリシーもあります。

Azure App Service にデプロイするときの一般的な問題

App Service に対してマネージド ID が設定されていない

Kudu デバッグコンソールを使用して、環境変数 MSI_ENDPOINT および MSI_SECRET が存在することを確認します。これらの環境変数が存在しない場合は、App Service に対してマネージド ID が有効になりません。

IIS を使用してローカルにデプロイするときの一般的な問題

IIS 内でアプリをデバッグするときにトークンを取得できない

既定では、AppAuth は IIS の別のユーザーコンテキストで実行されます。そのため、開発者 ID を使用してアクセストークンを取得するためのアクセス権はありません。次の 2 つの手順に従って、ユーザーコンテキストで実行するように IIS を構成できます。

現在のユーザーアカウントとして実行するように Web アプリのアプリケーションプールを構成します。詳細については、こちらをご覧ください。
"SetProfileEnvironment" を "True" に構成します。詳細については、こちらをご覧ください。
- %windir%\System32\inetsrv\config\applicationHost.config にアクセスします
- "setProfileEnvironment" を検索します。 "False" に設定されている場合は、"True" に変更します。存在しない場合は、processModel 要素 (/configuration/system.applicationHost/applicationPools/applicationPoolDefaults/processModel/@setProfileEnvironment) に属性として追加し、"True" に設定します。
詳細については、「Azure リソースの管理 ID について」を参照してください。
Azure AD の認証シナリオについて詳細を参照する。

次の方法で共有

.NET 用アプリ認証クライアントライブラリ - バージョン 1.6.0

前提条件

ライブラリの使用

ローカル開発用における認証

Azure サービスに対する認証

Visual Studio での認証

Azure CLI での認証

Azure AD 認証を使用した認証

カスタムサービスに対する認証

マネージド ID またはユーザー割り当て ID を使用してアプリケーションを実行する

サービスプリンシパルを使用してアプリケーションを実行する

ローカルキーストア内の証明書を使用して Azure AD にサインインする

共有シークレット資格情報を使用して Azure AD にサインインする

Key Vault 内の証明書を使用して Azure AD にサインインする

接続文字列のサポート

サンプル

AppAuthentication のトラブルシューティング

ローカル開発時の一般的な問題

Azure CLI がインストールされていないか、ログインしていないか、または最新バージョンがない

AzureServiceTokenProvider で Azure CLI のパスを見つけることができない

複数のアカウントを使用して Azure CLI にログインしているか、同じアカウントに複数のテナント内のサブスクリプションへのアクセス権があるか、ローカル開発中に呼び出そうとしたときにアクセス拒否エラーが発生する

環境間の一般的な問題

未承認のアクセス、アクセスの拒否、禁止、または同様のエラー

Azure App Service にデプロイするときの一般的な問題

App Service に対してマネージド ID が設定されていない

IIS を使用してローカルにデプロイするときの一般的な問題

IIS 内でアプリをデバッグするときにトークンを取得できない

その他のリソース

次の方法で共有

.NET 用アプリ認証クライアント ライブラリ - バージョン 1.6.0

前提条件

ライブラリの使用

ローカル開発用における認証

Azure サービスに対する認証

Visual Studio での認証

Azure CLI での認証

Azure AD 認証を使用した認証

カスタム サービスに対する認証

マネージド ID またはユーザー割り当て ID を使用してアプリケーションを実行する

サービス プリンシパルを使用してアプリケーションを実行する

ローカル キーストア内の証明書を使用して Azure AD にサインインする

共有シークレット資格情報を使用して Azure AD にサインインする

Key Vault 内の証明書を使用して Azure AD にサインインする

接続文字列のサポート

サンプル

AppAuthentication のトラブルシューティング

ローカル開発時の一般的な問題

Azure CLI がインストールされていないか、ログインしていないか、または最新バージョンがない

AzureServiceTokenProvider で Azure CLI のパスを見つけることができない

複数のアカウントを使用して Azure CLI にログインしているか、同じアカウントに複数のテナント内のサブスクリプションへのアクセス権があるか、ローカル開発中に呼び出そうとしたときにアクセス拒否エラーが発生する

環境間の一般的な問題

未承認のアクセス、アクセスの拒否、禁止、または同様のエラー

Azure App Service にデプロイするときの一般的な問題

App Service に対してマネージド ID が設定されていない

IIS を使用してローカルにデプロイするときの一般的な問題

IIS 内でアプリをデバッグするときにトークンを取得できない

その他のリソース

.NET 用アプリ認証クライアントライブラリ - バージョン 1.6.0

カスタムサービスに対する認証

サービスプリンシパルを使用してアプリケーションを実行する

ローカルキーストア内の証明書を使用して Azure AD にサインインする