啟用受控服務的客戶自控金鑰

發行項
05/03/2024

注意

若要進一步控制您的資料，您可以新增自己的金鑰，以保護並控制對某些資料類型的存取。 Azure Databricks 有多個客戶管理的密鑰功能。若要比較相關功能，請參閱客戶管理的加密密鑰。

提示

本文說明如何從受控服務的 Azure 金鑰保存庫保存庫設定您自己的密鑰。如需從 Azure 金鑰保存庫受控 HSM 使用密鑰的指示，請參閱為受控服務啟用 HSM 客戶管理的金鑰。

Azure Databricks 控制平面中的受控服務數據會在待用時加密。您可以為受控服務新增客戶管理的金鑰，以協助保護及控制對下列加密資料的存取：

Azure Databricks 控制平面中的筆記本來源。
筆記本的筆記本結果會以互動方式執行，而不是儲存在控制平面中的作業。根據預設，較大的結果也會儲存在工作區根貯體中。您可以將 Azure Databricks 設定為將所有互動式筆記本結果儲存在雲端帳戶中。
秘密管理員 API 所儲存的秘密。
Databricks SQL 查詢和查詢歷程記錄。
個人存取令牌（PAT）或其他認證，用來設定 Git 與 Databricks Git 資料夾的整合。

為工作區新增客戶管理的密鑰加密之後，Azure Databricks 會使用密鑰來控制密鑰的存取權，以加密未來寫入作業至工作區的受控服務數據。現有的數據不會重新加密。數據加密金鑰會在記憶體中快取，以進行數個讀取和寫入作業，並定期從記憶體收回。該數據的新要求需要雲端服務密鑰管理系統的另一個要求。如果您刪除或撤銷金鑰，讀取或寫入受保護的數據會在快取時間間隔結束時失敗。

您可以稍後輪替客戶管理的金鑰（更新）。請參閱稍後輪替密鑰。

此功能不會加密儲存在控制平面外部的數據。如需其他客戶管理的金鑰功能，請參閱客戶管理的加密金鑰

需求

若要針對這些工作使用 Azure CLI，請安裝 Azure CLI 工具並安裝 Databricks 擴充功能：
```
az extension add --name databricks
```
若要針對這些工作使用Powershell，請安裝 Azure PowerShell 並安裝 Databricks Powershell 模組。您也必須登入：
```
Connect-AzAccount
```
若要以使用者身分登入您的 Azure 帳戶，請參閱使用 Azure Databricks 使用者帳戶登入 PowerShell。若要以服務主體身分登入 Azure 帳戶，請參閱使用 Microsoft Entra ID 服務主體登入 PowerShell。

步驟 1：設定金鑰保存庫

您必須建立 Azure 金鑰保存庫實例並設定其許可權。您可以透過 Azure 入口網站、CLI 或 API 來執行此動作。

重要

金鑰保存庫必須與 Azure Databricks 工作區位於相同的 Azure 租使用者中。

這些指示提供多個部署選項的詳細資料：

使用 Azure 入口網站
使用 Azure CLI
使用 Azure Powershell

使用 Azure 入口網站

建立或選取金鑰保存庫：
- 若要建立金鑰保存庫，請移至建立金鑰保存庫的 [Azure 入口網站] 頁面。按一下 [+ 建立]。輸入資源組名、金鑰保存庫名稱、區域和定價層。按一下 [檢閱 + 建立] ，然後按一下 [建立] 。
- 若要使用現有的金鑰保存庫，請複製下一個步驟的金鑰保存庫名稱。
取得 AzureDatabricks 應用程式的物件識別碼：
1. 在 Azure 入口網站中，前往 Microsoft Entra ID。
2. 從資訊看板功能表中選取 [企業應用程式]。
3. AzureDatabricks搜尋，然後按兩下結果中的[企業應用程式]。
4. 從 [屬性] 中複製物件識別碼。
使用 Azure 入口網站將存取原則新增至金鑰保存庫：
1. 流覽至您將用來為工作區的受控服務設定客戶受控密鑰的 Azure 金鑰保存庫。
2. 按兩下左側面板中的 [ 存取原則 ] 索引標籤。
3. 選取頁面頂端找到的 [ 建立] 按鈕 。
4. 在 [權限] 索引標籤中的 [金鑰權限] 區段底下，啟用 [取得]、[將金鑰解除包裝] 和 [包裝金鑰]。
5. 按一下 [下一步] 。
6. 在 [ 主體] 索引標籤上，輸入 AzureDatabricks 並捲動至具有 [應用程式標識符 2ff814a6-3304-4ab8-85cb-cd0e6f879c1d ] 的第一個企業應用程式結果，然後加以選取。
7. 繼續前往 [ 檢閱 + 建立] 索引標籤，然後按兩下 b。

