.NET を使用した Azure Key Vault に対するサービス間認証Service-to-service authentication to Azure Key Vault using .NET

Azure Key Vault の認証を受けるには、Azure Active Directory (AD) の資格情報として、共有シークレットまたは証明書のいずれかが必要です。To authenticate to Azure Key Vault, you need an Azure Active Directory (AD) credential, either a shared secret or a certificate. このような資格情報を管理するのは煩雑な作業になるため、資格情報をソース ファイルまたは構成ファイルに組み込んでアプリにバンドルしたくなります。Managing such credentials can be difficult and it's tempting to bundle credentials into an app by including them in source or configuration files.

.NET 用の Microsoft.Azure.Services.AppAuthentication ライブラリを使うと、この問題が簡略化されます。The Microsoft.Azure.Services.AppAuthentication for .NET library simplifies this problem. これにより、ローカルでの開発中は認証に開発者の資格情報が使用されます。It uses the developer's credentials to authenticate during local development. その後、ソリューションを Azure にデプロイすると、このライブラリは、自動的にアプリケーションの資格情報に切り替わります。When the solution is later deployed to Azure, the library automatically switches to application credentials.

ローカルでの開発中に開発者の資格情報を使用するという方法は、Azure AD 資格情報を作成したり、開発者間で資格情報を共有したりする必要がないため、セキュリティの面で有利です。Using developer credentials during local development is more secure because you do not need to create Azure AD credentials or share credentials between developers.

Microsoft.Azure.Services.AppAuthentication ライブラリによって認証が自動的に管理される結果、資格情報ではなくソリューションに重点を置くことができます。The Microsoft.Azure.Services.AppAuthentication library manages authentication automatically, which in turn allows you to focus on your solution, rather than your credentials.

Microsoft.Azure.Services.AppAuthentication ライブラリでは、Microsoft Visual Studio、Azure CLI、Azure AD の統合認証を使用したローカル開発がサポートされます。The Microsoft.Azure.Services.AppAuthentication library supports local development with Microsoft Visual Studio, Azure CLI, or Azure AD Integrated Authentication. マネージド ID をサポートする Azure リソースにデプロイすると、ライブラリでは Azure リソースのマネージド ID が自動的に使用されます。When deployed to an Azure resource that supports a managed identity, the library automatically uses managed identities for Azure resources. コードまたは構成を変更する必要はありません。No code or configuration changes are required. マネージド ID を利用できない場合や、ローカル開発中に開発者のセキュリティ コンテキストを特定できない場合、このライブラリは、Azure AD のクライアントの資格情報を直接使用することもサポートします。The library also supports direct use of Azure AD client credentials when a managed identity is not available, or when the developer's security context cannot be determined during local development.

ライブラリの使用Using the library

.NET アプリケーションの場合、マネージド ID を利用する最も簡単な方法は、Microsoft.Azure.Services.AppAuthentication パッケージを経由する方法です。For .NET applications, the simplest way to work with a managed identity is through the Microsoft.Azure.Services.AppAuthentication package. 次のようにして使い始めることができます。Here's how to get started:

  1. Microsoft.Azure.Services.AppAuthentication および Microsoft.Azure.KeyVault NuGet パッケージに対する参照をアプリケーションに追加します。Add references to the Microsoft.Azure.Services.AppAuthentication and Microsoft.Azure.KeyVault NuGet packages to your application.

  2. 次のコードを追加します。Add the following code:

    using Microsoft.Azure.Services.AppAuthentication;
    using Microsoft.Azure.KeyVault;
    
    // Instantiate a new KeyVaultClient object, with an access token to Key Vault
    var azureServiceTokenProvider1 = new AzureServiceTokenProvider();
    var kv = new KeyVaultClient(new KeyVaultClient.AuthenticationCallback(azureServiceTokenProvider1.KeyVaultTokenCallback));
    
    // Optional: Request an access token to other Azure services
    var azureServiceTokenProvider2 = new AzureServiceTokenProvider();
    string accessToken = await azureServiceTokenProvider2.GetAccessTokenAsync("https://management.azure.com/").ConfigureAwait(false);
    

