チュートリアル: Web アプリから Azure Key Vault を使用するTutorial: Use Azure Key Vault from a web application

このチュートリアルを使用すると、Azure の Web アプリケーションから Azure Key Vault を使用する方法について学習できます。Use this tutorial to help you learn how to use Azure Key Vault from a web application in Azure. Web アプリで使うために Azure Key Vault のシークレットにアクセスするプロセスを示します。It shows the process of accessing a secret from an Azure Key Vault for use in a web application. その後、このプロセスで、クライアント シークレットではなく証明書を使います。The tutorial then builds on the process and uses a certificate instead of a client secret. このチュートリアルは、Azure 上での Web アプリケーション作成の基本を理解している Web 開発者向けに設計されています。This tutorial is designed for web developers that understand the basics of creating web applications on Azure.

このチュートリアルでは、以下の内容を学習します。In this tutorial, you learn how to:

  • アプリケーションの設定を web.config ファイルに追加するAdd application settings to the web.config file
  • アクセス トークンを取得するメソッドを追加するAdd a method to get an access token
  • アプリケーションの起動時にトークンを取得するRetrieve the token on Application Start
  • 証明書で認証を行うAuthenticate with a certificate

Azure サブスクリプションをお持ちでない場合は、開始する前に 無料アカウント を作成してください。If you don't have an Azure subscription, create a free account before you begin.

前提条件Prerequisites

このチュートリアルを完了するには、以下のものが必要です。To complete this tutorial, you must have the following items:

  • Azure Key Vault のシークレットへの URIA URI to a secret in an Azure Key Vault
  • Key Vault にアクセスできる Azure Active Directory に登録された Web アプリケーションのクライアント ID とクライアント シークレットA Client ID and a Client Secret for a web application registered with Azure Active Directory that has access to your Key Vault
  • Web アプリケーション。A web application. このチュートリアルでは、Web アプリとして Azure に展開される ASP.NET MVC アプリケーションの手順を示します。This tutorial shows the steps for an ASP.NET MVC application deployed in Azure as a Web App.

Azure Key Vault の概要」の手順を完了して、シークレット、クライアント ID、クライアント シークレットの URI を取得し、アプリケーションを登録します。Complete the steps in Get Started with Azure Key Vault to get the URI to a secret, Client ID, Client Secret, and register the application. Web アプリケーションはコンテナーにアクセスするので、Azure Active Directory に登録されている必要があります。The web application will access the vault and must be registered in Azure Active Directory. Key Vault へのアクセス権も必要です。It also needs to have access rights to Key Vault. ない場合は、概要のチュートリアルにあるアプリケーションの登録に関するトピックに戻り、記載されている手順を繰り返します。If not, go back to Register an Application in the Get Started tutorial and repeat the steps listed. Azure Web Apps の作成について詳しくは、「Web Apps の概要」をご覧ください。For more information about creating Azure Web Apps, see Web Apps overview.

このサンプルは、Azure Active Directory ID の手動プロビジョニングに依存します。This sample depends on manually provisioning Azure Active Directory identities. しかしその代わりに、Azure AD の ID を自動的にプロビジョニングする Azure リソースのマネージド ID を使用する必要があります。But you should use Managed identities for Azure resources instead, which automatically provisions Azure AD identities. 詳細については、GitHub のサンプルと、関連する App Service と Functions に関するチュートリアルを参照してください。For more information, see the sample on GitHub and the related App Service and Functions tutorial. Key Vault 固有の「キー コンテナーからシークレットを読み取るように Azure Web アプリケーションを構成するためのチュートリアル」を参照することもできます。You can also look at the Key Vault specific Configure an Azure web application to read a secret from Key Vault tutorial.

NuGet パッケージを追加するAdd NuGet packages

Web アプリケーションでインストールしておく必要のあるパッケージは 2 つあります。There are two packages that your web application needs to have installed.

  • Active Directory 認証ライブラリ: Azure Active Directory と対話してユーザー ID を管理するためのメソッドがあります。Active Directory Authentication Library - has methods for interacting with Azure Active Directory and managing user identity
  • Azure Key Vault ライブラリ: Azure Key Vault と対話するためのメソッドがあります。Azure Key Vault Library - has methods for interacting with Azure Key Vault

どちらのパッケージも、パッケージ マネージャー コンソールで Install-Package コマンドを使用してインストールできます。Both of these packages can be installed using the Package Manager Console using the Install-Package command.

