[1.1 New Feature] Azure Key Vault Configuration Provider

[analogrelay]

Docs for the Azure Key Vault Configuration Provider should be added. Rough outline notes below.

Note: For Preview 1, The AzureKeyVault config provider only supports .NET 4.5.1+ apps, and not .NET Core apps.

• Service docs: https://azure.microsoft.com/en-us/services/key-vault/ and Key Vault Documentation
• Key Vault is a way to securely store secrets in Azure.
• AzureKeyVault Configuration provider adds support for reading configuration values out of Key Vault
• Create a Key Vault and an Application as per https://azure.microsoft.com/en-us/documentation/articles/key-vault-get-started/
  • The Configuration Provider requires that the access policy used to connect to the Key Vault has List and Get permissions to Secrets
• Add AzureKeyVault config source:

            var builder = new ConfigurationBuilder()
                .SetBasePath(env.ContentRootPath)
                .AddJsonFile("appsettings.json", optional: true, reloadOnChange: true)
                .AddJsonFile($"appsettings.{env.EnvironmentName}.json", optional: true)
#if NET451
                .AddAzureKeyVault("https://[vault name].vault.azure.net/", "[Azure AD App Client ID]", "[Azure AD App Client Secret]")
#endif
                .AddEnvironmentVariables();

• Add a "Manual" secret to the KeyVault using Azure PowerShell, API, or Portal ("Certificate" secrets are not supported)
• Read the secret by getting a configuration setting out of IConfiguration with the same name.
• For example: With a secret called "MySecret" and an IConfiguration or IConfigurationRoot instance config: config["MySecret"] will return the appropriate value.
• Hierarchical values can be put into the Vault using -- as a separator. For example Foo--Bar in the Key Vault can be retrieved via config["Foo:Bar"] or config.GetSection("Foo")["Bar"]
• Secrets are cached until IConfigurationRoot.Reload is called, so changes to the value in the Key Vault will not take affect until then
• Disabled secrets will cause config["..."] to throw KeyVaultClientException: Operation get is not allowed on a disabled secret during reload
• Since everything is cached, expired/disabled/updated secrets are not replaced until IConfigurationRoot.Reload is called.

/cc @pakrym

[caitchison]

Will support for a netstandard1.x be available for this or is it only going to be on the full framework? I can see a preview version of the AzureKeyVault nuget package that targets netstandard1.5.

[caitchison]

Never mind, I can see in the dev branch that you now have a netstandard1.5 framework with the new nuget package so that answers my question above. Hopefully that makes it into the 1.1 RTM :)

[analogrelay]

Yeah, we were just waiting on the Azure Key Vault client libraries to be ported to netstandard. That technically happened before the preview but we didn't have time to update. It should make 1.1 RTM in the current plans!

[guardrex]

@anurse I'm gonna format (not change) the outline ☝️ Friday morning. I think you guys will be able to approve it tomorrow afternoon, which would work well for me if that turns out to be the case. I enjoy writing on Saturday and Sunday mornings, and this doc will keep me out of trouble this weekend. 😁

[guardrex]

• Definition and purpose
  • Key Vault is a way to securely store secrets in Azure
  • AzureKeyVault configuration provider adds support for reading configuration values out of Azure Key Vault
• Package Microsoft.Extensions.Configuration.AzureKeyVault
• Application configuration
  • AddAzureKeyVault()
    • Basic configuration (simple implementation using appsettings.json file)
    • Use of IKeyVaultSecretManager (described but not in sample)
    • Use of KeyVaultClient (described but not in sample)
