Configuración del almacenamiento de claves de host de Functions en Azure Container Apps

Las claves de acceso de Functions son tokens de autenticación que el runtime de Functions usa para proteger los puntos de conexión desencadenados por HTTP. Cuando un autor de llamada invoca una función HTTP, incluye una clave como parámetro ?code= de consulta o un x-functions-key encabezado. El tiempo de ejecución valida la clave y autoriza o rechaza la solicitud.

Las claves de acceso no son las mismas que los secretos de nivel de aplicación. Las claves de acceso protegen quién puede llamar a tus funciones, mientras que los secretos a nivel de aplicación protegen a qué se conectan tus funciones.

Cuándo usar las claves de acceso

Prerequisites

• Una cuenta de Azure con una suscripción activa. Cree una cuenta gratuita.
• CLI de Azure versión 2.40.0 o posterior.
• Una aplicación Azure Functions existente en Container Apps o permisos para crear una.

Tipos de clave de acceso

El entorno de ejecución de Functions administra cuatro tipos de claves:

Patrones de nombres secretos

La convención de nomenclatura de las claves almacenadas depende del back-end de almacenamiento.

Almacén de claves (Key Vault)

El backend de Key Vault almacena cada clave como un secreto individual de Key Vault mediante una convención de doble guión (--):

Almacenamiento de Blobs

El backend de Blob Storage almacena claves como archivos JSON en el contenedor de blobs azure-webjobs-secrets. Todas las claves de nivel de host (maestras, claves de función y claves del sistema) se almacenan juntas en un único host.json blob. Las claves por función se almacenan en blobs independientes nombrados según cada función.

Almacén de secretos de Container Apps

El almacén de secretos de Container Apps usa una convención diferente. El host de Functions lee las claves de los archivos montados en volumen en /run/secrets/functions-keys/. Cada archivo usa un nombre con puntos (por ejemplo, host.master), pero los nombres secretos de Container Apps solo permiten caracteres alfanuméricos en minúsculas y guiones. Al montar un volumen secreto, debe establecer explícitamente el campo path con el nombre de archivo con puntos que espera el host de Functions (por ejemplo, secretRef: host-master → path: host.master). La plataforma no realiza ninguna traducción automática de nombres.

Elección de un back-end de almacenamiento

Establezca la AzureWebJobsSecretStorageType variable de entorno para controlar dónde conserva el tiempo de ejecución las claves de acceso. Azure Container Apps admite tres back-end de nivel de producción.

Configuración del almacén de secretos de Container Apps

El almacén de secretos de Container Apps es el back-end recomendado. Las claves permanecen dentro de la plataforma Container Apps y no requieren almacenamiento externo ni Key Vault. Azure Resource Manager registra los cambios en secretos y variables de entorno en los registros de actividad.

Con este back-end, el host de Functions lee las claves de los archivos montados en volumen en /run/secrets/functions-keys/. El host no genera automáticamente claves. Debe crear cada clave como secreto de Container Apps y la plataforma los monta como archivos para que el host los lea.

Paso 1: Establecimiento del tipo de almacenamiento

az containerapp update \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --set-env-vars "AzureWebJobsSecretStorageType=containerapp"

Paso 2: Generación y almacenamiento de secretos de clave de acceso

Genere valores clave y almacénelos como secretos de Container Apps. Como mínimo, necesita la clave maestra y una clave de host predeterminada.

# Generate random key values
MASTER_KEY=$(openssl rand -hex 32)
HOST_DEFAULT_KEY=$(openssl rand -hex 32)

# Store as Container Apps secrets
az containerapp secret set \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --secrets "host-master=$MASTER_KEY" "host-function-default=$HOST_DEFAULT_KEY"

FUNC_KEY=$(openssl rand -hex 32)

az containerapp secret set \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --secrets "functions-myhttpfunc-default=$FUNC_KEY"

Paso 3: Configuración de montaje de volumen

Monte los secretos como archivos en /run/secrets/functions-keys/.

# Export current config
az containerapp show \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --output yaml > app.yaml

properties:
  template:
    volumes:
      - name: functions-keys
        storageType: Secret
        secrets:
          - secretRef: host-master
            path: host.master
          - secretRef: host-function-default
            path: host.function.default
    containers:
      - name: <CONTAINER_NAME>
        volumeMounts:
          - volumeName: functions-keys
            mountPath: /run/secrets/functions-keys

az containerapp update \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --yaml app.yaml

Paso 4: Comprobar

Una vez reiniciada la aplicación, confirme que las claves funcionan:

az containerapp function keys list \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --key-type hostKey

También puede comprobar los registros de la aplicación para el mensaje Resolved secret storage provider ContainerAppsSecretsRepository, que confirma que el host utiliza el almacenamiento de secretos de Container Apps.

Rotación de claves

Para rotar una clave, actualice el secreto de Container Apps y reinicie la aplicación:

NEW_KEY=$(openssl rand -hex 32)

az containerapp secret set \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --secrets "host-function-default=$NEW_KEY"

az containerapp revision restart \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --revision "<REVISION_NAME>"

Configuración de Blob Storage

El back-end de Blob Storage permite que el entorno de ejecución genere y administre automáticamente las claves de acceso. Use esta opción cuando ya tenga una cuenta de almacenamiento para AzureWebJobsStorage y no necesite gobernanza centralizada.

