在 Azure 容器應用程式上配置 Functions 主機金鑰儲存

函式存取金鑰是函數執行時用來保護 HTTP 觸發端點的認證憑證。當呼叫者呼叫 HTTP 函式時，會包含一個金鑰作為 ?code= 查詢參數或 x-functions-key 標頭。執行時會驗證金鑰並授權或拒絕請求。

存取金鑰和應用程式層級的秘密不一樣。存取金鑰保護 誰可以呼叫你的函式，而應用程式層級的祕密則保護 你函式所連接的對象。

何時使用存取鍵

劇本	為什麼存取金鑰合適
第三方 webhook	像 GitHub、Stripe 或 Twilio 這類服務提供者會透過 URL 和 secret 呼叫你的函式。存取金鑰會直接插入呼叫者預期的 `?code=` 模式。
服務對服務通話	後端服務 A 透過 HTTP 呼叫函式 B。使用共用金鑰比起為僅限內部使用的呼叫設定 Microsoft Entra 應用程式註冊更簡單。
事件網格訂閱	Event Grid 會用平台自動管理的系統金鑰驗證並呼叫你的函式端點。
開發/測試認證	開發過程中你需要基本的認證，但不需要設定完整的 OAuth/OIDC。存取金鑰提供低摩擦的認證閘門，無需身份設定。
遷移相容性	現有的 Azure Functions 應用程式已經使用存取金鑰。移轉至 Container Apps 時，您需要相同的金鑰型驗證，以避免造成呼叫者中斷。

Note

對於面向使用者的 API、零信任工作負載或每使用者授權情境，請使用 Microsoft Entra ID / OAuth 2.0 取代存取金鑰。存取金鑰是共享的秘密，沒有身份層級的稽核紀錄。

先決條件

一個有有效訂閱的 Azure 帳號。免費註冊帳號。
Azure CLI版本 2.40.0 或更高版本。
容器應用程式中的現有 Azure Functions 應用程式，或是建立容器的權限。

存取金鑰類型

Functions 執行時管理四種類型的鍵：

鍵類型	Scope	Purpose
主鑰匙（`_master`）	整個函式應用程式	管理員層級存取所有功能與 `/admin/*` 管理端點。不能被撤銷，只能輪替。
主機金鑰（`default` +自訂）	整個函式應用程式	授權呼叫應用程式中任何 HTTP 觸發函式。
功能鍵（`default` +自訂）	單一函數	授權對單一特定函式的呼叫。提供比主機金鑰更細緻的控制。
系統金鑰	擴展端點	供事件方格 Webhook 訂用帳戶和 Durable Functions 等平台擴充功能使用。自動管理。

選擇儲存後端

設定環境 AzureWebJobsSecretStorageType 變數控制執行時存取金鑰的持久位置。 Azure 容器應用程式支援三個生產級後端。

後端	設定值	自動產生金鑰	外部依賴	最適合用於
Container Apps secret store	`containerapps`	否 - 您將金鑰佈建為 Container Apps 祕密	None	大多數工作負載（建議）
Azure Key Vault	`keyvault`	否 - 手動建立觸發器	金鑰保存庫實例	集中治理與合規稽核
Azure Blob 儲存體	`blob`	是的	記憶體帳戶	舊有應用程式或現有 `AzureWebJobsStorage` 帳號

請牢記以下後端考量：

執行時不會自動選擇容器應用程式的秘密儲存。如果你沒有設定AzureWebJobsSecretStorageType或設定為無法辨識的值，Functions 主機會在可用時AzureWebJobsStorage使用 Blob 儲存體。
保持 AzureWebJobsStorage 設定以進行儲存健康檢查及依賴儲存的功能。
不要設定 AzureWebJobsSecretStorageType 為 files。容器應用程式檔案系統是短暫的，因此當應用程式縮減到零、重啟或部署新版本時，後端儲存的金鑰會遺失。

秘密名稱模式

儲存金鑰的命名規則取決於儲存後端。

容器應用程式的秘密儲存庫則採用不同的慣例。 Functions 主機會從 /run/secrets/functions-keys/ 的磁碟區掛接檔案讀取金鑰。每個檔案使用虛點名稱（例如 host.master），但容器應用程式的秘密名稱僅允許 使用小寫字母數字和破折號。當你掛載秘密磁碟區時，必須將 path 欄位明確設為函式主機期望的點分檔案名稱（例如 secretRef: host-master → path: host.master）。平台不會自動進行姓名轉換。

