使用 C# 配置客户托管密钥Configure customer-managed-keys using C#

Azure 数据资源管理器对静态存储帐户中的所有数据进行加密。Azure Data Explorer encrypts all data in a storage account at rest. 默认情况下,使用 Microsoft 管理的密钥对数据进行加密。By default, data is encrypted with Microsoft-managed keys. 为了更进一步控制加密密钥,可以提供客户管理的密钥来用于对数据进行加密。For additional control over encryption keys, you can supply customer-managed keys to use for data encryption. 客户管理的密钥必须存储在 Azure Key Vault 中。Customer-managed keys must be stored in an Azure Key Vault. 你可以创建自己的密钥并将其存储在密钥保管库中,或者使用 Azure Key Vault API 来生成密钥。You can create your own keys and store them in a key vault, or you can use an Azure Key Vault API to generate keys. Azure 数据资源管理器群集和密钥保管库必须在同一个区域中,但可以在不同的订阅中。The Azure Data Explorer cluster and the key vault must be in the same region, but they can be in different subscriptions. 有关客户管理的密钥的详细说明,请参阅客户管理的密钥与 Azure Key VaultFor a detailed explanation on customer-managed keys, see customer-managed keys with Azure Key Vault. 本文将介绍如何配置客户管理的密钥。This article shows you how to configure customer-managed keys.

若要使用 Azure 数据资源管理器配置客户管理的密钥,必须在密钥保管库上设置两个属性:“软删除”和“不清除”。 To configure customer-managed keys with Azure Data Explorer, you must set two properties on the key vault: Soft Delete and Do Not Purge. 默认情况下未启用这些属性。These properties aren't enabled by default. 若要启用这些属性,请使用 PowerShellAzure CLITo enable these properties, use PowerShell or Azure CLI. 仅支持 RSA 密钥以及密钥大小 2048。Only RSA keys and key size 2048 are supported.

备注

先导和后继群集上不支持使用客户管理的密钥进行数据加密。Data encryption using customer managed keys is not supported on leader and follower clusters.

为群集分配标识Assign an identity to the cluster

若要为群集启用客户管理的密钥,请先将一个系统分配的托管标识分配给该群集。To enable customer-managed keys for your cluster, first assign a system-assigned managed identity to the cluster. 你将使用此托管标识授予群集访问密钥保管库的权限。You'll use this managed identity to grant the cluster permissions to access the key vault. 若要配置系统分配的托管标识,请参阅托管标识To configure system-assigned managed identities, see managed identities.

创建新的 Key VaultCreate a new key vault

若要使用 PowerShell 创建新的 Key Vault,请调用 New-AzKeyVaultTo create a new key vault using PowerShell, call New-AzKeyVault. 必须为用来存储客户管理的密钥(用于 Azure 数据资源管理器加密)的 Key Vault 启用两项密钥保护设置:“软删除”和“不要清除”。 The key vault that you use to store customer-managed keys for Azure Data Explorer encryption must have two key protection settings enabled, Soft Delete and Do Not Purge. 请将以下示例中括号中的占位符值替换为你自己的值。Replace the placeholder values in brackets with your own values in example below.

$keyVault = New-AzKeyVault -Name <key-vault> `
    -ResourceGroupName <resource_group> `
    -Location <location> `
    -EnableSoftDelete `
    -EnablePurgeProtection

配置 Key Vault 访问策略Configure the key vault access policy

接下来,配置密钥保管库的访问策略,使群集有权访问密钥保管库。Next, configure the access policy for the key vault so that the cluster has permissions to access it. 在此步骤中,你将使用前面分配给群集的系统分配的托管标识。In this step, you'll use the system-assigned managed identity that you previously assigned to the cluster. 若要设置 Key Vault 的访问策略,请调用 Set-AzKeyVaultAccessPolicyTo set the access policy for the key vault, call Set-AzKeyVaultAccessPolicy. 请将括号中的占位符值替换为你自己的值,并使用前面示例中定义的变量。Replace the placeholder values in brackets with your own values and use the variables defined in the previous examples.

