File: AzureKeyVaultResourceExtensions.cs
Web Access
Project: src\src\Aspire.Hosting.Azure.KeyVault\Aspire.Hosting.Azure.KeyVault.csproj (Aspire.Hosting.Azure.KeyVault)
// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.
 
using Aspire.Hosting.ApplicationModel;
using Aspire.Hosting.Azure;
using Azure.Provisioning;
using Azure.Provisioning.Expressions;
using Azure.Provisioning.KeyVault;
using System.Text.RegularExpressions;
 
namespace Aspire.Hosting;
 
/// <summary>
/// Provides extension methods for adding the Azure Key Vault resources to the application model.
/// </summary>
public static partial class AzureKeyVaultResourceExtensions
{
    /// <summary>
    /// Adds an Azure Key Vault resource to the application model.
    /// </summary>
    /// <param name="builder">The <see cref="IDistributedApplicationBuilder"/>.</param>
    /// <param name="name">The name of the resource. This name will be used as the connection string name when referenced in a dependency.</param>
    /// <returns>A reference to the <see cref="IResourceBuilder{T}"/>.</returns>
    /// <remarks>
    /// <para>
    /// By default references to the Azure Key Vault resource will be assigned the following roles:
    /// </para>
    /// <para>
    /// - <see cref="KeyVaultBuiltInRole.KeyVaultAdministrator"/>
    /// </para>
    /// <para>
    /// These can be replaced by calling <see cref="WithRoleAssignments{T}(IResourceBuilder{T}, IResourceBuilder{AzureKeyVaultResource}, KeyVaultBuiltInRole[])"/>.
    /// </para>
    /// <para>
    /// <strong>Managing Secrets:</strong>
    /// </para>
    /// <para>
    /// Use the <see cref="AddSecret(IResourceBuilder{AzureKeyVaultResource}, string, ParameterResource)"/> methods to add secrets to the Key Vault:
    /// </para>
    /// <example>
    /// <code lang="csharp">
    /// var builder = DistributedApplication.CreateBuilder(args);
    /// 
    /// var vault = builder.AddAzureKeyVault("vault");
    /// 
    /// // Add a secret from a parameter
    /// var secret = builder.AddParameter("secretParam", secret: true);
    /// vault.AddSecret("my-secret", secret);
    /// 
    /// // Add a secret from a reference expression
    /// var connectionString = ReferenceExpression.Create($"Server={server};Database={db}");
    /// vault.AddSecret("connection-string", connectionString);
    /// 
    /// // Get a reference to an existing secret
    /// var existingSecret = vault.GetSecret("existing-secret");
    /// </code>
    /// </example>
    /// </remarks>
    public static IResourceBuilder<AzureKeyVaultResource> AddAzureKeyVault(this IDistributedApplicationBuilder builder, [ResourceName] string name)
    {
        ArgumentNullException.ThrowIfNull(builder);
        ArgumentNullException.ThrowIfNull(name);
 
        builder.AddAzureProvisioning();
 
        var configureInfrastructure = static (AzureResourceInfrastructure infrastructure) =>
        {
            var keyVault = AzureProvisioningResource.CreateExistingOrNewProvisionableResource(infrastructure,
            (identifier, name) =>
            {
                var resource = KeyVaultService.FromExisting(identifier);
                resource.Name = name;
                return resource;
            },
            (infrastructure) => new KeyVaultService(infrastructure.AspireResource.GetBicepIdentifier())
            {
                Properties = new KeyVaultProperties()
                {
                    TenantId = BicepFunction.GetTenant().TenantId,
                    Sku = new KeyVaultSku()
                    {
                        Family = KeyVaultSkuFamily.A,
                        Name = KeyVaultSkuName.Standard
                    },
                    EnableRbacAuthorization = true,
                },
                Tags = { { "aspire-resource-name", infrastructure.AspireResource.Name } }
            });
 
            infrastructure.Add(new ProvisioningOutput("vaultUri", typeof(string))
            {
                Value = keyVault.Properties.VaultUri
            });
 
            // Process all secret resources
            if (infrastructure.AspireResource is AzureKeyVaultResource kvResource)
            {
                foreach (var secretResource in kvResource.Secrets)
                {
                    var value = secretResource.Value as IManifestExpressionProvider ?? throw new NotSupportedException(
                        $"Secret value for '{secretResource.SecretName}' is an unsupported type.");
 
                    var paramValue = value.AsProvisioningParameter(infrastructure, isSecure: true);
 
                    var secret = new KeyVaultSecret(Infrastructure.NormalizeBicepIdentifier($"secret_{secretResource.SecretName}"))
                    {
                        Name = secretResource.SecretName,
                        Properties = new SecretProperties
                        {
                            Value = paramValue
                        },
                        Parent = keyVault,
                    };
 
                    infrastructure.Add(secret);
                }
            }
 
            // We need to output name to externalize role assignments.
            infrastructure.Add(new ProvisioningOutput("name", typeof(string)) { Value = keyVault.Name });
        };
 
        var resource = new AzureKeyVaultResource(name, configureInfrastructure);
        return builder.AddResource(resource)
            .WithDefaultRoleAssignments(KeyVaultBuiltInRole.GetBuiltInRoleName,
                KeyVaultBuiltInRole.KeyVaultSecretsUser);
    }
 
