Handling Azure Key Vault Secret Naming with Umbraco UIBuilder License Configuration

The Issue: Key Vault Naming Constraints

When configuring the Umbraco UIBuilder license using Azure Key Vault, you might encounter a frustrating issue: Key Vault secret names cannot contain dots ("."), while Umbraco UIBuilder uses dots to structure its configuration:

"Umbraco": {
    "Licenses": {
        "Products": {
            "Umbraco.UIBuilder": "YOUR_LICENSE_KEY"
        }
    }
}

However, Azure Key Vault enforces strict naming rules, allowing only alphanumeric characters and dashes ("-") in secret names. Additionally, the Azure.Extensions.AspNetCore.Configuration.Secrets package automatically converts double dashes (--) to colons (:), making it even trickier when trying to map hierarchical configurations.

Why is this a problem?

Since the Umbraco UIBuilder package uses dot-separated keys in its configuration, using Umbraco.UIBuilder as a secret name isn't possible in Key Vault. Instead, we need a way to transform secret names from Key Vault into a structure that fits the expected configuration format for Umbraco UIBuilder.

The Solution: Implementing a Custom KeyVaultSecretManager

To resolve this issue, we can implement a custom KeyVaultSecretManager to control how secret names are mapped from Azure Key Vault to the expected configuration structure.

Step 1: Store the Secret in Key Vault
Since dots are not allowed, we store the secret in Key Vault using a different naming convention, for example:

Instead of Umbraco--Licenses--Products--Umbraco.UIBuilder, store it as:
Umbraco--Licenses--Products--Umbraco-UIBuilder (using a single dash - instead of a dot .).

Step 2: Create a Custom KeyVaultSecretManager
Now, we need to create a custom KeyVaultSecretManager that replaces dashes (-) with dots (.) when reading the Umbraco UIBuilder secret from Azure Key Vault.

using Azure.Extensions.AspNetCore.Configuration.Secrets;
using Azure.Security.KeyVault.Secrets;

namespace My.Namespace;

public class CustomSecretManager : KeyVaultSecretManager
{
    public override string GetKey(KeyVaultSecret secret)
    {
        var key = base.GetKey(secret); 

        if (key.Equals("Umbraco:Licenses:Products:Umbraco-UIBuilder", StringComparison.OrdinalIgnoreCase))
        {
            return key.Replace("-", ".");
        }

        return key; 
    }
}

Step 3: Register the Custom KeyVaultSecretManager
To integrate Key Vault with your Umbraco application, follow the official Umbraco documentation. However, you’ll need to modify the ConfigureKeyVault method to use the CustomKeyVaultSecretManager instead of the default configuration.

using Azure.Identity;
using Azure.Security.KeyVault.Secrets;
using Azure.Extensions.AspNetCore.Configuration.Secrets;
using Microsoft.Extensions.Configuration;

namespace My.Namespace;

public static class WebApplicationBuilderExtensions
{
    public static WebApplicationBuilder ConfigureKeyVault(this WebApplicationBuilder builder)
    {
        var keyVaultEndpoint = builder.Configuration["AzureKeyVaultEndpoint"];
        if (!string.IsNullOrWhiteSpace(keyVaultEndpoint) && Uri.TryCreate(keyVaultEndpoint, UriKind.Absolute, out var validUri))
        {
            builder.Configuration.AddAzureKeyVault(
                new SecretClient(validUri, new DefaultAzureCredential()),
                new CustomKeyVaultSecretManager() // Use the custom manager
            );
        }

        return builder;
    }
}

This workaround allows us to stay aligned with Umbraco's recommended approach while bypassing Key Vault's naming restrictions, ensuring Umbraco UIBuilder can still retrieve its configuration correctly