Description

User feedback transferred from UUF System:

"Found out from googling that you have to actually create the key in the key vault and pass that in to ProtectKeysWithAzureKeyVault method, but this is not clear at all from this page - can you please make it clear that you have to create the key first and then pass the identifier?"

[The following is an AI assisted assessment and proposed solution]

Problem Statement

The current documentation for "Configure ASP.NET Core Data Protection" doesn't explicitly state that users need to create a key in Azure Key Vault before using the ProtectKeysWithAzureKeyVault method. This step is missing from the documentation, causing confusion for some users trying to implement Azure Key Vault protection for their data protection keys.

While the documentation mentions the "Azure Key Vault key identifier" parameter in several places, it doesn't clearly instruct users to create this key first before passing its identifier to the method. This omission is causing users to search elsewhere for this important setup step.

Solution

Add explicit instructions on creating a key in Azure Key Vault before using it with the Data Protection API. This should be added to the "Protect keys with Azure Key Vault" section to ensure users have complete information for implementation.

Proposed Changes

In the file aspnetcore/security/data-protection/configuration/overview.md, under the "Protect keys with Azure Key Vault (ProtectKeysWithAzureKeyVault)" section, add the following text after the bullet points about establishing the key vault (around line 58):

**Create a key in Azure Key Vault**

Before using the `ProtectKeysWithAzureKeyVault` method, you must first create a key in your Azure Key Vault:

1. In the Azure portal, navigate to your Key Vault resource
2. Select "Keys" under Settings
3. Click "Generate/Import" to create a new key
4. Provide a name for your key (for example, "DataProtectionKey")
5. Select your desired key type and options (RSA keys are commonly used)
6. Click "Create" to generate the key
7. After creation, click on the created key to view its details
8. Copy the "Key Identifier" URL - this is the value you'll use for the `{KEY IDENTIFIER}` parameter in your code

This Key Identifier URL typically follows this format: `https://{your-key-vault-name}.vault.azure.net/keys/{key-name}/{version}`

Additionally, update the description of the {KEY IDENTIFIER} parameter (around line 103) to be more explicit:

Current:

`{KEY IDENTIFIER}`: Azure Key Vault key identifier used for key encryption. An access policy allows the application to access the key vault with `Get`, `Unwrap Key`, and `Wrap Key` permissions. The verification key MUST be 2048-bits or larger.

Proposed:

`{KEY IDENTIFIER}`: The full URL to your Azure Key Vault key (that you created earlier in the key vault), used for key encryption. This identifier is found in the key's properties in the Azure portal. An access policy allows the application to access the key vault with `Get`, `Unwrap Key`, and `Wrap Key` permissions. The verification key MUST be 2048-bits or larger.

These changes will provide users with clear instructions on the prerequisite step of creating a key in Azure Key Vault before using the ProtectKeysWithAzureKeyVault method, avoiding confusion and reducing the need to search for this information elsewhere.

Page URL

https://learn.microsoft.com/en-us/aspnet/core/security/data-protection/configuration/overview?view=aspnetcore-9.0

Content source URL

https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/security/data-protection/configuration/overview.md

Document ID

69818122-e47a-3fed-ea37-8009f66e2a5c

Platform Id

ce9ee80a-9c4f-8f0f-1327-dead47662f00

Article author

@tdykstra

Metadata

• ID: b63ab082-ad30-b00d-ecd1-ca88eee1659e
• PlatformId: ce9ee80a-9c4f-8f0f-1327-dead47662f00
• Service: aspnet-core
• Sub-service: security

Related Issues