使用 Azure CLI

使用 Azure CLI 來完成下列指示。

建立金鑰保存庫或選取現有的金鑰保存庫：
- 若要建立金鑰保存庫，請使用下列 Azure CLI 命令，並將括弧中的專案取代為您的區域、金鑰保存庫名稱、資源組名和位置：
```
az keyvault create --location <region> \
                   --name <key-vault-name> \
                   --resource-group <resource-group-name> \
                   --location <location> \
                   --enable-purge-protection
```
- 若要使用現有的金鑰保存庫，請複製下一個步驟的金鑰保存庫名稱。

使用 Azure CLI 取得 AzureDatabricks 應用程式的物件識別碼。

az ad sp show --id "2ff814a6-3304-4ab8-85cb-cd0e6f879c1d" \
              --query "id" \
              --output tsv

確認您使用的是正確的 Azure 訂用帳戶：
```
az account set --subscription {subscription_id}
```

使用 Azure Powershell

您可以建立新的金鑰保存庫或使用現有的金鑰保存庫。

建立金鑰保存庫：

$keyVault = New-AzKeyVault -Name <key-vault-name> \
-ResourceGroupName <resource-group-name> \
-Location <location> \
-sku <sku> \
-EnablePurgeProtection

使用現有的金鑰保存庫：

$keyVault = Get-AzKeyVault -VaultName <key-vault-name>

步驟 2：準備金鑰

您可以建立金鑰或使用現有的金鑰。使用您偏好使用的任何工具：Azure 入口網站、Azure CLI 或其他工具。

使用 Azure CLI

在金鑰保存庫下建立金鑰。 KeyType 必須是 RSA。

若要在 CLI 中建立金鑰，請執行此指令：

az keyvault key create --name <key-name> \
                       --vault-name <key-vault-name> \
                       --protection software

記下下列值，您可以從響應中屬性中的 kid 金鑰標識碼取得。您會在後續步驟中使用它們：

金鑰保存庫 URL：包含金鑰保存庫名稱之金鑰標識子的開頭部分。 https://<key-vault-name>.vault.azure.net格式為。
金鑰名稱：金鑰的名稱。
金鑰版本：金鑰的版本。

完整索引鍵識別碼的格式通常為 https://<key-vault-name>.vault.azure.net/keys/<key-name>/<key-version>。非公用雲端中的 Azure 金鑰保存庫金鑰有不同的形式。

若要使用現有的金鑰，而不是建立金鑰，請取得並複製金鑰的這些值，讓您可以在後續步驟中使用它們。在繼續之前，請檢查以確認您現有的金鑰已啟用。

使用 Azure Powershell

如果您打算建立金鑰，您可能需要根據建立金鑰的方式和時間來設定存取原則。例如，如果您最近使用 PowerShell 建立金鑰保存庫，新的金鑰保存庫可能缺少建立密鑰所需的存取原則。下列範例會使用 EmailAddress 參數來設定原則。如需相關詳細數據，請參閱有關 Set-AzKeyVaultAccessPolicy 的 Microsoft 文章。

在新金鑰保存庫上設定存取原則：
```
Set-AzKeyVaultAccessPolicy \
-VaultName $keyVault.VaultName \
-PermissionsToKeys all \
-EmailAddress <email-address>
```

您可以建立金鑰或擷取現有的金鑰：

建立金鑰：

$key = Add-AzKeyVaultKey \
-VaultName $keyVault.VaultName \
-Name <key-name> \
-Destination 'Software'

擷取現有的索引鍵：

$key = Get-AzKeyVaultKey \
-VaultName $keyVault.VaultName \
-Name <key-name>

將具有許可權的存取原則新增至金鑰保存庫：

$managedService = Get-AzureADServicePrincipal \
-Filter "appId eq '2ff814a6-3304-4ab8-85cb-cd0e6f879c1d'"

Set-AzKeyVaultAccessPolicy -VaultName $keyVault.VaultName \
-ObjectId $managedService.ObjectId \
-PermissionsToKeys wrapkey,unwrapkey,get

步驟 3：將金鑰新增至工作區

您可以使用受控服務的客戶自控密鑰來部署新的工作區，或將密鑰新增至現有的工作區。您可以使用 Azure CLI、Powershell、ARM 範本、Azure 入口網站或其他工具來執行這兩個動作。本節包含多個部署選項的詳細數據：

