在 Azure Functions 中使用存取金鑰

Azure Functions 可讓您使用秘密金鑰，來增加存取函式端點的困難度。 本文說明 Functions 支援的各種存取金鑰，以及如何使用存取金鑰。

雖然存取金鑰會針對不想要的存取緩解一定程度的風險，但是在生產環境中，您應該考慮其他選項來保護 HTTP 端點的安全。 例如，在公用應用程式中散發共用密碼並不是很好的做法。 如果您的函式是從公用用戶端呼叫，您應該考慮實作這些或其他安全性機制：

• 啟用 App Service 驗證/授權
• 使用「Azure API 管理」(APIM) 來驗證要求
• 將函式應用程式部署至虛擬網路
• 以隔離方式部署函式應用程式

存取金鑰為 HTTP 觸發函式提供 HTTP 授權的基礎。 如需詳細資訊，請參閱授權層級。

了解金鑰

存取金鑰的範圍及其支援的動作取決於存取金鑰的類型。

金鑰類型	金鑰名稱	HTTP 驗證層級	描述
Function	default 或使用者定義	function	只允許存取特定函式端點。
主機	default 或使用者定義	function	允許存取函式應用程式中的所有函式端點。
主機	_master	admin	在函式應用程式中，特殊主機金鑰還可以提供執行階段 REST API 的系統管理存取權。 無法撤銷此金鑰。 由於主要金鑰會在您的函式應用程式中授與提高的權限，因此不應該與第三方共用此金鑰，或是在原生用戶端應用程式中散發它。
系統	視延伸模組而定	n/a	特定的延伸模組可能需要系統管理的金鑰，才能存取 Webhook 端點。 系統金鑰是專為內部元件所呼叫的延伸模組特有函式端點而設計。 例如，事件方格觸發程序要求訂用帳戶在呼叫觸發程序端點時使用系統金鑰。 Durable Functions 也會使用系統金鑰來呼叫長期工作延伸模組 API。 系統金鑰只能由特定的延伸模組建立，而且您無法明確設定其值。 如同其他金鑰，您可以從入口網站或使用金鑰 API 來產生新的金鑰值。

每個金鑰均為具名以供參考，並且在函式和主機層級有一預設金鑰 (名稱為 default)。 函式金鑰的優先順序高於主機金鑰。 當您使用相同的名稱來定義兩個金鑰時，一律會使用函式金鑰。

下表將比較各種存取金鑰的用途：

動作	範圍	金鑰類型
執行函式	特定函式	函式
執行函式	任何函式	函式或主機
呼叫 admin 端點	函式應用程式	僅限主機
呼叫長期工作延伸模組 API	函式應用程式*	系統
呼叫延伸模組特定的 Webhook (內部)	函式應用程式*	系統

^*由延伸模組決定的範圍。

重要需求

在 Functions 中，存取金鑰是隨機產生的 32 位元組陣列，其編碼為 URL 安全的 Base 64 字串。 雖然您可以產生本身的存取金鑰並搭配使用 Functions，但強烈建議您改為允許 Functions 為您產生所有存取金鑰。

函式產生的存取金鑰包含特殊簽章和總和檢查碼值，這些值指出存取金鑰的類型，以及它是由 Azure Functions 產生的。 在金鑰本身中擁有這些額外的元件，可讓您更輕鬆地判斷在安全性掃描和其他自動化程序中找到的這類密碼的來源。

若要允許 Functions 為您產生金鑰，請勿將金鑰 value 提供給任何可用來產生金鑰的 API。

管理金鑰儲存體

金鑰會當作您函數應用程式的一部分儲存於 Azure 中，並在加密後靜置。 依預設，金鑰會儲存在帳戶的 Blob 儲存體容器中，而此帳戶是由 AzureWebJobsStorage 設定所提供的。 您可以使用 AzureWebJobsSecretStorageType 設定來覆寫此預設行為，並改為將金鑰儲存在下列其中一個替代位置：