    /// <summary>
    /// Assigns the specified roles to the given resource, granting it the necessary permissions
    /// on the target Azure Key Vault resource. This replaces the default role assignments for the resource.
    /// </summary>
    /// <param name="builder">The resource to which the specified roles will be assigned.</param>
    /// <param name="target">The target Azure Key Vault resource.</param>
    /// <param name="roles">The built-in Key Vault roles to be assigned.</param>
    /// <returns>The updated <see cref="IResourceBuilder{T}"/> with the applied role assignments.</returns>
    /// <remarks>
    /// <example>
    /// Assigns the KeyVaultReader role to the 'Projects.Api' project.
    /// <code lang="csharp">
    /// var builder = DistributedApplication.CreateBuilder(args);
    ///
    /// var vault = builder.AddAzureKeyVault("vault");
    /// 
    /// var api = builder.AddProject&lt;Projects.Api&gt;("api")
    ///   .WithRoleAssignments(vault, KeyVaultBuiltInRole.KeyVaultReader)
    ///   .WithReference(vault);
    /// </code>
    /// </example>
    /// </remarks>
    public static IResourceBuilder<T> WithRoleAssignments<T>(
        this IResourceBuilder<T> builder,
        IResourceBuilder<AzureKeyVaultResource> target,
        params KeyVaultBuiltInRole[] roles)
        where T : IResource
    {
        return builder.WithRoleAssignments(target, KeyVaultBuiltInRole.GetBuiltInRoleName, roles);
    }
 
    /// <summary>
    /// Gets a secret reference for the specified secret name from the Azure Key Vault resource.
    /// </summary>
    /// <param name="builder">The Azure Key Vault resource builder.</param>
    /// <param name="secretName">The name of the secret.</param>
    /// <returns>A reference to the secret.</returns>
    public static IAzureKeyVaultSecretReference GetSecret(this IResourceBuilder<AzureKeyVaultResource> builder, string secretName)
    {
        ArgumentNullException.ThrowIfNull(builder);
 
        return builder.Resource.GetSecret(secretName);
    }
 
    /// <summary>
    /// Adds a secret to the Azure Key Vault resource with the value from a parameter resource.
    /// </summary>
    /// <param name="builder">The Azure Key Vault resource builder.</param>
    /// <param name="secretName">The name of the secret. Must follow Azure Key Vault naming rules.</param>
    /// <param name="parameterResource">The parameter resource containing the secret value.</param>
    /// <returns>A reference to the <see cref="IResourceBuilder{T}"/>.</returns>
    public static IResourceBuilder<AzureKeyVaultSecretResource> AddSecret(this IResourceBuilder<AzureKeyVaultResource> builder, string secretName, IResourceBuilder<ParameterResource> parameterResource)
    {
        ArgumentNullException.ThrowIfNull(builder);
        ArgumentNullException.ThrowIfNull(parameterResource);
 
        return builder.AddSecret(secretName, secretName, parameterResource.Resource);
    }
 
    /// <summary>
    /// Adds a secret to the Azure Key Vault resource with the value from a parameter resource.
    /// </summary>
    /// <param name="builder">The Azure Key Vault resource builder.</param>
    /// <param name="secretName">The name of the secret. Must follow Azure Key Vault naming rules.</param>
    /// <param name="parameterResource">The parameter resource containing the secret value.</param>
    /// <returns>A reference to the <see cref="IResourceBuilder{T}"/>.</returns>
    public static IResourceBuilder<AzureKeyVaultSecretResource> AddSecret(this IResourceBuilder<AzureKeyVaultResource> builder, string secretName, ParameterResource parameterResource)
    {
        ArgumentNullException.ThrowIfNull(builder);
        ArgumentNullException.ThrowIfNull(parameterResource);
 
        ValidateSecretName(secretName);
 
        var secret = new AzureKeyVaultSecretResource(secretName, secretName, builder.Resource, parameterResource);
        builder.Resource.Secrets.Add(secret);
 
        return builder.ApplicationBuilder.AddResource(secret);
    }
 