使用沒有範本的 Azure 入口網站
使用沒有範本的 Azure CLI
不使用範本使用 Powershell
使用 ARM 範本套用變更

使用沒有範本的 Azure 入口網站

移至 Azure 入口網站首頁。
按兩下 頁面左上角的 [建立資源 ]。
在搜尋列中，輸入 Azure Databricks 並按兩下 [Azure Databricks ] 選項。
按兩下 Azure Databricks Widget 中的 [建立 ]。
在 [基本] 和 [網络] 索引標籤上輸入輸入欄位的值。
到達 [ 加密 ] 索引標籤之後：
- 若要建立工作區，請在 [受控服務] 區段中啟用 [使用您自己的密鑰 ]。
- 若要更新工作區，請啟用 受控服務。
設定加密欄位。
- 在 [金鑰標識碼] 字段中，貼上 Azure 金鑰保存庫金鑰的金鑰標識碼。
- 在 [訂用帳戶] 下拉式清單中，輸入 Azure 金鑰保存庫密鑰的訂用帳戶名稱。
完成其餘索引標籤，然後按兩下 [ 檢閱 + 建立 ] 或 [儲存 ] （用於更新工作區）。

重要

如果您輪替金鑰，則必須保留舊密鑰 24 小時。

使用沒有範本的 Azure CLI

使用下列命令，將存取原則新增至金鑰保存庫。 <key-vault-name>取代為您在上一步驟中使用的儲存庫名稱，並以應用程式的物件識別碼AzureDatabricks取代 <object-id> 。
```
az keyvault set-policy -n <key-vault-name> \
                       --key-permissions get wrapKey unwrapKey  \
                       --object-id <object-id>
```

建立或更新工作區：

針對建立和更新，請將這些欄位新增至命令：

managed-services-key-name：機碼名稱
managed-services-key-vault：金鑰保存庫 URI
managed-services-key-version：金鑰版本

使用這些欄位建立工作區的範例：

az databricks workspace create --name <workspace-name> \
--resource-group <resource-group-name> \
--location <location> \
--sku premium \
--managed-services-key-name <key-name> \
--managed-services-key-vault <key-vault-uri> \
--managed-services-key-version <key-version>

使用下列欄位更新工作區的範例：

az databricks workspace update --name <workspace-name> \
--resource-group <resource-group-name> \
--managed-services-key-name <key-name> \
--managed-services-key-vault <key-vault-uri> \
--managed-services-key-version <key-version>

重要

如果您輪替金鑰，則必須保留舊密鑰 24 小時。

不使用範本使用 Powershell

若要建立或更新工作區，請將下列參數新增至新密鑰的命令：

ManagedServicesKeyVaultPropertiesKeyName：機碼名稱
ManagedServicesKeyVaultPropertiesKeyVaultUri：金鑰 URI
ManagedServicesKeyVaultPropertiesKeyVersion：金鑰版本

使用這些欄位建立工作區的範例：

New-AzDatabricksWorkspace -Name <workspace-name> \
-ResourceGroupName <resource-group-name> \
-location $keyVault.Location \
-sku premium \
-ManagedServicesKeyVaultPropertiesKeyName $key.Name \
-ManagedServicesKeyVaultPropertiesKeyVaultUri $keyVault.VaultUri \
-ManagedServicesKeyVaultPropertiesKeyVersion $key.Version

這些欄位的範例工作區更新：

Update-AzDatabricksWorkspace -Name <workspace-name> \
-ResourceGroupName <resource-group-name> \
-sku premium \
-ManagedServicesKeyVaultPropertiesKeyName $key.Name \
-ManagedServicesKeyVaultPropertiesKeyVaultUri $keyVault.VaultUri \
-ManagedServicesKeyVaultPropertiesKeyVersion $key.Version

重要

如果您輪替金鑰，則必須保留舊密鑰 24 小時。

使用 ARM 範本套用變更

下列 ARM 範本會使用資源的 API 版本2023-02-01Microsoft.Databricks/workspaces，使用客戶管理的密鑰來建立新的工作區。將此文字儲存至名為的 databricks-cmk-template.json檔案。

此範例範本不包含所有可能的 Azure Databricks 功能，例如提供您自己的 VNet 來部署工作區。

重要