Location	值	Description
次要儲存體帳戶	blob	將金鑰儲存在 Blob 儲存體中，該儲存體使用的儲存體帳戶與 Functions 執行階段所使用的帳戶不同。 所使用的特定帳戶和容器是由設定在 AzureWebJobsSecretStorageSas 中的共用存取簽章 (SAS) URL 所定義的。 當 SAS URL 變更時，您必須維護 AzureWebJobsSecretStorageSas 設定。
Azure Key Vault	keyvault	AzureWebJobsSecretStorageKeyVaultUri 中設定的金鑰保存庫會用於儲存金鑰。
檔案系統	files	金鑰會保存在本機檔案系統上，這是 Functions v1.x 中的預設值。 不建議使用檔案系統儲存體。
Kubernetes 秘密	kubernetes	AzureWebJobsKusbnetesSecretName 中的資源集可用來儲存金鑰。 僅在函式應用程式部署至 Kube 時支援。 當您使用 Azure Functions Core Tools 將應用程式部署至 Kube 叢集時，其會自動產生值。

使用 Key Vault 進行金鑰儲存時，所需的應用程式設定取決於受控識別類型，無論是系統指派還是使用者指派。

設定名稱	系統指派	使用者指派	應用程式註冊
AzureWebJobsSecretStorageKeyVaultUri
AzureWebJobsSecretStorageKeyVaultClientId	X
AzureWebJobsSecretStorageKeyVaultClientSecret	X	X
AzureWebJobsSecretStorageKeyVaultTenantId	X	X

使用存取金鑰

HTTP 觸發函式通常可以使用下列格式的 URL 來呼叫：https://<APP_NAME>.azurewebsites.net/api/<FUNCTION_NAME>。 當給定函式的授權層級設定為 anonymous 以外的值時，您還必須在要求中提供存取金鑰。 存取金鑰可從使用 ?code= 查詢字串中的 URL 或要求標頭 (x-functions-key) 中提供。 如需詳細資訊，請參閱存取金鑰授權。

若要存取執行階段 REST API (在 /admin/ 下)，您必須在 x-functions-key 要求標頭中提供主要金鑰 (_master)。 您可以使用 functionsRuntimeAdminIsolationEnabled 網站屬性移除系統管理端點。

取得函式存取金鑰

您可以使用這些 Azure Resource Manager API，以程式設計方式取得函式和主機金鑰：

• 列出 Functions 金鑰
• 列出主機金鑰
• 列出 Function 金鑰插槽
• 列出主機金鑰插槽。

若要了解如何呼叫 Azure Resource Manager API，請參閱 Azure REST API 參考。

您可以使用這些方法來取得存取金鑰，而不需要使用 REST API。

Azure 入口網站

1. 登入 Azure 入口網站，然後搜尋並選取 [函式應用程式]。

2. 選取您想要使用的函式應用程式。

3. 在左側窗格中，展開 [函式]，然後選取 [應用程式金鑰]。

   [應用程式金鑰] 頁面隨即出現。 在此頁面上會顯示主機金鑰，可用來存取應用程式中的任何函式。 系統金鑰也會顯示，讓任何系統管理員等級的人員能夠存取所有函式應用程式 API。

您也可以透過僅為特定函式使用的金鑰來實作最小權限。 您可以從特定 HTTP 觸發函式的 [函式金鑰] 索引標籤取得函式特定金鑰。

Azure CLI

在 Azure Cloud Shell 中執行下列指令碼，其輸出是 default 主機金鑰，可用於存取函式應用程式中的任何 HTTP 觸發函式。

az functionapp keys list --resource-group <RESOURCE_GROUP> --name <APP_NAME> --query functionKeys.default --output tsv

在此指令碼中，分別將 <RESOURCE_GROUP> 和 <APP_NAME> 取代為資源群組和函式應用程式名稱。

因為輸出包含敏感性資訊，因此不會保存輸出或保護任何保存的檔案輸出。

Azure PowerShell

執行下列指令碼，其輸出是 default 主機金鑰，可用於存取函數應用程式中的任何 HTTP 觸發函式。

$subName = '<SUBSCRIPTION_ID>'
$rGroup = '<RESOURCE_GROUP>'
$appName = '<APP_NAME>'
$path = "/subscriptions/$((Get-AzContext).Subscription.Id)/resourceGroups/$rGroup/providers/Microsoft.Web/sites/$appName/host/default/listKeys?api-version=2018-11-01"
((Invoke-AzRestMethod -Path $path -Method POST).Content | ConvertFrom-JSON).functionKeys.default