Install-Package Microsoft.IdentityModel.Clients.ActiveDirectory 
Install-Package Microsoft.Azure.KeyVault

web.config を変更するModify web.config

次のように、web.config ファイルに追加する必要のある 3 つのアプリケーション設定があります。There are three application settings that need to be added to the web.config file as follows. セキュリティ レベルを上げるために、Azure portal で実際の値を追加する予定です。We'll be adding the actual values in the Azure portal for an additional level of security.

    <!-- ClientId and ClientSecret refer to the web application registration with Azure Active Directory -->
    <add key="ClientId" value="clientid" />
    <add key="ClientSecret" value="clientsecret" />

    <!-- SecretUri is the URI for the secret in Azure Key Vault -->
    <add key="SecretUri" value="secreturi" />
    <!-- If you aren't hosting your app as an Azure Web App, then you should use the actual ClientId, Client Secret, and Secret URI values -->

アクセス トークンを取得するメソッドを追加するAdd method to get an access token

Key Vault API を使用するには、アクセス トークンが必要です。To use the Key Vault API, you need an access token. Key Vault クライアントによって Key Vault API の呼び出しが処理されますが、アクセス トークンを取得する関数を指定する必要があります。The Key Vault Client handles calls to the Key Vault API but you need to supply it with a function that gets the access token. Azure Active Directory からアクセス トークンを取得するコードの例を次に示します。The following example is code to get an access token from Azure Active Directory. このコードはアプリケーション内の任意の場所に配置できます。This code can go anywhere in your application. Utils クラスまたは EncryptionHelper クラスを追加します。I like to add a Utils or EncryptionHelper class.

//add these using statements
using Microsoft.IdentityModel.Clients.ActiveDirectory;
using System.Threading.Tasks;
using System.Web.Configuration;

//this is an optional property to hold the secret after it is retrieved
public static string EncryptSecret { get; set; }

//the method that will be provided to the KeyVaultClient
public static async Task<string> GetToken(string authority, string resource, string scope)
{
    var authContext = new AuthenticationContext(authority);
    ClientCredential clientCred = new ClientCredential(WebConfigurationManager.AppSettings["ClientId"],
                WebConfigurationManager.AppSettings["ClientSecret"]);
    AuthenticationResult result = await authContext.AcquireTokenAsync(resource, clientCred);

    if (result == null)
        throw new InvalidOperationException("Failed to obtain the JWT token");

    return result.AccessToken;
}
// Using Client ID and Client Secret is a way to authenticate an Azure AD application.
// Using it in your web application allows for a separation of duties and more control over your key management. 
// However, it does rely on putting the Client Secret in your configuration settings.
// For some people, this can be as risky as putting the secret in your configuration settings.

アプリケーション起動時のシークレットの取得Retrieve the secret on Application Start

ここで、Key Vault API を呼び出してシークレットを取得するコードが必要になります。Now we need code to call the Key Vault API and retrieve the secret. 次のコードは、それが必要になる前に呼び出されれば、どこに配置してもかまいません。The following code can be put anywhere as long as it's called before you need to use it. ここでは、このコードを Global.asax の Application Start イベントに配置しました。これにより、コードは起動時に 1 回実行され、アプリケーションでシークレットを使用できるようになります。I've put this code in the Application Start event in the Global.asax so it runs once on start and makes the secret available for the application.

//add these using statements
using Microsoft.Azure.KeyVault;
using System.Web.Configuration;

// I put my GetToken method in a Utils class. Change for wherever you placed your method.
var kv = new KeyVaultClient(new KeyVaultClient.AuthenticationCallback(Utils.GetToken));
var sec = await kv.GetSecretAsync(WebConfigurationManager.AppSettings["SecretUri"]);

//I put a variable in a Utils class to hold the secret for general application use.
Utils.EncryptSecret = sec.Value;

Azure portal でアプリの設定を追加するAdd app settings in the Azure portal

Azure Web アプリでは、Azure portal でアプリ設定の実際の値を追加できます。In the Azure Web App, you can now add the actual values for the AppSettings in the Azure portal. これにより、実際の値は web.config ファイルに存在しなくなりますが、個別のアクセス制御機能があるポータルによって保護されます。By doing this step, the actual values won't be in the web.config but protected via the Portal where you have separate access control capabilities. これらの値は、web.config で入力した値の代わりに使用されます。名前が同じであるかどうかを確認してください。These values will be substituted for the values that you entered in your web.config. Make sure that the names are the same.

Azure Portal に表示されるアプリケーション設定

