Azure API Management Named Values & Key Vault Integration

Securely Storing and Using Configuration Values

Introduction

Named values in Azure API Management provide a way to store configuration values and secrets that can be used across multiple policies. When combined with Azure Key Vault integration, you can securely store sensitive information like API keys, connection strings, and certificates without exposing them in your policies.

This comprehensive guide covers:

Named values — Creating and using configuration values
Key Vault integration — Secure secret storage
Managed identity — Authentication without credentials
Usage patterns — Using values in policies
Best practices — Secure configuration management

Understanding Named Values

Types of Named Values

┌─────────────────────────────────────────────────────────────────────┐
│                       NAMED VALUE TYPES                             │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│   ┌─────────────────────────────────────────────────────────────┐   │
│   │                    Plain Values                             │   │
│   │                                                             │   │
│   │   • API version: "2024-01-01"                               │   │
│   │   • Base URL: "https://api.example.com"                     │   │
│   │   • Timeout: "30"                                           │   │
│   │                                                             │   │
│   └─────────────────────────────────────────────────────────────┘   │
│                                                                     │
│   ┌─────────────────────────────────────────────────────────────┐   │
│   │                    Secrets (Masked)                         │   │
│   │                                                             │   │
│   │   • API Key: "*********************abc"                     │   │
│   │   • Password: "*********************xyz"                    │   │
│   │                                                             │   │
│   └─────────────────────────────────────────────────────────────┘   │
│                                                                     │
│   ┌─────────────────────────────────────────────────────────────┐   │
│   │                    Key Vault References                     │   │
│   │                                                             │   │
│   │   • @Microsoft.KeyVault(SecretUri=...)                      │   │
│   │   • Automatically fetched and rotated                       │   │
│   │   • Uses managed identity                                   │   │
│   │                                                             │   │
│   └─────────────────────────────────────────────────────────────┘   │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Creating Named Values

Via Azure Portal

Navigate to your APIM instance
Go to "Named values" in the left menu
Click "+ Add"
Configure:
- Name: Unique identifier (e.g., api-key)
- Display name: Friendly name
- Value: The actual value or Key Vault reference
- Secret: Toggle if value is a secret

Via CLI

# Create plain named value
az apim nv create \
  --resource-group my-rg \
  --service-name my-apim \
  --name "api-version" \
  --value "2024-01-01"

# Create secret named value
az apim nv create \
  --resource-group my-rg \
  --service-name my-apim \
  --name "api-key" \
  --value "secret-key-value" \
  --secret-value true

Azure Key Vault Integration

Why Use Key Vault?

Benefit	Description
Security	Secrets never exposed in APIM
Rotation	Automatic secret rotation
Audit	Full audit trail of access
Access Control	Role-based permissions
Encryption	Hardware-level encryption

Step 1: Enable Managed Identity

# Enable system-assigned managed identity
az apim identity assign \
  --resource-group my-rg \
  --name my-apim

# Get the principal ID
az apim show \
  --resource-group my-rg \
  --name my-apim \
  --query "identity.principalId"

Step 2: Grant Key Vault Access

# Get Key Vault resource ID
KV_RESOURCE_ID=$(az keyvault show \
  --name my-key-vault \
  --query "id" -o tsv)

# Set access policy
az keyvault set-policy \
  --name my-key-vault \
  --object-id "<apim-principal-id>" \
  --secret-permissions get list \
  --key-permissions get list \
  --certificate-permissions get list

Step 3: Create Named Value with Key Vault

Name: connection-string
Value: @Microsoft.KeyVault(SecretUri=https://mykeyvault.vault.azure.net/secrets/connection-string/)

Versioned Secret Reference

# Specific version
@Microsoft.KeyVault(SecretUri=https://mykeyvault.vault.azure.net/secrets/connection-string/abc123)

# Latest version (auto-updates)
@Microsoft.KeyVault(SecretUri=https://mykeyvault.vault.azure.net/secrets/connection-string/)

Using Named Values in Policies

Syntax

<!-- Use named value in policy -->
<set-header name="X-Api-Key" exists-action="override">
    <value>{{api-key}}</value>
</set-header>

Examples

<!-- Set backend URL -->
<backend>
    <set-backend-service base-url="{{backend-base-url}}" />
</backend>

<!-- Set API key header -->
<inbound>
    <set-header name="X-Api-Key" exists-action="override">
        <value>{{external-api-key}}</value>
    </set-header>
</inbound>

<!-- Use in expressions -->
<set-variable name="apiVersion" value="{{api-version}}" />

Key Vault in Policies

<!-- Key Vault reference is automatically resolved -->
<set-header name="Authorization" exists-action="override">
    <value>{{keyvault-api-key}}</value>
</set-header>

<!-- The value is fetched from Key Vault at runtime -->

Common Patterns

API Keys for Backends

<inbound>
    <!-- Backend 1 API key -->
    <set-header name="X-Backend1-Key" exists-action="override">
        <value>{{backend1-api-key}}</value>
    </set-header>
    
    <!-- Backend 2 API key -->
    <set-header name="X-Backend2-Key" exists-action="override">
        <value>{{backend2-api-key}}</value>
    </set-header>
</inbound>

Connection Strings

<inbound>
    <set-variable name="sql-connection" value="{{sql-connection-string}}" />
</inbound>

<backend>
    <set-backend-service base-url="@(context.Variables["sql-connection"])" />
</backend>

URLs and Endpoints

<inbound>
    <set-header name="X-Return-Url" exists-action="override">
        <value>{{frontend-url}}</value>
    </set-header>
</inbound>

Secrets Rotation

Manual Rotation

# Update secret in Key Vault
az keyvault secret set \
  --vault-name my-key-vault \
  --name connection-string \
  --value "new-connection-string"

# APIM automatically picks up the new value

Automatic Rotation with Key Vault

Key Vault Secret Update
        │
        ▼
┌───────────────────┐
│  APIM Cache      │
│  (5-minute TTL)  │
└────────┬──────────┘
         │
         ▼
┌───────────────────┐
│  New Value       │
│  Retrieved       │
└───────────────────┘

Best Practices

Practice	Description
Use Key Vault for secrets	Never store secrets directly in APIM
Enable managed identity	Avoid storing credentials
Use latest version references	Auto-rotate without code changes
Organize with prefixes	`backend-`, `external-`, `internal-`
Document values	Use display name for description
Enable diagnostic logging	Track secret access

Security Checklist

✓ Enable system-assigned managed identity
✓ Grant minimum required permissions
✓ Use Key Vault instead of plain secrets
✓ Reference latest version for rotation
✓ Enable Key Vault firewall
✓ Monitor access with Azure Monitor

Troubleshooting

Common Issues

Issue	Solution
Key Vault access denied	Check managed identity has access policy
Secret not found	Verify secret URI is correct
Value not resolving	Check Key Vault firewall settings
Old value showing	Wait for cache to expire (5 min)

Debug Named Values

# List all named values
az apim nv list \
  --resource-group my-rg \
  --service-name my-apim

# Show specific value (masked)
az apim nv show \
  --resource-group my-rg \
  --service-name my-apim \
  --name api-key