在此指令碼中，分別將 <RESOURCE_GROUP> 和 <APP_NAME> 取代為資源群組和函式應用程式名稱。

更新或建立存取金鑰

當更新或建立存取金鑰值時，您必須手動將更新的金鑰值重新散發給所有呼叫您函式的用戶端。

您可以使用這些 Azure Resource Manager API，以程序設計方式更新函式和主機金鑰，或建立新的金鑰：

• 建立或更新函式密碼
• 建立或更新函式密碼插槽
• 建立或更新主機密碼
• 建立或更新主機密碼插槽

若要了解如何呼叫 Azure Resource Manager API，請參閱 Azure REST API 參考。

您可以使用這些方法來取得存取金鑰，而不需要手動建立 REST API 的呼叫。

Azure 入口網站

1. 登入 Azure 入口網站，然後搜尋並選取 [函式應用程式]。

2. 選取您想要使用的函式應用程式。

3. 在左側窗格中，展開 [函式]，然後選取 [應用程式金鑰]。

   [應用程式金鑰] 頁面隨即出現。 在此頁面上會顯示主機金鑰，可用來存取應用程式中的任何函式。 系統金鑰也會顯示，讓任何系統管理員等級的人員能夠存取所有函式應用程式 API。

4. 選取要更新之金鑰旁邊的 [更新金鑰值]，然後選取 [更新並儲存]。

您可以從特定 HTTP 觸發函式的 [函式金鑰] 索引標籤續訂函式金鑰。

Azure CLI

在 Azure Cloud Shell 中執行下列指令碼，其會以 Functions 產生的新金鑰值來更新 default 主機金鑰。

az functionapp keys set --resource-group <RESOURCE_GROUP> --name <APP_NAME> --key-type functionKeys --key-name default

在此指令碼中，分別將 <RESOURCE_GROUP> 和 <APP_NAME> 取代為資源群組和函式應用程式名稱。 此指令碼已建立，以在 Azure Cloud Shell (Bash) 中執行。 您必須加以修改，才能在 Windows 終端機中執行。

函式所產生的新金鑰值會隨即顯示以供參考。 這個新的金鑰值必須安全地散發給任何依賴主機金鑰的應用程式。 因為輸出包含敏感性資訊，因此不會保存輸出或保護任何保存的檔案輸出。

Azure PowerShell

執行下列指令碼，其會以 Functions 產生的新金鑰值使用 REST API 來更新 default 主機金鑰。

# Variables - replace these with your actual values
$resourceGroupName = "<RESOURCE_GROUP>"
$functionAppName = "<APP_NAME>" 

# Construct the URI for the REST API call
$uri = "https://management.azure.com/subscriptions/$((Get-AzContext).Subscription.Id)/resourceGroups/$resourceGroupName/providers/Microsoft.Web/sites/$functionAppName/host/default/listkeys?api-version=2021-02-01"

# Construct the body of the request
$body = @{
    properties = @{
        name = "default"
    }
} | ConvertTo-Json

# Invoke the REST API to create or update the host-level secret
$response = Invoke-AzRestMethod -Method Post -Uri $uri -Payload $body

# Output the updated key for reference
($response.Content | ConvertFrom-Json).functionKeys.default

在此指令碼中，分別將 <RESOURCE_GROUP> 和 <APP_NAME> 取代為資源群組和函式應用程式名稱。

函式所產生的新金鑰值會隨即傳回以供參考。 這個新金鑰值必須安全地散發給任何依賴主機金鑰的應用程式。 因為輸出包含敏感性資訊，因此不會保存輸出或保護任何保存的檔案輸出。

刪除存取金鑰

您可以使用這些 Azure Resource Manager API，以程式設計方式刪除函式和主機金鑰：

• 刪除函式密碼
• 刪除函式密碼插槽
• 刪除主機密碼
• 刪除主機密碼插槽

若要了解如何呼叫 Azure Resource Manager API，請參閱 Azure REST API 參考。

相關內容

• 保護 Azure Functions
• Azure Functions HTTP 觸發程序
• 管理函數應用程式