クライアント シークレットではなく、証明書を使用して認証するAuthenticate with a certificate instead of a client secret

クライアント ID とクライアント シークレットを使って Azure AD アプリの認証を行う方法がわかったので、クライアント ID と証明書を使用してみます。Now that you understand authenticating an Azure AD app using Client ID and Client Secret, let's use a Client ID and a certificate. Azure Web アプリで証明書を使用するには、次の手順のようにします。To use a certificate in an Azure Web App, use the following steps:

  1. 証明書を取得または作成するGet or create a Certificate
  2. 証明書を Azure AD アプリケーションに関連付けるAssociate the certificate with an Azure AD application
  3. 証明書を使用する Web アプリにコードを追加するAdd code to your web app to use the certificate
  4. 証明書を Web アプリに追加するAdd a certificate to your web app

証明書を取得または作成するGet or create a certificate

このチュートリアル用のテスト証明書を作成します。We'll make a test certificate for this tutorial. 次に示すのは、自己署名証明書を作成するためのスクリプトです。Here is a script to create a self-signed certificate. 証明書ファイルの作成先となるディレクトリを変更します。Change directory to where you want the cert files created. 証明書の開始日と終了日には、現在の日付の 1 年後の日付を使用できます。For the beginning and ending date of the certificate, you can use the current date plus one year.

#Create self-signed certificate and export pfx and cer files 
$PfxFilePath = 'KVWebApp.pfx'
$CerFilePath = 'KVWebApp.cer'
$DNSName = 'MyComputer.Contoso.com'
$Password = 'MyPassword"'

$StoreLocation = 'CurrentUser' #be aware that LocalMachine requires elevated privileges
$CertBeginDate = Get-Date
$CertExpiryDate = $CertBeginDate.AddYears(1)

$SecStringPw = ConvertTo-SecureString -String $Password -Force -AsPlainText 
$Cert = New-SelfSignedCertificate -DnsName $DNSName -CertStoreLocation "cert:\$StoreLocation\My" -NotBefore $CertBeginDate -NotAfter $CertExpiryDate -KeySpec Signature
Export-PfxCertificate -cert $Cert -FilePath $PFXFilePath -Password $SecStringPw 
Export-Certificate -cert $Cert -FilePath $CerFilePath 

終了日と .pfx のパスワードをメモしておきます (この例では、2019 年 5 月 15 日と MyPassword)。Make note of the end date and the password for the .pfx (in this example: May 15, 2019 and MyPassword). 次のスクリプトに必要です。You'll need them for the script below.

証明書を Azure AD アプリケーションに関連付けるAssociate the certificate with an Azure AD application

証明書を作成したので、それを Azure AD アプリケーションに関連付ける必要があります。Now that you have a certificate, you need to associate it with an Azure AD application. 関連付けは PowerShell を使って行うことができます。The association can be completed through PowerShell. 次のコマンドを実行して、証明書を Azure AD アプリケーションに関連付けます。Run the following commands to associate the certificate with the Azure AD application:

$x509 = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2
$x509.Import("C:\data\KVWebApp.cer")
$credValue = [System.Convert]::ToBase64String($x509.GetRawCertData())


$adapp = New-AzureRmADApplication -DisplayName "KVWebApp" -HomePage "http://kvwebapp" -IdentifierUris "http://kvwebapp" -CertValue $credValue -StartDate $x509.NotBefore -EndDate $x509.NotAfter


$sp = New-AzureRmADServicePrincipal -ApplicationId $adapp.ApplicationId


Set-AzureRmKeyVaultAccessPolicy -VaultName 'contosokv' -ServicePrincipalName "http://kvwebapp" -PermissionsToSecrets get,list,set,delete,backup,restore,recover,purge -ResourceGroupName 'contosorg'

# get the thumbprint to use in your app settings
$x509.Thumbprint

これらのコマンドを実行した後、Azure AD でアプリケーションを確認できます。After you've run these commands, you can see the application in Azure AD. アプリの登録を検索するときは、検索ダイアログで [すべてのアプリ] ではなく [マイ アプリ] を選択します。When searching the app registrations, make sure you select My apps instead of "All apps" in the search dialog.

証明書を使用する Web アプリにコードを追加するAdd code to your web app to use the certificate

ここで証明書にアクセスするコードを Web アプリに追加し、認証に使用します。Now we'll add code to your Web App to access the cert and use it for authentication.