    /// <summary>
    /// Adds a secret to the Azure Key Vault resource with the value from a reference expression.
    /// </summary>
    /// <param name="builder">The Azure Key Vault resource builder.</param>
    /// <param name="secretName">The name of the secret. Must follow Azure Key Vault naming rules.</param>
    /// <param name="value">The reference expression containing the secret value.</param>
    /// <returns>A reference to the <see cref="IResourceBuilder{T}"/>.</returns>
    public static IResourceBuilder<AzureKeyVaultSecretResource> AddSecret(this IResourceBuilder<AzureKeyVaultResource> builder, string secretName, ReferenceExpression value)
    {
        ArgumentNullException.ThrowIfNull(builder);
        ArgumentNullException.ThrowIfNull(value);
 
        ValidateSecretName(secretName);
 
        var secret = new AzureKeyVaultSecretResource(secretName, secretName, builder.Resource, value);
        builder.Resource.Secrets.Add(secret);
 
        return builder.ApplicationBuilder.AddResource(secret);
    }
 
    /// <summary>
    /// Adds a secret to the Azure Key Vault resource with the value from a parameter resource.
    /// </summary>
    /// <param name="builder">The Azure Key Vault resource builder.</param>
    /// <param name="name">The name of the secret resource.</param>
    /// <param name="secretName">The name of the secret. Must follow Azure Key Vault naming rules.</param>
    /// <param name="parameterResource">The parameter resource containing the secret value.</param>
    /// <returns>A reference to the <see cref="IResourceBuilder{T}"/>.</returns>
    public static IResourceBuilder<AzureKeyVaultSecretResource> AddSecret(this IResourceBuilder<AzureKeyVaultResource> builder, [ResourceName] string name, string secretName, IResourceBuilder<ParameterResource> parameterResource)
    {
        ArgumentNullException.ThrowIfNull(builder);
        ArgumentNullException.ThrowIfNull(parameterResource);
 
        return builder.AddSecret(name, secretName, parameterResource.Resource);
    }
 
    /// <summary>
    /// Adds a secret to the Azure Key Vault resource with the value from a parameter resource.
    /// </summary>
    /// <param name="builder">The Azure Key Vault resource builder.</param>
    /// <param name="name">The name of the secret resource.</param>
    /// <param name="secretName">The name of the secret. Must follow Azure Key Vault naming rules.</param>
    /// <param name="parameterResource">The parameter resource containing the secret value.</param>
    /// <returns>A reference to the <see cref="IResourceBuilder{T}"/>.</returns>
    public static IResourceBuilder<AzureKeyVaultSecretResource> AddSecret(this IResourceBuilder<AzureKeyVaultResource> builder, [ResourceName] string name, string secretName, ParameterResource parameterResource)
    {
        ArgumentNullException.ThrowIfNull(builder);
        ArgumentNullException.ThrowIfNull(parameterResource);
 
        ValidateSecretName(secretName);
 
        var secret = new AzureKeyVaultSecretResource(name, secretName, builder.Resource, parameterResource);
        builder.Resource.Secrets.Add(secret);
 
        return builder.ApplicationBuilder.AddResource(secret);
    }
 
    /// <summary>
    /// Adds a secret to the Azure Key Vault resource with the value from a reference expression.
    /// </summary>
    /// <param name="builder">The Azure Key Vault resource builder.</param>
    /// <param name="name">The name of the secret resource.</param>
    /// <param name="secretName">The name of the secret. Must follow Azure Key Vault naming rules.</param>
    /// <param name="value">The reference expression containing the secret value.</param>
    /// <returns>A reference to the <see cref="IResourceBuilder{T}"/>.</returns>
    public static IResourceBuilder<AzureKeyVaultSecretResource> AddSecret(this IResourceBuilder<AzureKeyVaultResource> builder, [ResourceName] string name, string secretName, ReferenceExpression value)
    {
        ArgumentNullException.ThrowIfNull(builder);
        ArgumentNullException.ThrowIfNull(value);
 
        ValidateSecretName(secretName);
 
        var secret = new AzureKeyVaultSecretResource(name, secretName, builder.Resource, value);
        builder.Resource.Secrets.Add(secret);
 
        return builder.ApplicationBuilder.AddResource(secret);
    }
 
    private static void ValidateSecretName(string secretName)
    {
        // Azure Key Vault secret names must be 1-127 characters long and contain only ASCII letters (a-z, A-Z), digits (0-9), and dashes (-)
        if (secretName.Length > 127)
        {
            throw new ArgumentException("Secret name cannot be longer than 127 characters.", nameof(secretName));
        }
 
        if (!AzureKeyVaultSecretNameRegex().IsMatch(secretName))
        {
            throw new ArgumentException("Secret name can only contain ASCII letters (a-z, A-Z), digits (0-9), and dashes (-).", nameof(secretName));
        }
    }
 
    [GeneratedRegex("^[a-zA-Z0-9-]+$")]
    private static partial Regex AzureKeyVaultSecretNameRegex();
}