Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
Applies to: 
Azure SQL Database
Azure SQL Managed Instance
This article shows how to use a key from Azure Key Vault for transparent data encryption (TDE) on Azure SQL Database. To learn more about the TDE with Azure Key Vault integration - Bring Your Own Key (BYOK) Support, visit TDE with customer-managed keys in Azure Key Vault. If you want Azure portal instructions on how to enable TDE with a customer-managed key from Azure Key Vault, see Create server configured with user-assigned managed identity and customer-managed TDE.
Note
Azure SQL Database supports both asymmetric (RSA) and symmetric (AES) keys for customer-managed Transparent Data Encryption, depending on the configuration. Support for symmetric (AES) keys is currently in public preview and is limited to Azure SQL Database. You might see this capability appear over time depending on your region and service deployment status. For details, see Transparent Data Encryption with customer-managed keys (BYOK).
Prerequisites for PowerShell
- You must have an Azure subscription and be an administrator on that subscription.
- [Recommended but Optional] Have a hardware security module (HSM) or local key store for creating a local copy of the TDE Protector key material.
- You must have Azure PowerShell installed and running.
- Create an Azure Key Vault and Key to use for TDE.
- Instructions for using a hardware security module (HSM) and Azure Key Vault
- The key vault must have the following property to be used for TDE:
- soft-delete and purge protection
- Instructions for using a hardware security module (HSM) and Azure Key Vault
- The key must have the following attributes to be used for TDE:
- The activation date (if set) must be a date and time in the past
- The expiration date (if set) must be a future date and time
- The key must be in the Enabled state
- Able to perform get, wrap key, unwrap key operations
- To use an Azure Key Vault Managed HSM key, follow instructions to create and activate a Managed HSM using Azure CLI
For Az PowerShell module installation instructions, see Install Azure PowerShell.
For specifics on Azure Key Vault, see PowerShell instructions from Azure Key Vault and How to use Azure Key Vault soft-delete with PowerShell.
Assign a Microsoft Entra identity to your server
If you have an existing server, use the following instructions to add a Microsoft Entra identity to your server:
$server = Set-AzSqlServer -ResourceGroupName <SQLDatabaseResourceGroupName> -ServerName <LogicalServerName> -AssignIdentity
If you're creating a server, use the New-AzSqlServer cmdlet with the -Identity tag to add a Microsoft Entra identity during server creation:
$server = New-AzSqlServer -ResourceGroupName <SQLDatabaseResourceGroupName> -Location <RegionName> `
-ServerName <LogicalServerName> -ServerVersion "12.0" -SqlAdministratorCredentials <PSCredential> -AssignIdentity
Grant Azure Key Vault permissions to your server
Use the Set-AzKeyVaultAccessPolicy cmdlet to grant your server access to the key vault before using a key from it for TDE.
Set-AzKeyVaultAccessPolicy -VaultName <KeyVaultName> `
-ObjectId $server.Identity.PrincipalId -PermissionsToKeys get, wrapKey, unwrapKey
To add permissions to your server on a Managed HSM, add the Managed HSM Crypto Service Encryption User local RBAC role to the server. This role enables the server to perform get, wrap key, and unwrap key operations on the keys in the Managed HSM. For more information, see Managed HSM role management.
Add the Azure Key Vault key to the server and set the TDE Protector
- Use the Get-AzKeyVaultKey cmdlet to retrieve the key ID from key vault.
- Use the Add-AzSqlServerKeyVaultKey cmdlet to add the key from the Azure Key Vault to the server.
- Use the Set-AzSqlServerTransparentDataEncryptionProtector cmdlet to set the key as the TDE protector for all server resources.
- Use the Get-AzSqlServerTransparentDataEncryptionProtector cmdlet to confirm that the TDE protector was configured as intended.
Note
For Managed HSM keys, use Az.Sql 2.11.1 version of PowerShell or higher.
Note
The combined length for the key vault name and key name can't exceed 94 characters.
Tip
Using versioned and versionless Azure Key Vault keys for TDE
When setting the TDE protector, you can reference an Azure Key Vault key by using either a specific key version or a versionless key identifier.
In both cases, Azure SQL Database always resolves and uses the latest enabled version of the key in Azure Key Vault or Azure Key Vault Managed HSM. Use versionless key identifiers to avoid embedding a specific key version in the TDE protector configuration.
Versionless key identifiers are currently supported only for Azure SQL Database.
Examples:
Key identifier that includes a specific version
https://<key-vault-name>.vault.azure.net/keys/<key-name>/<key-version>Versionless key identifier
https://<key-vault-name>.vault.azure.net/keys/<key-name>
# add the key from Azure Key Vault to the server
Add-AzSqlServerKeyVaultKey -ResourceGroupName <SQLDatabaseResourceGroupName> -ServerName <LogicalServerName> -KeyId <KeyVaultKeyId>
# set the key as the TDE protector for all resources under the server
Set-AzSqlServerTransparentDataEncryptionProtector -ResourceGroupName <SQLDatabaseResourceGroupName> -ServerName <LogicalServerName> `
-Type AzureKeyVault -KeyId <KeyVaultKeyId>
# confirm the TDE protector was configured as intended
Get-AzSqlServerTransparentDataEncryptionProtector -ResourceGroupName <SQLDatabaseResourceGroupName> -ServerName <LogicalServerName>
Turn on TDE
Use the Set-AzSqlDatabaseTransparentDataEncryption cmdlet to turn on TDE.
Set-AzSqlDatabaseTransparentDataEncryption -ResourceGroupName <SQLDatabaseResourceGroupName> `
-ServerName <LogicalServerName> -DatabaseName <DatabaseName> -State "Enabled"
Now the database has TDE enabled with an encryption key in Azure Key Vault.
Check the encryption state and encryption activity
Use the Get-AzSqlDatabaseTransparentDataEncryption to get the encryption state for a database.
# get the encryption state of the database
Get-AzSqlDatabaseTransparentDataEncryption -ResourceGroupName <SQLDatabaseResourceGroupName> `
-ServerName <LogicalServerName> -DatabaseName <DatabaseName> `
Useful PowerShell cmdlets
Use the Set-AzSqlDatabaseTransparentDataEncryption cmdlet to turn off TDE.
Set-AzSqlDatabaseTransparentDataEncryption -ServerName <LogicalServerName> -ResourceGroupName <SQLDatabaseResourceGroupName> ` -DatabaseName <DatabaseName> -State "Disabled"Use the Get-AzSqlServerKeyVaultKey cmdlet to return the list of Azure Key Vault keys added to the server.
# KeyId is an optional parameter, to return a specific key version Get-AzSqlServerKeyVaultKey -ServerName <LogicalServerName> -ResourceGroupName <SQLDatabaseResourceGroupName>Use the Remove-AzSqlServerKeyVaultKey to remove an Azure Key Vault key from the server.
# the key set as the TDE Protector cannot be removed Remove-AzSqlServerKeyVaultKey -KeyId <KeyVaultKeyId> -ServerName <LogicalServerName> -ResourceGroupName <SQLDatabaseResourceGroupName>
Troubleshooting
If the key vault can't be found, ensure you're in the right subscription.
Get-AzSubscription -SubscriptionId <SubscriptionId>
If you can't add the new key to the server, or if you can't update the new key as the TDE Protector, check the following conditions:
- The key shouldn't have an expiration date.
- The key must have the get, wrap key, and unwrap key operations enabled.
TDE BYOK Azure Synapse Analytics
For TDE BYOK documentation about Azure Synapse Analytics, see Azure Synapse Analytics SQL documentation. For documentation on Transparent Data Encryption for dedicated SQL pools inside Synapse workspaces, see Azure Synapse Analytics encryption.