Secrets in Azure Container Apps¶

Azure Container Apps supports application-scoped secrets stored directly in the app definition or referenced from Azure Key Vault. This page focuses on how those secret mechanisms work inside Container Apps and when secret changes actually reach running revisions.

Secret exposure model¶

Container Apps exposes secrets through two layers:

1. Secret definitions in the app configuration.
2. Secret references from containers, most commonly through environment variables.

Microsoft Learn documents two supported secret definition patterns:

• Inline secret: the secret value is stored directly in the Container Apps secret store.
• Key Vault reference: the secret definition stores a keyVaultUrl and an identity that Container Apps uses to resolve the value from Azure Key Vault.

Inline secrets vs Key Vault references¶

Inline secret shape¶

Microsoft Learn shows inline secrets as name/value pairs:

{
  "name": "queue-connection-string",
  "value": "<secret-value>"
}

Key Vault reference shape¶

Microsoft Learn shows Key Vault-backed secrets with keyVaultUrl and identity:

{
  "name": "queue-connection-string",
  "keyVaultUrl": "https://<key-vault-name>.vault.azure.net/secrets/queue-connection-string",
  "identity": "system"
}

For a user-assigned identity, Microsoft Learn documents replacing system with the user-assigned identity resource ID.

How containers consume secrets¶

Environment variables reference secrets with secretRef instead of embedding the value directly in the container spec.

flowchart TD
    A[Container env var] --> B[secretRef]
    B --> C{Secret definition type}
    C --> D[Inline secret value]
    C --> E[Key Vault reference]
    E --> F[Managed identity]
    F --> G[Azure Key Vault]
    D --> H[Resolved value at runtime]
    G --> H
    H --> I[Revision container process]

Example environment variable reference:

{
  "name": "ConnectionString",
  "secretRef": "queue-connection-string"
}

The same secret name can be referenced by multiple revisions because the secret definition lives at the application level.

Managed identity requirements for Key Vault¶

Container Apps requires a managed identity before it can resolve a Key Vault-backed secret. Microsoft Learn documents these requirements:

• Enable either a system-assigned or user-assigned managed identity on the container app.
• Grant the identity access to the secret in Key Vault, typically through Azure RBAC such as Key Vault Secrets User.
• Ensure the app has a valid network path to Key Vault if the vault is behind private endpoints or other network restrictions.

Rotation and refresh behavior¶

Rotation behavior is where inline secrets and Key Vault references diverge most.

Inline secrets¶

When you update or delete an inline secret:

• Existing revisions do not automatically receive the new value.
• You must either:
  • Deploy a new revision, or
  • Restart an existing revision.

This makes inline secrets operationally simple, but they do not provide automatic refresh behavior.

Key Vault references¶

When the keyVaultUrl omits a secret version:

• Container Apps uses the latest Key Vault version.
• When a newer version becomes available, Container Apps automatically retrieves it within 30 minutes.
• Active revisions that reference that secret in an environment variable are automatically restarted to pick up the new value.

If you pin a specific secret version in the URI, you control promotion explicitly, but you also give up automatic latest-version refresh.

Practical configuration patterns¶

Pattern 1: Inline secret stored in Container Apps¶

Use this when the value is app-local and you already have a controlled revision rollout process.

az containerapp secret set \
  --name "$APP_NAME" \
  --resource-group "$RG" \
  --secrets "api-key=<secret-value>"

az containerapp update \
  --name "$APP_NAME" \
  --resource-group "$RG" \
  --set-env-vars "API_KEY=secretref:api-key"

Pattern 2: Key Vault-backed secret with managed identity¶

Use this when you want centralized secret lifecycle management and auditability.

az containerapp secret set \
  --name "$APP_NAME" \
  --resource-group "$RG" \
  --secrets "db-password=keyvaultref:https://<key-vault-name>.vault.azure.net/secrets/db-password,identityref:system"

az containerapp update \
  --name "$APP_NAME" \
  --resource-group "$RG" \
  --set-env-vars "DB_PASSWORD=secretref:db-password"

Security design guidance¶

Use these rules of thumb to avoid duplicating the full identity guidance elsewhere in the repo:

• Prefer managed identity + Key Vault for production secrets.
• Use inline secrets only when the operational simplicity is worth the manual refresh workflow.
• Keep the secret definition and the container reference conceptually separate when reviewing revisions.
• Treat revision restart behavior as part of your rotation plan, not as an implementation detail.

See Also¶

• Security Overview
• Key Vault Secrets Management (Managed Identity)
• Managed Identity
• Secret Rotation
• Identity and Secrets Best Practices

Sources¶

• Manage secrets in Azure Container Apps (Microsoft Learn)
• Manage environment variables in Azure Container Apps (Microsoft Learn)
• Managed identities in Azure Container Apps (Microsoft Learn)