Encrypt Astra DB Serverless databases with Microsoft Azure Key Vault encryption keys

Customer key encryption for Microsoft Azure regions is available only to qualified participants in the private preview release. Development is ongoing, and the features and functionality are subject to change. This private preview is governed by your Agreement and the DataStax Preview Terms.

You must configure customer keys before you deploy the databases that will use those keys. You cannot use a new customer key for an existing database.

You can encrypt your Astra DB Serverless databases with Azure Key Vault encryption keys.

To do this, you must start the registration process in Astra, create a key in Azure Key Vault, and then register the key in your Astra organization. This process requires access to both Astra and your cloud provider.

To configure customer key encryption for other cloud providers or Astra Managed Clusters databases, see Prepare to use customer-managed encryption keys with Astra DB Serverless.

Prerequisites

Learn how Astra uses customer keys and determine how many keys you need.
Access to Azure Key Vault as an administrator or other user with permissions to create and manage encryption keys.
The Organization Administrator or a custom role with the the Read CMK Key and Write CMK Key permissions.

To use the DevOps API, you need an application token with a valid role.

Create and register an Azure Key Vault encryption key in the Astra Portal

In the Astra Portal header, click Settings.
In the Settings navigation menu, make sure the enterprise/organization filter is set to the organization that you want to manage.

If the organization belongs to an enterprise, you must filter on the enterprise, and then click the organization name in the Organizations list.
In the Settings navigation menu, click Security.
In the Key Encryption section, click Add Keys.
For Database Type, select Serverless.
For Provider, select Microsoft Azure.
For Region, select the region where you plan to create your customer key and deploy your database.

You can select from any supported region that is unlocked for your Astra organization. For assistance with unavailable regions, contact IBM Support.
After your select a region, make a note of the Cloud Provider ID. This is a unique identifier for a DataStax-owned Azure application. You will use this ID to define allowed principals in your key’s IAM policy.

Some Azure regions have two provider IDs. If you select a region with two provider IDs, you must include both IDs in your key’s IAM policy.
Open a new browser tab, navigate to Azure Key Vault, and then create a key vault in the same location (region) that you selected in the Astra Portal.
In the key vault networking settings, select Allow trusted Microsoft services to bypass this firewall.
Create a software-protected key in your key vault.
Enable Azure RBAC on your key vault.
Create a service principal using the Cloud Provider ID from the Astra Portal. If your Azure region has two provider IDs, create service principals for both IDs.
```
az ad sp create --id CLOUD_PROVIDER_ID
```
Assign the Key Vault Crypto Service Encryption User role to your key vault. For more information, see Key Vault scope role assignment.
```
az role assignment create \
  --assignee-object-id SERVICE_PRINCIPAL_ID \
  --role "Key Vault Crypto Service Encryption User" \
  --scope /subscriptions/SUBSCRIPTION_ID/resourceGroups/RESOURCE_GROUP_NAME/providers/Microsoft.KeyVault/vaults/VAULT_NAME
```
Replace the following:
- SERVICE_PRINCIPAL_ID: The ID of the service principal that you created in the previous step. If your Azure region has two provider IDs, you must configure a role assignment for both service principals.
- SUBSCRIPTION_ID: Your Azure subscription ID.
- RESOURCE_GROUP_NAME: The name of the resource group where you created the key vault.
- VAULT_NAME: The name of your key vault.
In Azure Key Vault, navigate to your key, and then copy the Key Identifier without the version hash, such as https://VAULT_NAME.vault.azure.net/keys/KEY_NAME.

You must not include the version hash at the end of the key identifier. If you include the version hash, then Astra DB can only use that specific key version.
```
# Full key identifier (DO NOT USE)
https://testvault.vault.azure.net/keys/astra-eastus-key/a00a0000-000a-000a-a000-a000a000a000

# Key identifier without version hash
https://testvault.vault.azure.net/keys/astra-eastus-key
```
In the Astra Portal, paste the key identifier without the version hash in the Key ID field, and then click Add Key.
Deploy databases in the same provider-specific region as the registered key.

Astra uses the registered key to encrypt all Astra DB Serverless databases that you deploy to the same provider-specific region.

Creating new databases and adding regions to multi-region databases are both considered database deployments. For multi-region databases, you must register a key in each desired region before you deploy the database to those regions. For more information, see Prepare to use customer-managed encryption keys with Astra DB Serverless.
Optional: Enable customer key encryption for other regions, providers, or database types.

To enable customer key encryption for Astra DB Serverless databases in other Azure regions, repeat this entire process for each applicable region.

To configure customer key encryption for other cloud providers or Astra Managed Clusters databases, see Prepare to use customer-managed encryption keys with Astra DB Serverless.