鍵類型	容器應用程式機密名稱（破折號）	磁碟區掛接 `path` (點)
主鑰匙	`host-master`	`host.master`
預設主機金鑰	`host-function-default`	`host.function.default`
自訂主機金鑰	`host-function-<name>`	`host.function.<name>`
特定函式的預設函式鍵	`functions-<functionname>-default`	`functions.<functionName>.default`
特定函數的自訂函式鍵	`functions-<functionname>-<keyname>`	`functions.<functionName>.<keyName>`
系統金鑰	`host-systemkey-<extension>`	`host.systemKey.<extension>`

金鑰保存庫後端會使用雙破折號 (--) 慣例，將每個金鑰儲存為個別金鑰保存庫祕密：

鍵類型	秘密名稱格式	範例
主鑰匙	`host--masterKey--master`	`host--masterKey--master`
功能鍵（預設）	`host--functionKey--default`	`host--functionKey--default`
功能鍵（自訂）	`host--functionKey--<name>`	`host--functionKey--MyApiClient`
系統金鑰	`host--systemKey--<extension>`	`host--systemKey--eventgrid_extension`
每個函式金鑰	`function--<functionName>--<keyName>`	`function--myhttpfunc--default`

Blob 儲存體後端會把金鑰以 JSON 檔案儲存在 azure-webjobs-secrets blob 容器中。所有主機層鍵（主鍵、功能鍵和系統鍵）都集中儲存在一個 host.json blob 中。每個函式金鑰會儲存在以每個函式命名的個別 Blob 中。

Blob 路徑	內容
`<SITE_SLOT_NAME>/host.json`	的 JSON 檔案包含`masterKey`、`functionKeys`和`systemKeys`
`<SITE_SLOT_NAME>/<FUNCTION_NAME>.json`	包含特定函式鍵的 JSON 檔案

小提示

在排除故障時，請在後端儲存庫中搜尋這些模式，以確認金鑰是否正確設定。

設定容器應用程式秘密儲存庫

Container Apps 的秘密儲存庫是推薦的後端。金鑰會保留在容器應用程式平台內，無需使用外部儲存空間或金鑰保存庫。 Azure Resource Manager 的活動日誌會追蹤秘密和環境變數的變更。

使用此後端時，Functions 主機會從磁碟區掛接於 /run/secrets/functions-keys/ 的檔案讀取金鑰。主機 不會自動產生金鑰。你必須將每個金鑰建立為容器應用程式的秘密，平台會掛載它們作為檔案讓主機讀取。

Important

容器應用程式的秘密儲存庫 從主機的角度來看是唯讀的。主機會讀取已掛載的金鑰檔案，但從不寫入。如果缺少某個必需的金鑰，主機不會自動生成。

請進入 Azure 入口網站的 Functions 容器應用程式。
在設定中，選擇 環境變數。
選擇新增，並輸入以下數值：

Property 價值

Name AzureWebJobsSecretStorageType

價值 containerapps
選擇儲存，然後選擇套用以確認變更。

Property	價值
Name	`AzureWebJobsSecretStorageType`
價值	`containerapps`

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

步驟 2：產生並儲存存取權密鑰

產生金鑰值並儲存為容器應用程式的機密資訊。至少你需要主金鑰和 預設主機金鑰。

Portal
Azure CLI

在你的 Functions 容器應用程式中，在設定中選擇秘密。
選擇新增並輸入以下數值：

Property 價值

Name host-master

Type 容器應用程序密鑰

價值一個隨機產生的鍵值。
選取 ，然後新增。
對 host-function-default 重複，並用另一個隨機產生的值。
若要新增每個函式金鑰，請新增名為 functions-<functionname>-default 的祕密 (全部小寫)。

Property	價值
Name	`host-master`
Type	容器應用程序密鑰
價值	一個隨機產生的鍵值。

# 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"

要新增針對每個函數的鍵（例如，針對名為 MyHttpFunc 的函數）：

FUNC_KEY=$(openssl rand -hex 32)

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

Note

容器應用程式的秘密名稱僅允許使用小寫字母、數字和破折號。你必須在磁碟區設定中明確將欄位設 path 為函式主機期望的虛線檔名（例如， secretRef: host-master → path: host.master）。如果沒有明確的 path，磁碟上的檔案會保留含破折號的名稱，且 Functions 主機將找不到金鑰。

步驟 3：設定磁碟區掛載

