Azure 키 자격 증명 모음 구성 공급자Azure Key Vault configuration provider

Luke LathamAndrew Stanton 간호사By Luke Latham and Andrew Stanton-Nurse

보기 또는 2.x에 대 한 샘플 코드를 다운로드 합니다.View or download sample code for 2.x:

이 문서에서는 사용 하는 방법에 설명 된 Microsoft Azure Key Vault 구성 공급자를 Azure 키 자격 증명 모음 암호에서 응용 프로그램 구성 값을 로드 합니다.This document explains how to use the Microsoft Azure Key Vault configuration provider to load application configuration values from Azure Key Vault secrets. Azure 키 자격 증명 모음에는 암호화 키와 앱 및 서비스에서 사용 하는 암호를 보호 하는 데 도움이 되는 클라우드 기반 서비스입니다.Azure Key Vault is a cloud-based service that helps you safeguard cryptographic keys and secrets used by apps and services. 일반적인 시나리오는 중요 한 구성 데이터에 대 한 액세스 제어를 포함 하며 FIPS 140-2에 대 한 요구 사항을 충족 수준 2 하드웨어 보안 모듈 (HSM의) 될 때 확인 구성 데이터를 저장 합니다.Common scenarios include controlling access to sensitive configuration data and meeting the requirement for FIPS 140-2 Level 2 validated Hardware Security Modules (HSM's) when storing configuration data. 이 기능은 이상의 ASP.NET Core 1.1을 대상으로 하는 응용 프로그램에 대해 사용할 수 있습니다.This feature is available for applications that target ASP.NET Core 1.1 or higher.

패키지Package

공급자를 사용 하려면 추가에 대 한 참조는 Microsoft.Extensions.Configuration.AzureKeyVault 패키지 합니다.To use the provider, add a reference to the Microsoft.Extensions.Configuration.AzureKeyVault package.

응용 프로그램 구성Application configuration

사용 하 여 공급자를 탐색할 수 있습니다는 앱 샘플합니다.You can explore the provider with the sample apps. 주요 자격 증명 모음을 설정 하 고 자격 증명 모음에 암호를 만들 샘플 앱은 안전 하 게을 로드 하는 비밀 값 해당 구성에 웹 페이지에 표시할.Once you establish a key vault and create secrets in the vault, the sample apps securely load the secret values into their configurations and display them in webpages.

공급자에 추가 되는 ConfigurationBuilderAddAzureKeyVault 확장 합니다.The provider is added to the ConfigurationBuilder with the AddAzureKeyVault extension. 샘플 응용 프로그램에서 확장 프로그램은 사용에서 로드 된 세 가지 구성 값은 appsettings.json 파일입니다.In the sample apps, the extension uses three configuration values loaded from the appsettings.json file.

앱 설정App Setting 설명Description 예제Example
Vault Azure 키 자격 증명 모음 이름Azure Key Vault name contosovaultcontosovault
ClientId Azure Active Directory 응용 프로그램 IdAzure Active Directory App Id 627e911e-43cc-61d4-992e-12db9c81b413627e911e-43cc-61d4-992e-12db9c81b413
ClientSecret Azure Active Directory 응용 프로그램 키Azure Active Directory App Key g58K3dtg59o1Pa e59v2Tx829w6VxTB2yv9sv/101di + =g58K3dtg59o1Pa+e59v2Tx829w6VxTB2yv9sv/101di=
config.SetBasePath(Directory.GetCurrentDirectory())
    .AddJsonFile("appsettings.json", optional: false)
    .AddEnvironmentVariables();

var builtConfig = config.Build();

config.AddAzureKeyVault(
    $"https://{builtConfig["Vault"]}.vault.azure.net/",
    builtConfig["ClientId"],
    builtConfig["ClientSecret"]);

주요 자격 증명 모음 암호 만들기 및 구성 값 (basic 샘플)를 로드 합니다.Creating key vault secrets and loading configuration values (basic-sample)

  1. 키 자격 증명 모음 만들기 및 Azure Active Directory (Azure AD)의 지침에 따라 응용 프로그램에 대 한 설정 Azure 키 자격 증명 모음 시작합니다.Create a key vault and set up Azure Active Directory (Azure AD) for the application following the guidance in Get started with Azure Key Vault.
    • 암호를 사용 하 여 주요 자격 증명 모음에 추가 된 AzureRM 키 자격 증명 모음 PowerShell 모듈 에서 사용할 수는 PowerShell 갤러리, Azure 키 자격 증명 모음 REST API, 또는 Azure 포털합니다.Add secrets to the key vault using the AzureRM Key Vault PowerShell Module available from the PowerShell Gallery, the Azure Key Vault REST API, or the Azure Portal. 비밀 하나로 만들어집니다 수동 또는 인증서 비밀 정보입니다.Secrets are created as either Manual or Certificate secrets. 인증서 비밀 앱 및 서비스에서 사용 하기 위해 인증서가 있지만 구성 공급자에서 지원 되지 않습니다.Certificate secrets are certificates for use by apps and services but are not supported by the configuration provider. 사용 해야는 수동 구성 공급자와 함께 사용 하기 위해 암호 이름-값 쌍을 만드는 옵션을 합니다.You should use the Manual option to create name-value pair secrets for use with the configuration provider.
      • 단순 암호 이름-값 쌍으로 생성 됩니다.Simple secrets are created as name-value pairs. Azure 키 자격 증명 모음 보안 이름은 영숫자, 대시로 제한 됩니다.Azure Key Vault secret names are limited to alphanumeric characters and dashes.
      • 계층 값 (구성 섹션) 사용 하 여 -- (대시 두 개)이 샘플에서 구분 기호로 합니다.Hierarchical values (configuration sections) use -- (two dashes) as a separator in the sample. 하위 키에의 한 부분을 구분 하는 데 일반적으로 사용 되는 콜론 ASP.NET Core 구성, 비밀 이름에 사용할 수 없습니다.Colons, which are normally used to delimit a section from a subkey in ASP.NET Core configuration, aren't allowed in secret names. 따라서 대시 두 개 사용 되며 암호는 응용 프로그램의 구성에 로드 될 때 콜론으로 교체 됩니다.Therefore, two dashes are used and swapped for a colon when the secrets are loaded into the app's configuration.
      • 두 개 만든 수동 비밀 다음 이름-값 쌍을 포함 합니다.Create two Manual secrets with the following name-value pairs. 첫 번째 암호는 단순한 이름 및 값, 및 두 번째 암호 섹션 및 비밀 이름에 하위 키와 비밀 값을 만듭니다.The first secret is a simple name and value, and the second secret creates a secret value with a section and subkey in the secret name:
        • SecretName: secret_value_1SecretName: secret_value_1
        • Section--SecretName: secret_value_2Section--SecretName: secret_value_2
    • Azure Active Directory와 샘플 응용 프로그램을 등록 합니다.Register the sample app with Azure Active Directory.
    • 응용 프로그램에서 주요 자격 증명 모음에 액세스 권한을 부여 합니다.Authorize the app to access the key vault. 사용 하는 경우는 Set-AzureRmKeyVaultAccessPolicy 앱 키 자격 증명 모음에 액세스할 수 권한을 부여 하는 PowerShell cmdlet을 제공 ListGet 와 비밀 정보에 대 한 액세스 -PermissionsToSecrets list,get합니다.When you use the Set-AzureRmKeyVaultAccessPolicy PowerShell cmdlet to authorize the app to access the key vault, provide List and Get access to secrets with -PermissionsToSecrets list,get.
  2. 응용 프로그램의 업데이트 appsettings.json 파일의 값을 가진 Vault, ClientId, 및 ClientSecret합니다.Update the app's appsettings.json file with the values of Vault, ClientId, and ClientSecret.
  3. 구성 값을 가져오는 샘플 응용 프로그램을 실행 IConfigurationRoot 비밀 이름으로 같은 이름의 합니다.Run the sample app, which obtains its configuration values from IConfigurationRoot with the same name as the secret name.
    • 비 계층 값: 값에 대 한 SecretName 사용 하 여 얻은 config["SecretName"]합니다.Non-hierarchical values: The value for SecretName is obtained with config["SecretName"].
    • 계층 값 (섹션): 사용 : (콜론) 표기법 또는 GetSection 확장 메서드.Hierarchical values (sections): Use : (colon) notation or the GetSection extension method. 이러한 방법 중 하나를 사용 하 여 구성 값을 가져옵니다.Use either of these approaches to obtain the configuration value:
      • config["Section:SecretName"]
      • config.GetSection("Section")["SecretName"]

응용 프로그램을 실행 하면 웹 페이지 로드 된 비밀 값으로 표시 됩니다.When you run the app, a webpage shows the loaded secret values:

브라우저 창에는 Azure 키 자격 증명 모음 구성 공급자를 통해 로드 하는 비밀 값 표시

접두사가 지정 된 키 자격 증명 모음 암호 만들기 및 구성 값 (키-이름-접두사-샘플)를 로드 합니다.Creating prefixed key vault secrets and loading configuration values (key-name-prefix-sample)

AddAzureKeyVault또한 구현을 허용 하는 오버 로드를 제공 IKeyVaultSecretManager, 구성 키로 변환 하는 주요 자격 증명 모음 암호를 제어할 수 있습니다.AddAzureKeyVault also provides an overload that accepts an implementation of IKeyVaultSecretManager, which allows you to control how key vault secrets are converted into configuration keys. 예를 들어 앱을 시작할 때 제공 되는 접두사 값에 따라 보안 값을 로드 하는 인터페이스를 구현할 수 있습니다.For example, you can implement the interface to load secret values based on a prefix value you provide at app startup. 이렇게 하면 응용 프로그램의 버전에 따라 암호를 로드 예를 들어 있습니다.This allows you, for example, to load secrets based on the version of the app.

경고

같은 키 자격 증명 모음에 여러 앱에 대 한 암호를 배치 하려면 또는 환경 비밀을 주요 자격 증명 모음 암호에 접두사를 사용 하지 않습니다 (예를 들어 개발 verus 프로덕션 비밀)를 동일한 자격 증명 모음입니다.Don't use prefixes on key vault secrets to place secrets for multiple apps into the same key vault or to place environmental secrets (for example, development verus production secrets) into the same vault. 다른 앱과 개발/프로덕션 환경 가장 높은 보안 수준에 대 한 응용 프로그램 환경을 격리할 때 별도 주요 자격 증명 모음 사용 하는 것이 좋습니다.We recommend that different apps and development/production environments use separate key vaults to isolate app environments for the highest level of security.

두 번째 샘플 응용 프로그램을 사용 하면 만들 되는 암호에 대 한 주요 자격 증명 모음에 5000-AppSecret (마침표 비밀 키 자격 증명 모음 이름에 허용 되지) 5.0.0.0 응용 프로그램의 버전에 대 한 앱 암호를 나타내는입니다.Using the second sample app, you create a secret in the key vault for 5000-AppSecret (periods aren't allowed in key vault secret names) representing an app secret for version 5.0.0.0 of your app. 에 대 한 암호를 만들면 다른 버전의 경우, 5.1.0.0 5100-AppSecret합니다.For another version, 5.1.0.0, you create a secret for 5100-AppSecret. 각 응용 프로그램 버전으로 해당 구성에는 자체 비밀 값 로드 AppSecret, 비밀 로드 된 버전에서 제거 합니다.Each app version loads its own secret value into its configuration as AppSecret, stripping off the version as it loads the secret. 샘플의 구현은 다음과 같습니다.The sample's implementation is shown below:

// The appVersion obtains the app version (5.0.0.0), which 
// is set in the project file and obtained from the entry 
// assembly. The versionPrefix holds the version without 
// dot notation for the PrefixKeyVaultSecretManager.
var appVersion = Assembly.GetEntryAssembly().GetName().Version.ToString();
var versionPrefix = appVersion.Replace(".", string.Empty);

config.AddAzureKeyVault(
    $"https://{builtConfig["Vault"]}.vault.azure.net/",
    builtConfig["ClientId"],
    builtConfig["ClientSecret"],
    new PrefixKeyVaultSecretManager(versionPrefix));
public class PrefixKeyVaultSecretManager : IKeyVaultSecretManager
{
    private readonly string _prefix;

    public PrefixKeyVaultSecretManager(string prefix)
    {
        _prefix = $"{prefix}-";
    }

    public bool Load(SecretItem secret)
    {
        // Load a vault secret when its secret name starts with the 
        // prefix. Other secrets won't be loaded.
        return secret.Identifier.Name.StartsWith(_prefix);
    }

    public string GetKey(SecretBundle secret)
    {
        // Remove the prefix from the secret name and replace two 
        // dashes in any name with the KeyDelimiter, which is the 
        // delimiter used in configuration (usually a colon). Azure 
        // Key Vault doesn't allow a colon in secret names.
        return secret.SecretIdentifier.Name
            .Substring(_prefix.Length)
            .Replace("--", ConfigurationPath.KeyDelimiter);
    }
}

Load 을 찾거나 버전 접두사가 있는 자격 증명 모음 암호를 반복 하는 공급자 알고리즘 메서드를 호출 합니다.The Load method is called by a provider algorithm that iterates through the vault secrets to find the ones that have the version prefix. 버전 접두사와 있을 때 Load, 알고리즘이 사용 하는 GetKey 메서드를 보안 이름의 구성 이름을 반환 합니다.When a version prefix is found with Load, the algorithm uses the GetKey method to return the configuration name of the secret name. 암호의 이름에서 버전 접두사를 제거 하 고 이름-값 쌍에 응용 프로그램의 구성에 한 로드에 대 한 비밀 이름의 나머지를 반환 합니다.It strips off the version prefix from the secret's name and returns the rest of the secret name for loading into the app's configuration name-value pairs.

이 방법은 구현 하는 경우:When you implement this approach:

  1. 주요 자격 증명 모음 암호 로드 됩니다.The key vault secrets are loaded.
  2. 에 대 한 문자열 암호 5000-AppSecret 일치 합니다.The string secret for 5000-AppSecret is matched.
  3. 버전, 5000 (대시로)는 하이픈이 제거 되어를 종료 하는 키 이름을 오프 AppSecret 비밀 값 응용 프로그램의 구성에 로드할 수 있습니다.The version, 5000 (with the dash), is stripped off of the key name leaving AppSecret to load with the secret value into the app's configuration.

참고

제공할 수도 있습니다 직접 KeyVaultClient 구현 AddAzureKeyVault합니다.You can also provide your own KeyVaultClient implementation to AddAzureKeyVault. 사용자 지정 클라이언트를 제공 합니다. 구성 공급자와 응용 프로그램의 다른 파트 간의 클라이언트의 단일 인스턴스를 공유할 수 있습니다.Supplying a custom client allows you to share a single instance of the client between the configuration provider and other parts of your app.

  1. 키 자격 증명 모음 만들기 및 Azure Active Directory (Azure AD)의 지침에 따라 응용 프로그램에 대 한 설정 Azure 키 자격 증명 모음 시작합니다.Create a key vault and set up Azure Active Directory (Azure AD) for the application following the guidance in Get started with Azure Key Vault.
    • 암호를 사용 하 여 주요 자격 증명 모음에 추가 된 AzureRM 키 자격 증명 모음 PowerShell 모듈 에서 사용할 수는 PowerShell 갤러리, Azure 키 자격 증명 모음 REST API, 또는 Azure 포털합니다.Add secrets to the key vault using the AzureRM Key Vault PowerShell Module available from the PowerShell Gallery, the Azure Key Vault REST API, or the Azure Portal. 비밀 하나로 만들어집니다 수동 또는 인증서 비밀 정보입니다.Secrets are created as either Manual or Certificate secrets. 인증서 비밀 앱 및 서비스에서 사용 하기 위해 인증서가 있지만 구성 공급자에서 지원 되지 않습니다.Certificate secrets are certificates for use by apps and services but are not supported by the configuration provider. 사용 해야는 수동 구성 공급자와 함께 사용 하기 위해 암호 이름-값 쌍을 만드는 옵션을 합니다.You should use the Manual option to create name-value pair secrets for use with the configuration provider.
      • 계층 값 (구성 섹션) 사용 하 여 -- (대시 두 개)를 구분 합니다.Hierarchical values (configuration sections) use -- (two dashes) as a separator.
      • 두 개 만든 수동 다음 이름-값 쌍이 있는 비밀 정보:Create two Manual secrets with the following name-value pairs:
        • 5000-AppSecret: 5.0.0.0_secret_value5000-AppSecret: 5.0.0.0_secret_value
        • 5100-AppSecret: 5.1.0.0_secret_value5100-AppSecret: 5.1.0.0_secret_value
    • Azure Active Directory와 샘플 응용 프로그램을 등록 합니다.Register the sample app with Azure Active Directory.
    • 응용 프로그램에서 주요 자격 증명 모음에 액세스 권한을 부여 합니다.Authorize the app to access the key vault. 사용 하는 경우는 Set-AzureRmKeyVaultAccessPolicy 앱 키 자격 증명 모음에 액세스할 수 권한을 부여 하는 PowerShell cmdlet을 제공 ListGet 와 비밀 정보에 대 한 액세스 -PermissionsToSecrets list,get합니다.When you use the Set-AzureRmKeyVaultAccessPolicy PowerShell cmdlet to authorize the app to access the key vault, provide List and Get access to secrets with -PermissionsToSecrets list,get.
  2. 응용 프로그램의 업데이트 appsettings.json 파일의 값을 가진 Vault, ClientId, 및 ClientSecret합니다.Update the app's appsettings.json file with the values of Vault, ClientId, and ClientSecret.
  3. 구성 값을 가져오는 샘플 응용 프로그램을 실행 IConfigurationRoot 접두사가 붙은 비밀 이름으로 같은 이름의 합니다.Run the sample app, which obtains its configuration values from IConfigurationRoot with the same name as the prefixed secret name. 이 샘플에서는 접두사는 응용 프로그램의 버전에 제공 된 PrefixKeyVaultSecretManager Azure 키 자격 증명 모음 구성 공급자를 추가 하는 경우.In this sample, the prefix is the app's version, which you provided to the PrefixKeyVaultSecretManager when you added the Azure Key Vault configuration provider. 에 대 한 값 AppSecret 사용 하 여 얻은 config["AppSecret"]합니다.The value for AppSecret is obtained with config["AppSecret"]. 응용 프로그램에 의해 생성 된 웹 페이지 로드 된 값을 보여 줍니다.The webpage generated by the app shows the loaded value:

    응용 프로그램의 버전을 5.0.0.0 Azure 키 자격 증명 모음 구성 공급자를 통해 로드 되는 브라우저 창에 비밀 값 표시

  4. 프로젝트 파일에서 응용 프로그램 어셈블리의 버전을 변경 5.0.0.05.1.0.0 응용 프로그램을 다시 실행 합니다.Change the version of the app assembly in the project file from 5.0.0.0 to 5.1.0.0 and run the app again. 이 이번에 반환 된 보안 값은 5.1.0.0_secret_value합니다.This time, the secret value returned is 5.1.0.0_secret_value. 응용 프로그램에 의해 생성 된 웹 페이지 로드 된 값을 보여 줍니다.The webpage generated by the app shows the loaded value:

    응용 프로그램의 버전을 5.1.0.0 Azure 키 자격 증명 모음 구성 공급자를 통해 로드 되는 브라우저 창에 비밀 값 표시

ClientSecret에 대 한 액세스를 제어합니다.Controlling access to the ClientSecret

사용 하 여는 암호 관리자 도구 유지 관리 하는 ClientSecret 프로젝트 소스 트리에 외부입니다.Use the Secret Manager tool to maintain the ClientSecret outside of your project source tree. 암호 관리자와 앱 암호 특정 프로젝트와 연결 여러 프로젝트 간에 공유할 수 있습니다.With Secret Manager, you associate app secrets with a specific project and share them across multiple projects.

인증서를 지원 하는 환경에서.NET Framework 앱을 개발 하는 경우 X.509 인증서로 Azure 키 자격 증명 모음에 인증할 수 있습니다.When developing a .NET Framework app in an environment that supports certificates, you can authenticate to Azure Key Vault with an X.509 certificate. X.509 인증서의 개인 키는 운영 체제에서 관리 됩니다.The X.509 certificate's private key is managed by the OS. 자세한 내용은 참조 클라이언트 암호 대신 인증서로 인증합니다.For more information, see Authenticate with a Certificate instead of a Client Secret. 사용 하 여는 AddAzureKeyVault 를 받아들이는 오버 로드는 X509Certificate2합니다.Use the AddAzureKeyVault overload that accepts an X509Certificate2.

var store = new X509Store(StoreLocation.CurrentUser);
store.Open(OpenFlags.ReadOnly);
var cert = store.Certificates.Find(X509FindType.FindByThumbprint, config["CertificateThumbprint"], false);

builder.AddAzureKeyVault(
    config["Vault"],
    config["ClientId"],
    cert.OfType<X509Certificate2>().Single(),
    new EnvironmentSecretManager(env.ApplicationName));
store.Close();

Configuration = builder.Build();

암호를 다시 로드Reloading secrets

될 때까지 캐시 된 비밀 IConfigurationRoot.Reload() 호출 됩니다.Secrets are cached until IConfigurationRoot.Reload() is called. 만료를 사용할 수 없을 때까지 응용 프로그램 키 자격 증명 모음에 업데이트 된 비밀 정보를 준수 하지 않 및 Reload 실행 됩니다.Expired, disabled, and updated secrets in the key vault are not respected by the application until Reload is executed.

Configuration.Reload();

사용 안 함 및 만료 된 암호Disabled and expired secrets

사용 안 함 및 만료 된 암호를 throw 한 KeyVaultClientException합니다.Disabled and expired secrets throw a KeyVaultClientException. 응용 프로그램에서 throw를 방지 하려면 응용 프로그램을 교체 또는 사용 안 함/만료 된 암호를 업데이트 합니다.To prevent your app from throwing, replace your app or update the disabled/expired secret.

문제 해결Troubleshooting

응용 프로그램에서 공급자를 사용 하 여 구성을 로드 하지 못하는에 오류 메시지가 기록 됩니다는 ASP.NET 로깅 인프라합니다.When the application fails to load configuration using the provider, an error message is written to the ASP.NET Logging infrastructure. 다음과 같은 구성을 로드에서 하지 것입니다.The following conditions will prevent configuration from loading:

  • 응용 프로그램은 Azure Active Directory에 올바르게 구성 되지 않았습니다.The app isn't configured correctly in Azure Active Directory.
  • Azure 키 자격 증명 모음에 키 자격 증명 모음 존재 하지 않습니다.The key vault doesn't exist in Azure Key Vault.
  • 응용 프로그램에 키 자격 증명 모음에 액세스할 권한이 부여 되지 않았습니다.The app isn't authorized to access the key vault.
  • 액세스 정책에 포함 되지 않으면 GetList 사용 권한.The access policy doesn't include Get and List permissions.
  • 키 자격 증명 모음에 구성 데이터 (이름-값 쌍)는 이름이 잘못 지정, 누락 된 경우 비활성화 되었거나 만료 되었습니다.In the key vault, the configuration data (name-value pair) is incorrectly named, missing, disabled, or expired.
  • 응용 프로그램에 잘못 된 키 자격 증명 모음 이름 (Vault), Azure AD 응용 프로그램 Id (ClientId), 또는 Azure AD 키 (ClientSecret).The app has the wrong key vault name (Vault), Azure AD App Id (ClientId), or Azure AD Key (ClientSecret).
  • Azure AD 키 (ClientSecret) 만료 되었습니다.The Azure AD Key (ClientSecret) is expired.
  • 구성 키 (이름)을 로드 하려고 하는 값에 대 한 응용 프로그램에서 올바르지 않습니다.The configuration key (name) is incorrect in the app for the value you're trying to load.

추가 리소스Additional resources