1. Habilite la identidad administrada en la aplicación contenedora (si aún no está habilitada):

   az containerapp identity assign \
     --resource-group "<RESOURCE_GROUP>" \
     --name "<FUNCTIONS_APP_NAME>" \
     --system-assigned
   

2. Conceda el rol Colaborador de datos de Storage Blob en la cuenta de almacenamiento a la identidad administrada:

   PRINCIPAL_ID=$(az containerapp show \
     --resource-group "<RESOURCE_GROUP>" \
     --name "<FUNCTIONS_APP_NAME>" \
     --query identity.principalId \
     --output tsv)
   
   STORAGE_ID=$(az storage account show \
     --name "<STORAGE_ACCOUNT_NAME>" \
     --resource-group "<RESOURCE_GROUP>" \
     --query id \
     --output tsv)
   
   az role assignment create \
     --role "Storage Blob Data Contributor" \
     --assignee "$PRINCIPAL_ID" \
     --scope "$STORAGE_ID"
   

3. Establezca el tipo de almacenamiento:

   az containerapp update \
     --resource-group "<RESOURCE_GROUP>" \
     --name "<FUNCTIONS_APP_NAME>" \
     --set-env-vars "AzureWebJobsSecretStorageType=blob"
   

4. El entorno de ejecución genera automáticamente claves en el siguiente inicio en frío. Compruebe lo siguiente:

   az containerapp function keys list \
     --resource-group "<RESOURCE_GROUP>" \
     --name "<FUNCTIONS_APP_NAME>" \
     --key-type hostKey
   

Configuración de Key Vault

El back-end de Key Vault almacena las claves de acceso como secretos de Key Vault, lo que proporciona auditoría de nivel empresarial y control de acceso.

1. Cree una Key Vault (si no tiene una):

   az keyvault create \
     --name "<KEYVAULT_NAME>" \
     --resource-group "<RESOURCE_GROUP>" \
     --location "<LOCATION>"
   

2. Habilite la identidad administrada en la aplicación contenedora (si aún no está habilitada):

   az containerapp identity assign \
     --resource-group "<RESOURCE_GROUP>" \
     --name "<FUNCTIONS_APP_NAME>" \
     --system-assigned
   

3. Otorgue el rol Key Vault Secrets Officer a la identidad administrada. El tiempo de ejecución necesita acceso de lectura y escritura para crear y administrar claves:

   PRINCIPAL_ID=$(az containerapp show \
     --resource-group "<RESOURCE_GROUP>" \
     --name "<FUNCTIONS_APP_NAME>" \
     --query identity.principalId \
     --output tsv)
   
   KEYVAULT_ID=$(az keyvault show \
     --name "<KEYVAULT_NAME>" \
     --query id \
     --output tsv)
   
   az role assignment create \
     --role "Key Vault Secrets Officer" \
     --assignee "$PRINCIPAL_ID" \
     --scope "$KEYVAULT_ID"
   

4. Establezca el tipo de almacenamiento y Key Vault URI:

   Para la identidad asignada por el sistema:

   az containerapp update \
     --resource-group "<RESOURCE_GROUP>" \
     --name "<FUNCTIONS_APP_NAME>" \
     --set-env-vars \
       "AzureWebJobsSecretStorageType=keyvault" \
       "AzureWebJobsSecretStorageKeyVaultUri=https://<KEYVAULT_NAME>.vault.azure.net"
   

   Para la identidad asignada por el usuario, establezca también el identificador de cliente:

   az containerapp update \
     --resource-group "<RESOURCE_GROUP>" \
     --name "<FUNCTIONS_APP_NAME>" \
     --set-env-vars \
       "AzureWebJobsSecretStorageType=keyvault" \
       "AzureWebJobsSecretStorageKeyVaultUri=https://<KEYVAULT_NAME>.vault.azure.net" \
       "AzureWebJobsSecretStorageKeyVaultClientId=<USER_ASSIGNED_IDENTITY_CLIENT_ID>"
   

5. Desencadene la creación de claves mediante la enumeración de claves:

   az containerapp function keys list \
     --resource-group "<RESOURCE_GROUP>" \
     --name "<FUNCTIONS_APP_NAME>" \
     --key-type hostKey
   

Administración de las claves de acceso

Independientemente del back-end, use los siguientes comandos para enumerar, crear y eliminar claves de acceso:

# List all host keys
az containerapp function keys list \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --key-type hostKey

# List the master key
az containerapp function keys list \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --key-type masterKey

# Create or overwrite a custom host key
az containerapp function keys set \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --key-name "MyCustomKey" \
  --key-value "<YOUR_KEY_VALUE>" \
  --key-type hostKey

# Show a specific key
az containerapp function keys show \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --key-name "<KEY_NAME>" \
  --key-type hostKey

# Delete a host key
az containerapp function keys delete \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --key-name "MyCustomKey" \
  --key-type hostKey

Llame a una función con una clave de acceso

Pase la clave como un parámetro de consulta o un encabezado de solicitud.

# Query parameter
curl "https://<FUNCTIONS_APP_URL>/api/<FUNCTION_NAME>?code=<HOST_KEY>"

# Header
curl "https://<FUNCTIONS_APP_URL>/api/<FUNCTION_NAME>" \
  -H "x-functions-key: <HOST_KEY>"

Contenido relacionado

• Introducción a los secretos de Functions
• Almacenar secretos a nivel de aplicación
• Administración de secretos en Azure Container Apps
• Administrar teclas de función
• Identidades administradas en Container Apps
• Información general sobre Azure Functions en Azure Container Apps