• Creating & reading secrets
  • Create a Key Vault
    • https://azure.microsoft.com/en-us/documentation/articles/key-vault-get-started/
    • The Configuration Provider requires that the access policy used to connect to the Key Vault has List and Get permissions to secrets
    • App in Azure AD must have access to the key vault
    • Add "Manual" secrets to the key vault using Azure PowerShell, API, or Portal
      • Hierarchical values (sections) use -- as a separator.
      • Test secrets
        • MySecret: Secret_Value_1
        • Section--MySecret: Secret_Value_2
      • "Certificate" secrets are not supported
  • Getting a configuration setting out of IConfiguration with the same name.
    • MySecret and an IConfiguration or IConfigurationRoot instance config: config["MySecret"]
    • Hierarchical Values (sections)
      • config["Section:MySecret"]
      • config.GetSection("Section")["MySecret"]
• Secrets are cached until IConfigurationRoot.Reload() is called. Expired/disabled/updated secrets are not replaced until IConfigurationRoot.Reload() is called
• Disabled secrets throw KeyVaultClientException: Operation get is not allowed on a disabled secret during reload
• Troubleshooting
  • Checking values from Azure (AD & Key Vault)
  • Confirm Get and List permissions for the access policy
  • Using PS to make sure the app has access to key vault if Access Denied is the error
• Additional Resources
  • Configuration - https://docs.microsoft.com/en-us/aspnet/core/fundamentals/configuration
  • Microsoft Azure: Key Vault - https://azure.microsoft.com/en-us/services/key-vault/)
  • Microsoft Azure: Key Vault Documentation - https://docs.microsoft.com/en-us/azure/key-vault/)

[guardrex]

@anurse I just reformatted it a little. I tend to drop these right into the doc body and go to town on it.

The status on Core: This is still .NET 4.5.1 only, correct? Are Core capabilities on the dev feed package?

Anything missing or other notes?

[guardrex]

@tdykstra Do you want this doc to appear under Security? ... perhaps under the Safe storage of app secrets during development doc?

If you prefer big changes to Configuration layout for this, then I'll wait for you to do the setup.

If you just want it under Security, I can handle that in the PR without crashing the Internet. 😄

[EDIT] Title: Azure Key Vault Configuration Provider 👈 Is that correct?

[analogrelay]

The status on Core: This is still .NET 4.5.1 only, correct?

Nope, Microsoft.Extensions.Configuration.AzureKeyVault 1.0.0 supports Core. It was just during the preview that it didn't support it. It does require ASP.NET Core 1.1 though, it's not supported on ASP.NET Core 1.0.

[guardrex]

Excellent! Thanks.

[tdykstra]

@guardrex I would put it where you suggest but link to it from the Fundamentals/Configuration doc. Title looks good.

[guardrex]

@tdykstra Cool. Thanks.

I'll look at this one more time tonight ... the outline and the sample and ref docs. I'll sit down to writing tomorrow morning. Thanks guys ... this is looking great.

[guardrex]

@anurse

Sample app

I put a draft sample app up for the doc ...

https://github.com/GuardRex/Docs/tree/guardrex/key-vault-configuration/aspnetcore/security/key-vault-configuration/sample

• Reads Vault, ClientId, and ClientSecret from appsettings.json
• Simplest example is implemented. We can have info on configuration with IKeyVaultSecretManager and KeyVaultClient in the doc. Do you agree that those are advanced scenarios and thus don't need to be part of the sample?
• I use the Configuration to load a little markup, which I shamelessly stole from a @PinpointTownes bug report because I thought it was pretty slick. Two other doc samples that aren't MVC apps return markup, but they don't really send back a real HTML document. They just shoot back a little markup (like a paragraph, <p>). Also, I wasn't really feel'in Console.WriteLine() ... very boring. I like this full markup document approach, so let me know if you think it's ok. cc/ @tdykstra

[UPDATE] Still very WIP but the first draft is shaping up like this I'm at 2nd draft stage now I'm at the 3rd draft ...

https://github.com/GuardRex/Docs/blob/guardrex/key-vault-configuration/aspnetcore/security/key-vault-configuration.md

... and I'll work that over a few times again on Monday evening with final edits Tuesday morning. I hope to PR it by Tuesday noon CST. However, if you see something going terribly astray, I'm all 👂 👂 👂 👂 ears.

🎉 🎈 PR is ready! 🎈 🎉