AzureServiceTokenProvider クラスは、トークンをメモリ内にキャッシュし、有効期限の直前に Azure AD から取得します。The AzureServiceTokenProvider class caches the token in memory and retrieves it from Azure AD just before expiration. このため、GetAccessTokenAsync メソッドを呼び出す前に有効期限を確認する必要がなくなります。Consequently, you no longer have to check the expiration before calling the GetAccessTokenAsync method. トークンが必要になった時点で、いつでもメソッドを呼び出すことができます。Just call the method when you want to use the token.

GetAccessTokenAsync メソッドには、リソース識別子が必要です。The GetAccessTokenAsync method requires a resource identifier. 詳細については、「 Azure サービスはAzure リソースのマネージド ID をサポートしますか」を参照してください。To learn more, see which Azure services support managed identities for Azure resources.

サンプルSamples

次のサンプルは、Microsoft.Azure.Services.AppAuthentication ライブラリの動作について示しています。The following samples show the Microsoft.Azure.Services.AppAuthentication library in action:

  1. 実行時にマネージド ID を使用して Azure Key Vault からシークレットを取得するUse a managed identity to retrieve a secret from Azure Key Vault at runtime

  2. マネージド ID を使用して Azure VM から Azure Resource Manager テンプレートをプログラムでデプロイするProgrammatically deploy an Azure Resource Manager template from an Azure VM with a managed identity.

  3. .NET Core サンプルとマネージド ID を使用して、Azure Linux VM から Azure サービスを呼び出すUse .NET Core sample and a managed identity to call Azure services from an Azure Linux VM.

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

ローカル開発の場合、次の 2 つの主要な認証シナリオがあります。For local development, there are two primary authentication scenarios:

Azure サービスに対する認証Authenticating to Azure Services

ローカルコンピューターは Azure リソースのマネージド ID をサポートしません。Local machines do not support managed identities for Azure resources. その結果、Microsoft.Azure.Services.AppAuthentication ライブラリは、ローカル開発環境で実行するために開発者の資格情報を使用します。As a result, the Microsoft.Azure.Services.AppAuthentication library uses your developer credentials to run in your local development environment. ソリューションを Azure にデプロイすると、このライブラリは、マネージド ID を使用して OAuth 2.0 クライアント資格情報の付与フローに切り替えます。When the solution is deployed to Azure, the library uses a managed identity to switch to an OAuth 2.0 client credential grant flow. このため、同じコードをローカルでも、リモートでも、心配せずにテストできます。This means you can test the same code locally and remotely without worry.

ローカル開発では、AzureServiceTokenProvider は、Visual StudioAzure コマンド ライン インターフェイス (CLI)、Azure AD 統合認証を使用してトークンをフェッチします。For local development, AzureServiceTokenProvider fetches tokens using Visual Studio, Azure command-line interface (CLI), or Azure AD Integrated Authentication. このライブラリは、各オプションを順番に試行し、最初に成功したオプションを使用します。Each option is tried sequentially and the library uses the first option that succeeds. どのオプションも機能しない場合、詳しい情報と共に AzureServiceTokenProviderException 例外がスローされます。If no option works, an AzureServiceTokenProviderException exception is thrown with detailed information.

Visual Studio での認証Authenticating with Visual Studio

Visual Studio での認証には次の前提条件があります。Authenticating with Visual Studio has the following prerequisites:

  1. Visual Studio 2017 v15.5 以降。Visual Studio 2017 v15.5 or later.

  2. Visual Studio 用のアプリ認証拡張機能。Visual Studio 2017 Update 5 用の個別の拡張機能として入手可能であり、Update 6 以降の製品にはバンドルされています。The App Authentication extension for Visual Studio, available as a separate extension for Visual Studio 2017 Update 5 and bundled with the product in Update 6 and later. Update 6 以降では、Visual Studio インストーラー内から [Azure Development tools](Azure 開発ツール) を選択して、アプリ認証拡張機能のインストールを確認できます。With Update 6 or later, you can verify the installation of the App Authentication extension by selecting Azure Development tools from within the Visual Studio installer.