Set-AzKeyVaultAccessPolicy `
    -VaultName $keyVault.VaultName `
    -ObjectId $cluster.Identity.PrincipalId `
    -PermissionsToKeys wrapkey,unwrapkey,get,recover

新建密钥Create a new key

接下来,在 Key Vault 中创建新密钥。Next, create a new key in the key vault. 若要创建新密钥,请调用 Add-AzKeyVaultKeyTo create a new key, call Add-AzKeyVaultKey. 请将括号中的占位符值替换为你自己的值,并使用前面示例中定义的变量。Replace the placeholder values in brackets with your own values and use the variables defined in the previous examples.

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

配置使用客户管理的密钥进行加密Configure encryption with customer-managed keys

本部分说明如何使用 Azure 数据资源管理器 C# 客户端配置客户托管密钥加密。This section shows you how to configure customer-managed keys encryption using the Azure Data Explorer C# client.

必备条件Prerequisites

安装 C# NuGetInstall C# NuGet

身份验证Authentication

若要运行本文中的示例,请创建可以访问资源的 Azure AD 应用程序和服务主体To run the examples in this article, create an Azure AD application and service principal that can access resources. 可以在订阅范围添加角色分配,并获取所需的 Directory (tenant) IDApplication IDClient SecretYou can add role assignment at the subscription scope and get the required Directory (tenant) ID, Application ID, and Client Secret.

配置群集Configure cluster

默认情况下,Azure 数据资源管理器加密使用 Microsoft 托管密钥。By default, Azure Data Explorer encryption uses Microsoft-managed keys. 将 Azure 数据资源管理器群集配置为使用客户托管密钥,并指定要与群集关联的密钥。Configure your Azure Data Explorer cluster to use customer-managed keys and specify the key to associate with the cluster.

  1. 使用以下代码更新群集:Update your cluster by using the following code:

    var tenantId = "xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxx";//Directory (tenant) ID
    var clientId = "xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxx";//Application ID
    var clientSecret = "xxxxxxxxxxxxxx";//Client Secret
    var subscriptionId = "xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxx";
    var authenticationContext = new AuthenticationContext($"https://login.partner.microsoftonline.cn/{tenantId}");
    var credential = new ClientCredential(clientId, clientSecret);
    var result = await authenticationContext.AcquireTokenAsync(resource: "https://management.core.chinacloudapi.cn/", clientCredential: credential);
    
    var credentials = new TokenCredentials(result.AccessToken, result.AccessTokenType);
    
    var kustoManagementClient = new KustoManagementClient(credentials)
    {
        SubscriptionId = subscriptionId
    };
    
    var resourceGroupName = "testrg";
    var clusterName = "mykustocluster";
    var keyName = "myKey";
    var keyVersion = "5b52b20e8d8a42e6bd7527211ae32654";
    var keyVaultUri = "https://mykeyvault.vault.azure.cn/";
    var keyVaultProperties = new KeyVaultProperties (keyName, keyVersion, keyVaultUri);
    var clusterUpdate = new ClusterUpdate(keyVaultProperties: keyVaultProperties);
    await kustoManagementClient.Clusters.UpdateAsync(resourceGroupName, clusterName, clusterUpdate);
    
  2. 运行以下命令,检查群集是否已成功更新:Run the following command to check if your cluster was successfully updated:

    kustoManagementClient.Clusters.Get(resourceGroupName, clusterName);
    

    如果结果包含带 Succeeded 值的 ProvisioningState,则表示已成功更新群集。If the result contains ProvisioningState with the Succeeded value, then your cluster was successfully updated.

更新密钥版本Update the key version

创建密钥的新版本时,需将群集更新为使用新版本。When you create a new version of a key, you'll need to update the cluster to use the new version. 首先调用 Get-AzKeyVaultKey 以获取最新密钥版本。First, call Get-AzKeyVaultKey to get the latest version of the key. 然后,将群集的密钥保管库属性更新为使用新的密钥版本,如配置群集中所示。Then update the cluster's key vault properties to use the new version of the key, as shown in Configure cluster.

后续步骤Next steps