如果您已經使用範本，請將此範本的額外參數、資源和輸出合併至現有的範本。

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "workspaceName": {
      "type": "string",
      "metadata": {
        "description": "The name of the Azure Databricks workspace to create."
      }
    },
    "pricingTier": {
      "type": "string",
      "defaultValue": "premium",
      "allowedValues": [
        "standard",
        "premium"
      ],
      "metadata": {
        "description": "The pricing tier of workspace."
      }
    },
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]",
      "metadata": {
        "description": "Location for all resources."
      }
    },
    "apiVersion": {
      "type": "string",
      "defaultValue": "2023-02-01",
      "allowedValues":[
        "2023-02-01",
        "2021-04-01-preview"
      ],
      "metadata": {
        "description": "The api version to create the workspace resources"
      }
    },
    "keyvaultUri": {
      "type": "string",
      "metadata": {
        "description": "The Key Vault URI for customer-managed key for managed services"
      }
    },
    "keyName": {
      "type": "string",
      "metadata": {
        "description": "The key name used for customer-managed key for managed services"
      }
    },
    "keyVersion": {
      "type": "string",
      "metadata": {
        "description": "The key version used for customer-managed key for managed services"
      }
    }
  },
  "variables": {
    "managedResourceGroupName": "[concat('databricks-rg-', parameters('workspaceName'), '-', uniqueString(parameters('workspaceName'), resourceGroup().id))]"
  },
  "resources": [
    {
      "type": "Microsoft.Databricks/workspaces",
      "name": "[parameters('workspaceName')]",
      "location": "[parameters('location')]",
      "apiVersion": "[parameters('apiVersion')]",
      "sku": {
        "name": "[parameters('pricingTier')]"
      },
      "properties": {
        "ManagedResourceGroupId": "[concat(subscription().id, '/resourceGroups/', variables('managedResourceGroupName'))]",
        "encryption": {
          "entities": {
             "managedServices": {
                "keySource": "Microsoft.Keyvault",
                "keyVaultProperties": {
                   "keyVaultUri": "[parameters('keyvaultUri')]",
                   "keyName": "[parameters('keyName')]",
                   "keyVersion": "[parameters('keyVersion')]"
                }
             }
          }
        }
      }
    }
  ],
  "outputs": {
    "workspace": {
      "type": "object",
      "value": "[reference(resourceId('Microsoft.Databricks/workspaces', parameters('workspaceName')))]"
    }
  }
}

如果您已經使用另一個範本，您可以將此範本的參數、資源和輸出合併至現有的範本。

若要使用此範本來建立或更新工作區，請選擇下列其中一個部署選項：

使用 Azure CLI 套用範本
使用 Azure 入口網站套用範本

使用 Azure CLI 套用範本

若要使用 Azure CLI 建立新的工作區，請執行下列命令：

az deployment group create --resource-group <resource-group-name>  \
                           --template-file <file-name>.json \
                           --parameters workspaceName=<new-workspace-name> \
                           keyvaultUri=<keyvaultUrl> \
                           keyName=<keyName> keyVersion=<keyVersion>

若要更新現有的工作區，以使用客戶管理的金鑰工作區（或使用 Azure CLI 輪替現有的金鑰：

如果您的部署工作區的 ARM 範本從未新增客戶管理的金鑰，請新增 resources.properties.encryption 區段及其相關參數。請參閱本文稍早的範本。
1. resources.properties.encryption從範本新增區段。
2. 在區 parameters 段中，從樣本新增三個新參數 keyvaultUri、 keyName和 keyVersion 。

執行與建立新工作區相同的命令。只要資源組名和工作區名稱與您現有的工作區相同，此命令就會更新現有的工作區，而不是建立新的工作區。

az deployment group create --resource-group <existing-resource-group-name>  \
                           --template-file <file-name>.json \
                           --parameters workspaceName=<existing-workspace-name> \
                           keyvaultUri=<keyvaultUrl> \
                           keyName=<keyName> keyVersion=<keyVersion>

除了金鑰相關參數的變更以外，請使用用於建立工作區的相同參數。

重要

如果您輪替金鑰，則必須保留舊密鑰 24 小時。

使用 Azure 入口網站套用範本

若要使用 Azure 入口網站中的範本來建立或更新工作區：

移至 [ 自定義部署] 頁面。
按一下 [Build your own template in the editor] $在編輯器中建置您自己的範本$。
貼上 JSON。
按一下 [檔案] 。
填寫參數。

若要更新現有的工作區，請使用您用來建立工作區的相同參數。若要第一次新增索引鍵，請新增三個索引鍵相關參數。若要輪替金鑰，請變更部分或所有與金鑰相關的參數。請確定資源組名和工作區名稱與您現有的工作區相同。如果相同，此命令會更新現有的工作區，而不是建立新的工作區。

