Manage Transparent Data Encryption in a Managed Instance using your own key from Azure Key Vault
This PowerShell script example configures Transparent Data Encryption (TDE) with customer-managed key for Azure SQL Managed Instance, using a key from Azure Key Vault. This is often referred to as a Bring Your Own Key scenario for TDE. To learn more about the TDE with customer-managed key, see TDE Bring Your Own Key to Azure SQL.
- An existing Managed Instance. See Use PowerShell to create an Azure SQL Database managed instance.
This article has been updated to use the new Azure PowerShell Az module. You can still use the AzureRM module, which will continue to receive bug fixes until at least December 2020. To learn more about the new Az module and AzureRM compatibility, see Introducing the new Azure PowerShell Az module. For Az module installation instructions, see Install Azure PowerShell.
Use Azure Cloud Shell
Azure hosts Azure Cloud Shell, an interactive shell environment that you can use through your browser. You can use either Bash or PowerShell with Cloud Shell to work with Azure services. You can use the Cloud Shell preinstalled commands to run the code in this article without having to install anything on your local environment.
To start Azure Cloud Shell:
|Select Try It in the upper-right corner of a code block. Selecting Try It doesn't automatically copy the code to Cloud Shell.|
|Go to https://shell.azure.com, or select the Launch Cloud Shell button to open Cloud Shell in your browser.|
|Select the Cloud Shell button on the menu bar at the upper right in the Azure portal.|
To run the code in this article in Azure Cloud Shell:
Start Cloud Shell.
Select the Copy button on a code block to copy the code.
Paste the code into the Cloud Shell session by selecting Ctrl+Shift+V on Windows and Linux or by selecting Cmd+Shift+V on macOS.
Select Enter to run the code.
Using both PowerShell locally or using Azure Cloud Shell requires AZ PowerShell 2.3.2 or a later version. If you need to upgrade, see Install Azure PowerShell module, or run the below sample script to install the module for the current user:
Install-Module -Name Az -AllowClobber -Scope CurrentUser
If you are running PowerShell locally, you also need to run
Connect-AzAccount to create a connection with Azure.
# You will need an existing Managed Instance as a prerequisite for completing this script. # See https://docs.microsoft.com/en-us/azure/sql-database/scripts/sql-database-create-configure-managed-instance-powershell # Log in to your Azure account: Connect-AzAccount # If there are multiple subscriptions, choose the one where AKV is created: Set-AzContext -SubscriptionId "subscription ID" # Install the preview version of Az.Sql PowerShell package 1.1.1-preview if you are running this PowerShell locally (uncomment below): # Install-Module -Name Az.Sql -RequiredVersion 1.1.1-preview -AllowPrerelease -Force # 1. Create Resource and setup Azure Key Vault (skip if already done) # Create Resource group (name the resource and specify the location) $location = "westus2" # specify the location $resourcegroup = "MyRG" # specify a new RG name New-AzResourceGroup -Name $resourcegroup -Location $location # Create new Azure Key Vault with a globally unique VaultName and soft-delete option turned on: $vaultname = "MyKeyVault" # specify a globally unique VaultName New-AzKeyVault -VaultName $vaultname -ResourceGroupName $resourcegroup -Location $location -EnableSoftDelete # Authorize Managed Instance to use the AKV (wrap/unwrap key and get public part of key, if public part exists): $objectid = (Set-AzSqlInstance -ResourceGroupName $resourcegroup -Name "MyManagedInstance" -AssignIdentity).Identity.PrincipalId Set-AzKeyVaultAccessPolicy -BypassObjectIdValidation -VaultName $vaultname -ObjectId $objectid -PermissionsToKeys get,wrapKey,unwrapKey # Allow access from trusted Azure services: Update-AzKeyVaultNetworkRuleSet -VaultName $vaultname -Bypass AzureServices # Turn the network rules ON by setting the default action to Deny: Update-AzKeyVaultNetworkRuleSet -VaultName $vaultname -DefaultAction Deny # 2. Provide TDE Protector key (skip if already done) # The recommended way is to import an existing key from a .pfx file. Replace "<PFX private key password>" with the actual password below: $keypath = "c:\some_path\mytdekey.pfx" # Supply your .pfx path and name $securepfxpwd = ConvertTo-SecureString -String "<PFX private key password>" -AsPlainText -Force $key = Add-AzKeyVaultKey -VaultName $vaultname -Name "MyTDEKey" -KeyFilePath $keypath -KeyFilePassword $securepfxpwd # ...or get an existing key from the vault: # $key = Get-AzKeyVaultKey -VaultName $vaultname -Name "MyTDEKey" # Alternatively, generate a new key directly in Azure Key Vault (recommended for test purposes only - uncomment below): # $key = Add-AzureKeyVaultKey -VaultName $vaultname -Name MyTDEKey -Destination Software -Size 2048 # 3. Set up BYOK TDE on Managed Instance: # Assign the key to the Managed Instance: # $key = 'https://contoso.vault.azure.net/keys/contosokey/01234567890123456789012345678901' Add-AzSqlInstanceKeyVaultKey -KeyId $key.id -InstanceName "MyManagedInstance" -ResourceGroupName $resourcegroup # Set TDE operation mode to BYOK: Set-AzSqlInstanceTransparentDataEncryptionProtector -Type AzureKeyVault -InstanceName "MyManagedInstance" -ResourceGroup $resourcegroup -KeyId $key.id
For more information on the Azure PowerShell, see Azure PowerShell documentation.
Additional SQL Database PowerShell script samples can be found in the Azure SQL Database PowerShell scripts.