Visual Studio にサインインし、 [ツール]  >  [オプション]  >  [Azure サービスの認証] を使用してローカル開発のアカウントを選択します。Sign in to Visual Studio and use Tools > Options > Azure Service Authentication to select an account for local development.

トークン プロバイダー ファイルに関するエラーなど、Visual Studio の使用に関して問題が発生した場合は、これらの手順をよくご確認ください。If you run into problems using Visual Studio, such as errors regarding the token provider file, carefully review these steps.

また、開発者トークンの再認証が必要となる場合もあります。It may also be necessary to reauthenticate your developer token. これを行うには、 [ツール]  >  [オプション] > [Azure サービスの認証]   に移動し、選択したアカウントの下にある [再認証] リンクを探します。To do so, go to Tools > Options>Azure Service Authentication and look for a Re-authenticate link under the selected account. それを選択して認証してください。Select it to authenticate.

Azure CLI での認証Authenticating with Azure CLI

ローカル開発に Azure CLI を使用するには、次のようにします。To use Azure CLI for local development:

  1. Azure CLI v2.0.12 またはそれ以降をインストールします。Install Azure CLI v2.0.12 or later. それより前のバージョンは、アップグレードします。Upgrade earlier versions.

  2. az login を使用して Azure にサインインします。Use az login to sign in to Azure.

az account get-access-token を使用してアクセスを確認します。Use az account get-access-token to verify access. エラーが発生した場合は、手順 1 が正常に完了したことを確認してください。If you receive an error, verify that Step 1 completed successfully.

Azure CLI が既定のディレクトリにインストールされていない場合は、AzureServiceTokenProvider が Azure CLI のパスを見つけられないというエラーが出ることがあります。If Azure CLI is not installed to the default directory, you may receive an error reporting that AzureServiceTokenProvider cannot find the path for Azure CLI. AzureCLIPath 環境変数を使用して、Azure CLI のインストール フォルダーを定義してください。Use the AzureCLIPath environment variable to define the Azure CLI installation folder. AzureServiceTokenProvider は、必要な場合に、AzureCLIPath 環境変数に指定されたディレクトリを Path 環境変数に追加します。AzureServiceTokenProvider adds the directory specified in the AzureCLIPath environment variable to the Path environment variable when necessary.

複数のアカウントを使用して Azure CLI にサインインしている場合、または使用しているアカウントで複数のサブスクリプションにアクセスできる場合は、使用する特定のサブスクリプションを指定する必要があります。If you are signed in to Azure CLI using multiple accounts or your account has access to multiple subscriptions, you need to specify the specific subscription to be used. これを行うには、次のコマンドを使用します。To do so, use:

az account set --subscription <subscription-id>

このコマンドは、エラーが発生した場合にのみ出力を生成します。This command generates output only on failure. 現在のアカウント設定を確認するには、次のコマンドを使用します。To verify the current account settings, use:

az account list

Azure AD 統合認証での認証Authenticating with Azure AD Integrate authentication

Azure AD の認証を使用するには、次の点を確認します。To use Azure AD authentication, verify that:

  • オンプレミスの Active Directory が Azure AD と同期していること。Your on-premises active directory syncs to Azure AD.

  • ご自分のコードが、ドメインに参加しているマシンで実行されていること。Your code is running on a domain-joined machine.

カスタム サービスに対する認証Authenticating to custom services

サービスから Azure サービスを呼び出すとき、Azure サービスがユーザーとアプリケーションの両方にアクセスすることを許可するので、前の手順が動作します。When a service calls Azure services, the previous steps work because Azure services allow access to both users and applications.