Create and register an Azure Key Vault encryption key with the DevOps API

Use the DevOps API to get the DataStax-owned Azure application ID for your key’s IAM policy:
```
curl -sS -L -X GET "https://api.astra.datastax.com/v2/kms/provider/azure/region/REGION/accounts" \
--header "Authorization: Bearer APPLICATION_TOKEN" \
--header "Content-Type: application/json"
```
Replace the following:
- REGION: A supported Azure region where you plan to create your customer key and your database, such as eastus
- APPLICATION_TOKEN: An application token with the Read CMK Key and Write CMK Key permissions.
Copy the provider_id from the response, which is a unique identifier for a DataStax-owned Azure application. You will use this ID to define allowed principals in your key’s IAM policy. Some Azure regions have two provider IDs. If you select a region with two provider IDs, you must include both IDs in your key’s IAM policy.
```
[
  {
    "organization_id": "ORGANIZATION_ID",
    "provider_id": "PROVIDER_ID",
    "provider": "azure"
  }
]
```
In a browser, navigate to Azure Key Vault, and then create a key vault in the same location (region) that you used in the previous DevOps API request.
In the key vault networking settings, select Allow trusted Microsoft services to bypass this firewall.
Create a software-protected key in your key vault.
Enable Azure RBAC on your key vault.
Create a service principal using the provider_id that was returned by the DevOps API. If your Azure region has two provider IDs, create service principals for both IDs.
```
az ad sp create --id PROVIDER_ID
```
Assign the Key Vault Crypto Service Encryption User role to your key vault. For more information, see Key Vault scope role assignment.
```
az role assignment create \
  --assignee-object-id SERVICE_PRINCIPAL_ID \
  --role "Key Vault Crypto Service Encryption User" \
  --scope /subscriptions/SUBSCRIPTION_ID/resourceGroups/RESOURCE_GROUP_NAME/providers/Microsoft.KeyVault/vaults/VAULT_NAME
```
Replace the following:
- SERVICE_PRINCIPAL_ID: The ID of the service principal that you created in the previous step. If your Azure region has two provider IDs, you must configure a role assignment for both service principals.
- SUBSCRIPTION_ID: Your Azure subscription ID.
- RESOURCE_GROUP_NAME: The name of the resource group where you created the key vault.
- VAULT_NAME: The name of your key vault.
In Azure Key Vault, navigate to your key, and then copy the Key Identifier without the version hash, such as https://VAULT_NAME.vault.azure.net/keys/KEY_NAME.

Make sure that you don’t include the version hash at the end of the key identifier. If you include the version hash, then Astra DB can only use that specific key version.
```
# Full key identifier
https://testvault.vault.azure.net/keys/astra-eastus-key/a00a0000-000a-000a-a000-a000a000a000

# Key identifier without version hash
https://testvault.vault.azure.net/keys/astra-eastus-key
```
Use the DevOps API to register your customer key in your Astra organization:
```
curl -sS -L -X POST "https://api.astra.datastax.com/v2/kms" \
--header "Authorization: Bearer APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "orgId": "ORGANIZATION_ID",
  "azure": {
    "keyIdentifier": "KEY_IDENTIFIER_WITHOUT_VERSION",
    "region": "REGION"
  }
}'
```
Replace the following:
- APPLICATION_TOKEN: Your Astra application token.
- ORGANIZATION_ID: Your Astra organization ID.
- RESOURCE_NAME: Your key’s identifier without the version hash, such as https://VAULT_NAME.vault.azure.net/keys/KEY_NAME.
- REGION: The location where you created your key, such as eastus.
Deploy databases in the same provider-specific region as the registered key.

Astra uses the registered key to encrypt all Astra DB Serverless databases that you deploy to the same provider-specific region.

Creating new databases and adding regions to multi-region databases are both considered database deployments. For multi-region databases, you must register a key in each desired region before you deploy the database to those regions. For more information, see Prepare to use customer-managed encryption keys with Astra DB Serverless.
Optional: Enable customer key encryption for other regions, providers, or database types.

To enable customer key encryption for Astra DB Serverless databases in other Azure regions, repeat this entire process for each applicable region.

To configure customer key encryption for other cloud providers or Astra Managed Clusters databases, see Prepare to use customer-managed encryption keys with Astra DB Serverless.

Encrypt Astra DB Serverless databases with Microsoft Azure Key Vault encryption keys

Prerequisites

Create and register an Azure Key Vault encryption key in the Astra Portal

Create and register an Azure Key Vault encryption key with the DevOps API

See also

Was this helpful?

Give Feedback