まず、証明書にアクセスするコードがあります。StoreLocation は LocalMachine ではなく CurrentUser であることに注意してください。First, there's code to access the cert. Note that StoreLocation is CurrentUser instead of LocalMachine. また、ここではテスト証明書を使用しているため、Find メソッドに対して 'false' を指定しています。And that we're supplying 'false' to the Find method because we're using a test cert.

//Add this using statement
using System.Security.Cryptography.X509Certificates;  

public static class CertificateHelper
{
    public static X509Certificate2 FindCertificateByThumbprint(string findValue)
    {
        X509Store store = new X509Store(StoreName.My, StoreLocation.CurrentUser);
        try
        {
            store.Open(OpenFlags.ReadOnly);
            X509Certificate2Collection col = store.Certificates.Find(X509FindType.FindByThumbprint,
                findValue, false); // Don't validate certs, since the test root isn't installed.
            if (col == null || col.Count == 0)
                return null;
            return col[0];
        }
        finally
        {
            store.Close();
        }
    }
}

次に、CertificateHelper を使用し、認証に必要な ClientAssertionCertificate を作成するコードがあります。Next is code that uses the CertificateHelper and creates a ClientAssertionCertificate that is needed for authentication.

public static ClientAssertionCertificate AssertionCert { get; set; }

public static void GetCert()
{
    var clientAssertionCertPfx = CertificateHelper.FindCertificateByThumbprint(WebConfigurationManager.AppSettings["thumbprint"]);
    AssertionCert = new ClientAssertionCertificate(WebConfigurationManager.AppSettings["clientid"], clientAssertionCertPfx);
}

アクセス トークンを取得する新しいコードを次に示します。Here is the new code to get the access token. このコードで、前の例にある GetToken メソッドを置き換えます。This code replaces the GetToken method in the preceding example. 便宜上、別の名前を指定しています。I've given it a different name for convenience. 使いやすくするために、このコードをすべて Web アプリ プロジェクトの Utils クラスに配置してあります。I've put all of this code into my Web App project's Utils class for ease of use.

public static async Task<string> GetAccessToken(string authority, string resource, string scope)
{
    var context = new AuthenticationContext(authority, TokenCache.DefaultShared);
    var result = await context.AcquireTokenAsync(resource, AssertionCert);
    return result.AccessToken;
}

最後のコード変更は、Application_Start メソッドで行います。The last code change is in the Application_Start method. 最初に、GetCert() メソッドを呼び出して ClientAssertionCertificate を読み込む必要があります。First we need to call the GetCert() method to load the ClientAssertionCertificate. 次に、新しい KeyVaultClient を作成するときに指定するコールバック メソッドを変更します。And then we change the callback method that we supply when creating a new KeyVaultClient. このコードで、前の例のコードを置き換えます。This code replaces the code that we had in the preceding example.

Utils.GetCert();
var kv = new KeyVaultClient(new KeyVaultClient.AuthenticationCallback(Utils.GetAccessToken));

Azure portal を使用して証明書を Web アプリに追加するAdd a certificate to your web app through the Azure portal

証明書を Web アプリに追加する手順は、簡単な 2 段階のプロセスです。Adding a Certificate to your Web App is a simple two-step process. まず Azure Portal に移動し、Web アプリに移動します。First, go to the Azure portal and navigate to your Web App. Web アプリの [設定] で、[SSL 設定] のエントリをクリックします。On the Settings for your Web App, click on the entry for SSL settings. 開いたら、前の例で作成した証明書 KVWebApp.pfx をアップロードします。When it opens, upload the Certificate that you created in the preceding example, KVWebApp.pfx. pfx のパスワードを憶えておいてください。Make sure that you remember the password for the pfx.

Azure Portal での Web アプリへの証明書の追加

最後にWeb アプリへアプリケーション設定を、名前 "WEBSITE_LOAD_CERTIFICATES" 値 "*" と追加する必要があります。The last thing that you need to do is to add an Application Setting to your Web App that has the name WEBSITE_LOAD_CERTIFICATES and a value of *. この手順では、すべての証明書が読み込まれたことを確認します。This step will make sure that all Certificates are loaded. アップロードした証明書のみを読み込む場合は、そのサムプリントのコンマ区切りリストを入力できます。If you wanted to load only the Certificates that you've uploaded, then you can enter a comma-separated list of their thumbprints.

リソースのクリーンアップClean up resources

必要なくなったら、チュートリアルで使用したアプリ サービス、キー コンテナー、および Azure AD アプリケーションを削除します。When no longer needed, delete the app service, key vault, and Azure AD application you used for the tutorial.

次のステップNext steps