カスタム サービスを呼び出すサービスを作成するときには、ローカル開発における認証に Azure AD のクライアント資格情報を使用します。When creating a service that calls a custom service, use Azure AD client credentials for local development authentication. 2 つのオプションがあります。There are two options:

  1. 次のようにサービス プリンシパルを使用して Azure にサインインします。Use a service principal to sign into Azure:

    1. サービス プリンシパルを作成しますCreate a service principal.

    2. Azure CLI を使用してサインインします。Use Azure CLI to sign in:

      az login --service-principal -u <principal-id> --password <password>
         --tenant <tenant-id> --allow-no-subscriptions
      

      サービス プリンシパルには、サブスクリプションへのアクセス権がない可能性があるため、--allow-no-subscriptions 引数を使用します。Because the service principal may not have access to a subscription, use the --allow-no-subscriptions argument.

  2. 環境変数を使用して、サービス プリンシパルの詳細を指定します。Use environment variables to specify service principal details. 詳細については、「サービス プリンシパルを使用してアプリケーションを実行する」を参照してください。For details, see Running the application using a service principal.

Azure にサインインした後、AzureServiceTokenProvider はサービス プリンシパルを使用してローカル開発用のトークンを取得します。Once you've signed in to Azure, AzureServiceTokenProvider uses the service principal to retrieve a token for local development.

これは、ローカル開発に対してのみ適用されます。This applies only to local development. ソリューションを Azure にデプロイすると、ライブラリは管理 ID 認証に切り替わります。When your solution is deployed to Azure, the library switches to a managed identity for authentication.

マネージド ID またはユーザー割り当て ID を使用してアプリケーションを実行するRunning the application using managed identity or user-assigned identity

Azure App Service 上またはマネージド ID が有効な Azure VM 上でコードを実行すると、ライブラリは自動的にマネージド ID を使用します。When you run your code on an Azure App Service or an Azure VM with a managed identity enabled, the library automatically uses the managed identity. コードに変更を加える必要はありません。No code changes are required.

また、ユーザー割り当て ID を使用して認証することもできます。Alternatively, you may authenticate with a user-assigned identity. ユーザー割り当て ID の詳細については、「Azure リソースのマネージド ID とは」を参照してください。For more information on user-assigned identities, see About Managed Identities for Azure resources. 接続文字列については、後述する「接続文字列のサポート」セクションを参照してください。The connection string is specified in the Connection String Support section below.

サービス プリンシパルを使用してアプリケーションを実行するRunning the application using a Service Principal

認証のために、Azure AD のクライアント資格情報を作成する必要がある場合があります。It may be necessary to create an Azure AD Client credential to authenticate. たとえば、次のような場合です。Common examples include:

  1. コードはローカル開発環境で実行されるが、開発者の ID の下ではない。Your code runs on a local development environment, but not under the developer's identity. たとえば、Service Fabric では、ローカル開発用に NetworkService アカウントを使用します。Service Fabric, for example, uses the NetworkService account for local development.

  2. コードはローカル開発環境で実行されるが、開発者自身はカスタム サービスに対して認証を行っているため、自分の開発者 ID は使用できない。Your code runs on a local development environment and you authenticate to a custom service, so you can't use your developer identity.

  3. コードが、Azure Batch など、Azure リソースのマネージド ID をまだサポートしていない Azure コンピューティング リソース上で実行されている。Your code is running on an Azure compute resource that does not yet support managed identities for Azure resources, such as Azure Batch.

Azure AD にサインインするために証明書を使用するには、次のようにします。To use a certificate to sign into Azure AD:

  1. サービス プリンシパルの証明書を作成します。Create a service principal certificate.

  2. LocalMachine または CurrentUser ストアのいずれかに証明書をデプロイします。Deploy the certificate to either the LocalMachine or CurrentUser store.

  3. AzureServicesAuthConnectionString という名前の環境変数を次のように設定します。Set an environment variable named AzureServicesAuthConnectionString to:

    RunAs=App;AppId={AppId};TenantId={TenantId};CertificateThumbprint={Thumbprint};
          CertificateStoreLocation={CertificateStore}
    

    {AppId}{TenantId}{Thumbprint} は、手順 1 で生成された値に置き換えます。Replace {AppId}, {TenantId}, and {Thumbprint} with values generated in Step 1. デプロイ計画に基づき、 {CertificateStore}LocalMachine または CurrentUser のどちらかで置き換えます。Replace {CertificateStore} with either LocalMachine or CurrentUser, based on your deployment plan.

  4. アプリケーションを実行します。Run the application.