除了金鑰相關參數的變更以外，請使用用於建立工作區的相同參數。
按一下 [檢閱 + 建立]。
如果沒有驗證問題，請按兩下 [ 建立]。

重要

如果您輪替金鑰，則必須保留舊密鑰 24 小時。

如需詳細資訊，請參閱 Azure 文章快速入門：使用 Azure 入口網站建立和部署 ARM 範本。

步驟 4 （選擇性）：重新匯入筆記本

在您一開始為現有工作區新增受控服務的金鑰之後，只有未來的寫入作業會使用您的密鑰。現有的數據不會重新加密。

您可以匯出所有筆記本，然後重新匯入這些筆記本，讓加密數據的密鑰受到密鑰的保護和控制。您可以使用匯出和匯入工作區 API。

稍後輪替金鑰

如果您已經針對受控服務使用客戶管理的金鑰，您可以使用新的金鑰版本或全新的金鑰來更新工作區。這稱為 金鑰輪替。

在金鑰保存庫中建立新的金鑰或輪替現有的金鑰。請參閱步驟 1：設定 Key Vault。

請確定新金鑰具有適當的許可權。
確認您的範本具有正確的 API 版本。它必須等於或高於 2021-04-01-preview。
使用入口網站、CLI 或 PowerShell 以新金鑰更新工作區。請參閱步驟 3：將密鑰新增至工作區，並遵循工作區更新的指示。請確定您針對資源組名和工作區名稱使用相同的值，以便更新現有的工作區，而不是建立新的工作區。除了金鑰相關參數的變更以外，請使用用於建立工作區的相同參數。

重要

如果您輪替金鑰，則必須保留舊密鑰 24 小時。
選擇性地匯出並重新匯入現有的筆記本，以確保所有現有的筆記本都使用新的密鑰。

疑難排解

意外刪除金鑰

如果您在 Azure 金鑰保存庫中刪除金鑰，工作區登入將會開始失敗，且 Azure Databricks 無法讀取任何筆記本。若要避免這種情況，建議您啟用虛刪除。此選項可確保如果刪除金鑰，則可以在 30 天內復原。如果已啟用虛刪除，您可以直接重新啟用金鑰以解決問題。

金鑰更新失敗，因為 Key Vault 權限

如果您在建立工作區時遇到問題，請檢查 Key Vault 是否有正確的權限。從 Azure 傳回的錯誤可能無法正確指出這是根本原因。此外，必要的權限為 get、 wrapKey與 unwrapKey。請參閱步驟 1：設定 Key Vault。

遺失的金鑰無法復原

如果您遺失金鑰且無法加以復原，則會無法復原以該金鑰加密的所有筆記本資料。

Share via

啟用受控服務的客戶自控金鑰

需求

步驟 1：設定金鑰保存庫

使用 Azure 入口網站

使用 Azure CLI

使用 Azure Powershell

步驟 2：準備金鑰

使用 Azure CLI

使用 Azure Powershell

步驟 3：將金鑰新增至工作區

使用沒有範本的 Azure 入口網站

使用沒有範本的 Azure CLI

不使用範本使用 Powershell

使用 ARM 範本套用變更

使用 Azure CLI 套用範本

使用 Azure 入口網站套用範本

步驟 4 （選擇性）：重新匯入筆記本

稍後輪替金鑰

疑難排解

意外刪除金鑰

金鑰更新失敗，因為 Key Vault 權限

遺失的金鑰無法復原

意見反應

意見反應

其他資源

Share via

啟用受控服務的客戶自控金鑰

需求

步驟 1：設定 金鑰保存庫

使用 Azure 入口網站

使用 Azure CLI

使用 Azure Powershell

步驟 2：準備金鑰

使用 Azure CLI

使用 Azure Powershell

步驟 3：將金鑰新增至工作區

使用沒有範本的 Azure 入口網站

使用沒有範本的 Azure CLI

不使用範本使用 Powershell

使用 ARM 範本套用變更

使用 Azure CLI 套用範本

使用 Azure 入口網站 套用範本

步驟 4 （選擇性）：重新匯入筆記本

稍後輪替金鑰

疑難排解

意外刪除金鑰

金鑰更新失敗，因為 Key Vault 權限

遺失的金鑰無法復原

意見反應

意見反應

其他資源

步驟 1：設定金鑰保存庫

使用 Azure 入口網站套用範本