將祕密掛接為 /run/secrets/functions-keys/ 中的檔案。

Portal
Azure CLI

在你的 Functions 容器應用程式中，在應用程式的選項中，選擇 修訂版與複本。
選取 [建立新修訂]。
在 「縮放與體積」 標籤中，在 「體積」下，選擇 「新增」。
輸入下列值：

Property 價值

磁碟區類型 祕密

Name functions-keys
對於每個機密，將 Path 欄位設為函式主機所預期的點分隔的檔案名稱（例如，將 host-master 設為路徑 host.master，將 host-function-default 設為路徑 host.function.default）。
選取 ，然後新增。
在容器標籤中，選擇你的容器，然後選擇編輯。
選擇 「磁碟掛載 」標籤，然後選擇 「新增」。
輸入下列值：

Property 價值

磁碟區名稱 functions-keys

裝載路徑 /run/secrets/functions-keys
選擇儲存，然後選擇建立來部署新的版本。

Property	價值
磁碟區類型	祕密
Name	`functions-keys`

Property	價值
磁碟區名稱	`functions-keys`
裝載路徑	`/run/secrets/functions-keys`

匯出應用程式的 YAML、新增磁碟區和磁碟區掛接，然後套用：

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

步驟四：驗證

應用程式重新啟動後，請確認按鍵是否正常：

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

你也可以查看應用程式日誌中的訊息 Resolved secret storage provider ContainerAppsSecretsRepository，確認主機正在使用 Container Apps 的秘密儲存庫。

旋轉鍵

要旋轉金鑰，請更新容器應用程式的秘密並重新啟動應用程式：

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>"

Note

所有複製品共享相同的掛載秘密。重新啟動後，每個副本都會擷取更新的鍵值。

將金鑰保存庫或 Blob 儲存體設定為儲存

配置金鑰保存庫
配置 Blob 儲存體

金鑰保存庫後端將存取金鑰儲存為金鑰保存庫機密，提供企業級稽核與存取控制。

建立一個金鑰保存庫（如果你還沒有）：

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

在您的容器應用程式中啟用管理身份（如果尚未啟用）：

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

將 金鑰保存庫秘密員角色指派給受控識別。執行時需要讀寫權限來建立和管理金鑰：

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"

設定儲存類型與金鑰保存庫 URI：

針對系統指派的身分識別：

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

對於使用者指派的身份，也可以設定用戶端 ID：

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>"

透過列出金鑰來觸發金鑰的建立：

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

Blob 儲存體後端讓執行時能自動產生和管理存取金鑰。請在已經擁有儲存帳號且不需要為 AzureWebJobsStorage 進行集中治理時使用這個選項。

在您的容器應用程式中啟用管理身份（如果尚未啟用）：

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

將 Storage Blob Data Contributor 角色授與儲存體帳戶上的受控識別：

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"

設定儲存類型：

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

執行時會在下一次冷啟動時自動產生金鑰。請驗證：

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

管理存取金鑰

無論後端為何，請使用以下指令來列出、建立及刪除存取金鑰：

Note

至少要維持一個副本在運作，以執行這些金鑰管理操作。

列出所有主機金鑰：

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

列出主鑰匙：

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

建立或覆寫自訂主機金鑰：

az containerapp function keys set \
  --resource-group "<RESOURCE_GROUP>" \
  --name "<FUNCTIONS_APP_NAME>" \
  --key-name "MyCustomKey" \
  --key-value "<YOUR_KEY_VALUE>" \
  --key-type hostKey

顯示一個特定的鍵：

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

刪除主機金鑰：

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

呼叫一個帶有存取金鑰的函式

將金鑰作為查詢參數或請求標頭傳遞。

# 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>"

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-08-14

在 Azure 容器應用程式 上配置 Functions 主機金鑰儲存

何時使用存取鍵

先決條件

存取金鑰類型

選擇儲存後端

秘密名稱模式

設定容器應用程式秘密儲存庫

步驟 1：設定儲存類型

步驟 2：產生並儲存存取權密鑰

步驟 3：設定磁碟區掛載

步驟四：驗證

旋轉鍵

將 金鑰保存庫 或 Blob 儲存體 設定為儲存

管理存取金鑰

呼叫一個帶有存取金鑰的函式

相關內容

意見反應

其他資源

在 Azure 容器應用程式上配置 Functions 主機金鑰儲存

將金鑰保存庫或 Blob 儲存體設定為儲存