Azure AD の共有シークレット資格情報を使用してサインインするには、次のようにします。To sign in using an Azure AD shared secret credential:

  1. パスワード付きのサービス プリンシパルを作成し、それに Key Vault へのアクセス権を付与します。Create a service principal with a password and grant it access to the Key Vault.

  2. AzureServicesAuthConnectionString という名前の環境変数を次のように設定します。Set an environment variable named AzureServicesAuthConnectionString to:

    RunAs=App;AppId={AppId};TenantId={TenantId};AppKey={ClientSecret} 
    

    {AppId}{TenantId}{ClientSecret} は、手順 1 で生成された値に置き換えます。Replace {AppId}, {TenantId}, and {ClientSecret} with values generated in Step 1.

  3. アプリケーションを実行します。Run the application.

すべてを適切に設定した後は、それ以上のコード変更は必要ありません。Once everything's set up correctly, no further code changes are necessary. AzureServiceTokenProvider では、環境変数と証明書を使用して Azure AD に対する認証が行われます。AzureServiceTokenProvider uses the environment variable and the certificate to authenticate to Azure AD.

接続文字列のサポートConnection String Support

既定では、AzureServiceTokenProvider は複数の方法を使用してトークンを取得します。By default, AzureServiceTokenProvider uses multiple methods to retrieve a token.

プロセスを制御するには、接続文字列を AzureServiceTokenProvider のコンストラクターに渡すか、AzureServicesAuthConnectionString 環境変数に指定して、使用します。To control the process, use a connection string passed to the AzureServiceTokenProvider constructor or specified in the AzureServicesAuthConnectionString environment variable.

次のオプションがサポートされています。The following options are supported:

接続文字列オプション  Connection string option シナリオScenario 説明Comments
RunAs=Developer; DeveloperTool=AzureCli ローカル開発Local development AzureServiceTokenProvider は AzureCli を使用してトークンを取得します。AzureServiceTokenProvider uses AzureCli to get token.
RunAs=Developer; DeveloperTool=VisualStudio ローカル開発Local development AzureServiceTokenProvider は Visual Studio を使用してトークンを取得します。AzureServiceTokenProvider uses Visual Studio to get token.
RunAs=CurrentUser ローカル開発Local development AzureServiceTokenProvider は Azure AD 統合認証を使用してトークンを取得します。AzureServiceTokenProvider uses Azure AD Integrated Authentication to get token.
RunAs=App Azure リソースのマネージド IDManaged identities for Azure resources AzureServiceTokenProvider はマネージド ID を使用してトークンを取得します。AzureServiceTokenProvider uses a managed identity to get token.
RunAs=App;AppId={ClientId of user-assigned identity} Azure リソースのユーザー割り当て IDUser-assigned identity for Azure resources AzureServiceTokenProvider はユーザー割り当て ID を使用してトークンを取得します。AzureServiceTokenProvider uses a user-assigned identity to get token.
RunAs=App;AppId={AppId};TenantId={TenantId};CertificateThumbprint={Thumbprint};CertificateStoreLocation={LocalMachine or CurrentUser} サービス プリンシパルService principal AzureServiceTokenProvider は証明書を使用して Azure AD からトークンを取得します。AzureServiceTokenProvider uses certificate to get token from Azure AD.
RunAs=App;AppId={AppId};TenantId={TenantId};CertificateSubjectName={Subject};CertificateStoreLocation={LocalMachine or CurrentUser} サービス プリンシパルService principal AzureServiceTokenProvider は証明書を使用して Azure AD からトークンを取得しますAzureServiceTokenProvider uses certificate to get token from Azure AD
RunAs=App;AppId={AppId};TenantId={TenantId};AppKey={ClientSecret} サービス プリンシパルService principal AzureServiceTokenProvider はシークレットを使用して Azure AD からトークンを取得します。AzureServiceTokenProvider uses secret to get token from Azure AD.

次の手順Next steps