Skip to content

Commit 432437e

Browse files
Add TDE with a customer-managed Key Vault key to the SQL Database sample (#126)
* Add support for Transparent Data Encryption (TDE) with customer-managed keys * Refactor Program.cs and update sample.csproj formatting * Update README files to reflect changes in database table names and clarify Azure Key Vault usage
1 parent 5ae6984 commit 432437e

19 files changed

Lines changed: 815 additions & 36 deletions

File tree

‎run-samples.sh‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -70,8 +70,8 @@ TERRAFORM_SAMPLES=(
7070
"samples/web-app-cosmosdb-mongodb-api/dotnet/terraform|bash deploy.sh"
7171
"samples/web-app-managed-identity/python/terraform|bash deploy.sh"
7272
"samples/web-app-managed-identity/dotnet/terraform|bash deploy.sh"
73-
"samples/web-app-sql-database/python/terraform|bash deploy.sh"
74-
"samples/web-app-sql-database/dotnet/terraform|bash deploy.sh"
73+
"samples/web-app-sql-database/python/terraform|bash deploy.sh|bash ../scripts/validate.sh"
74+
"samples/web-app-sql-database/dotnet/terraform|bash deploy.sh|bash ../scripts/validate.sh"
7575
"samples/web-app-mysql-flexible-server/python/terraform|bash deploy.sh"
7676
"samples/web-app-mysql-flexible-server/dotnet/terraform|bash deploy.sh"
7777
"samples/web-app-postgresql-flexible-server/python/terraform|bash deploy.sh"

‎samples/web-app-sql-database/dotnet/README.md‎

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Azure Web App with Azure SQL Database and Azure Key Vault
22

3-
This sample demonstrates a ASP.NET Core Razor Pages single-page web application called *Vacation Planner* hosted on an [Azure Web App](https://learn.microsoft.com/en-us/azure/app-service/overview). The app runs on an Azure App Service Plan and stores activity data in an `activities` table within the `sampledb` database on an [Azure SQL Database](https://learn.microsoft.com/en-us/azure/azure-sql/database/) instance. The connection string of the SQL database is stored as a secret in [Azure Key Vault](https://learn.microsoft.com/en-us/azure/key-vault/general/overview). The application also retrieves its certificate from Key Vault to serve traffic over HTTPS.
3+
This sample demonstrates a ASP.NET Core Razor Pages single-page web application called *Vacation Planner* hosted on an [Azure Web App](https://learn.microsoft.com/en-us/azure/app-service/overview). The app runs on an Azure App Service Plan and stores activity data in an `Activities` table within the `PlannerDB` database on an [Azure SQL Database](https://learn.microsoft.com/en-us/azure/azure-sql/database/) instance. The connection string of the SQL database is stored as a secret in [Azure Key Vault](https://learn.microsoft.com/en-us/azure/key-vault/general/overview). The application also retrieves its certificate from Key Vault to serve traffic over HTTPS. The SQL server encrypts its databases at rest with [Transparent Data Encryption (TDE)](https://learn.microsoft.com/en-us/azure/azure-sql/database/transparent-data-encryption-byok-overview) protected by a customer-managed key: an RSA key in Key Vault that the server reaches through a user-assigned managed identity.
44

55

66
## Architecture
@@ -11,8 +11,9 @@ The following diagram illustrates the architecture of the solution:
1111

1212
- **Azure Web App**: Hosts the ASP.NET Core application
1313
- **Azure App Service Plan**: Provides compute resources for the web app
14-
- **Azure SQL Database**: Stores activity data in a relational table
15-
- **Azure Key Vault**: Stores the database connection string and the certificate used to secure HTTPS traffic
14+
- **Azure SQL Database**: Stores activity data in a relational table, encrypted at rest with TDE
15+
- **Azure Key Vault**: Stores the database connection string, the certificate used to secure HTTPS traffic, and the RSA key that serves as the TDE protector of the SQL server
16+
- **User-Assigned Managed Identity**: The identity the SQL server uses to wrap and unwrap its database encryption keys with the Key Vault key
1617

1718
## Prerequisites
1819

@@ -44,12 +45,16 @@ The Vacation Planner Web App supports two common approaches for accessing Azure
4445
This flexibility allows the app to run securely in Azure or in emulated environments like [LocalStack for Azure](https://docs.localstack.cloud/azure/). The client code supports both authentication modes using [`ClientSecretCredential`](https://learn.microsoft.com/en-us/dotnet/api/azure.identity.clientsecretcredential) or [`DefaultAzureCredential`](https://learn.microsoft.com/en-us/dotnet/api/azure.identity.defaultazurecredential) from the Azure SDK.
4546

4647
## Azure Key Vault Integration
47-
The application integrates with Azure Key Vault for managing secrets and certificates:
48+
The application integrates with Azure Key Vault for managing secrets and certificates, and the SQL server uses a Key Vault key to protect its data at rest:
4849

4950
Secrets: The SQL connection string is stored as a secret in Key Vault. At runtime, the app retrieves it using the Azure Key Vault Secrets SDK. This is configured via the KEY_VAULT_NAME and SECRET_NAME environment variables.
5051

5152
Certificates: A self-signed certificate is created in Key Vault during deployment. The app exposes a GET /api/certificate endpoint that retrieves the certificate using the Azure Key Vault Certificates SDK and returns its name, confirming the integration works. This is configured via the KEYVAULT_URI and CERT_NAME environment variables.
5253

54+
Keys: An RSA key in Key Vault is the TDE protector of the SQL server, the customer-managed key that encrypts the database encryption key of every database on the server. The server reaches the key through its user-assigned managed identity, which holds the `get`, `wrapKey` and `unwrapKey` key permissions, and picks up new versions of the key automatically (auto-rotation). Azure requires soft delete and purge protection on the vault. With purge protection, a deleted vault cannot be purged: after the resource group is deleted, the vault stays soft-deleted for the 7-day retention period, and its name cannot be reused anywhere until then. Vault names are global, so a soft-deleted vault from any earlier deployment of this sample, yours or someone else's, blocks the name for everyone. To deploy to Azure under a new name, change `PREFIX` or `SUFFIX` in the deployment script you use and in `scripts/validate.sh`; `scripts/call-web-app.sh` finds the web app by itself.
55+
56+
On LocalStack, the emulator registers the key on the server and checks that the key exists and that the server identity holds `get`, `wrapKey` and `unwrapKey` on it, but it does not encrypt the database with it, and unlike Azure it does not require purge protection on the vault. The Azure CLI variant registers the key and the protector with `az resource create`, because `az sql server key create` and `az sql server tde-key set` only accept key ids on the public Key Vault domains and reject the ones the emulator issues.
57+
5358
## Deployment
5459

5560
Set up the Azure emulator using the LocalStack for Azure Docker image. Before starting, ensure you have a valid `LOCALSTACK_AUTH_TOKEN` to access the Azure emulator. Refer to the [Auth Token guide](https://docs.localstack.cloud/getting-started/auth-token/) to obtain your Auth Token and set it in the `LOCALSTACK_AUTH_TOKEN` environment variable. The Azure Docker image is available on the [LocalStack Docker Hub](https://hub.docker.com/r/localstack/localstack-azure). To pull the image, execute:

‎samples/web-app-sql-database/dotnet/bicep/README.md‎

Lines changed: 41 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,8 @@ The [deploy.sh](deploy.sh) script creates the [Azure Resource Group](https://lea
4040
3. [Azure App Service Plan](https://learn.microsoft.com/en-us/azure/app-service/overview-hosting-plans): The compute resource that hosts the web application.
4141
4. [Azure Web App](https://learn.microsoft.com/en-us/azure/app-service/overview): Hosts the ASP.NET Core Razor Pages single-page application (*Vacation Planner*), connected to Azure SQL Database.
4242
5. [App Service Source Control](https://learn.microsoft.com/en-us/rest/api/appservice/web-apps/create-or-update-source-control?view=rest-appservice-2024-11-01): (Optional) Configures automatic deployment from a public GitHub repository.
43-
6. [Azure Key Vault](https://learn.microsoft.com/en-us/azure/key-vault/general/overview): Stores the SQL connection string in a secret.
43+
6. [Azure Key Vault](https://learn.microsoft.com/en-us/azure/key-vault/general/overview): Stores the SQL connection string in a secret and the RSA key that serves as the [TDE protector](https://learn.microsoft.com/en-us/azure/azure-sql/database/transparent-data-encryption-byok-overview) of the SQL server, registered by the [transparent-data-encryption.bicep](modules/transparent-data-encryption.bicep) module.
44+
7. [User-Assigned Managed Identity](https://learn.microsoft.com/en-us/entra/identity/managed-identities-azure-resources/overview): The identity the SQL server uses to reach its TDE protector key in Key Vault.
4445

4546
The web app allows users to plan and manage vacation activities, storing all activity data in the `Activities` table in the `PlannerDB` database. For more information, see [Azure Web App with Azure SQL Database and Azure Key Vault](../README.md).
4647

@@ -100,6 +101,7 @@ SQL_DATABASE_NAME='PlannerDB'
100101
WEB_APP_NAME="${PREFIX}-webapp-${SUFFIX}"
101102
KEY_VAULT_NAME="${PREFIX}-kv-${SUFFIX}"
102103
SECRET_NAME="${PREFIX}-secret-${SUFFIX}"
104+
TDE_KEY_NAME="${PREFIX}-tde-key-${SUFFIX}"
103105

104106
# Check resource group
105107
echo -e "[$RESOURCE_GROUP_NAME] resource group:\n"
@@ -130,6 +132,44 @@ az sql db show \
130132
--resource-group "$RESOURCE_GROUP_NAME" \
131133
--output table
132134

135+
# Check that the Key Vault key is the TDE protector of the Azure SQL Server
136+
echo -e "\n[$SQL_SERVER_NAME] SQL server TDE protector:\n"
137+
# Read the key through Azure Resource Manager: the Bicep variant grants the caller no Key Vault data-plane access.
138+
KEY_VAULT_ID=$(az keyvault show \
139+
--name "$KEY_VAULT_NAME" \
140+
--resource-group "$RESOURCE_GROUP_NAME" \
141+
--query "id" \
142+
--output tsv)
143+
TDE_KEY_ID=$(az resource show \
144+
--ids "$KEY_VAULT_ID/keys/$TDE_KEY_NAME" \
145+
--api-version 2024-11-01 \
146+
--query "properties.keyUriWithVersion" \
147+
--output tsv)
148+
TDE_PROTECTOR=$(az sql server tde-key show \
149+
--server "$SQL_SERVER_NAME" \
150+
--resource-group "$RESOURCE_GROUP_NAME" \
151+
--output json)
152+
echo "$TDE_PROTECTOR" | jq '{serverKeyType, uri, autoRotationEnabled}'
153+
if [[ "$(jq -r .serverKeyType <<< "$TDE_PROTECTOR")" != "AzureKeyVault" ||
154+
"$(jq -r .uri <<< "$TDE_PROTECTOR")" != "$TDE_KEY_ID" ||
155+
"$(jq -r .autoRotationEnabled <<< "$TDE_PROTECTOR")" != "true" ]]; then
156+
echo "The TDE protector of [$SQL_SERVER_NAME] is not the auto-rotated Key Vault key [$TDE_KEY_ID]"
157+
exit 1
158+
fi
159+
160+
# Check that TDE is enabled on the Azure SQL Database
161+
TDE_STATE=$(az sql db tde show \
162+
--database "$SQL_DATABASE_NAME" \
163+
--server "$SQL_SERVER_NAME" \
164+
--resource-group "$RESOURCE_GROUP_NAME" \
165+
--query "state" \
166+
--output tsv)
167+
echo -e "\n[$SQL_DATABASE_NAME] SQL database TDE state: [$TDE_STATE]"
168+
if [[ "$TDE_STATE" != "Enabled" ]]; then
169+
echo "TDE is not enabled on [$SQL_DATABASE_NAME]"
170+
exit 1
171+
fi
172+
133173
# Check Azure Key Vault
134174
echo -e "\n[$KEY_VAULT_NAME] Key Vault:\n"
135175
az keyvault show \

‎samples/web-app-sql-database/dotnet/bicep/main.bicep‎

Lines changed: 50 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -154,9 +154,6 @@ param administratorLoginPassword string = 'P@ssw0rd1234!'
154154
@description('Conditional. The Azure Active Directory (AAD) administrator authentication. Required if no `administratorLogin` & `administratorLoginPassword` is provided.')
155155
param administrators object?
156156

157-
@description('Specifies the conditional Developmentresource ID of a user-assigned identityDevelopment to be used by default. This is required if `userAssignedIdentities` is not empty.')
158-
param primaryUserAssignedIdentityResourceId string?
159-
160157
@allowed([
161158
'1.0'
162159
'1.1'
@@ -325,15 +322,25 @@ var webAppName = '${prefix}-webapp-${suffix}'
325322
var appServicePlanName = '${prefix}-app-service-plan-${suffix}'
326323
var keyVaultName = '${prefix}-kv-${suffix}'
327324
var sqlConnectionStringSecretName = '${prefix}-secret-${suffix}'
328-
var identity = {
329-
type: 'SystemAssigned'
330-
}
325+
var sqlServerIdentityName = '${prefix}-tde-identity-${suffix}'
326+
var tdeKeyName = '${prefix}-tde-key-${suffix}'
327+
328+
resource sqlServerIdentity 'Microsoft.ManagedIdentity/userAssignedIdentities@2023-01-31' = {
329+
name: sqlServerIdentityName
330+
location: location
331+
tags: tags
332+
}
331333

332334
resource sqlServer 'Microsoft.Sql/servers@2024-05-01-preview' = {
333335
name: sqlServerName
334336
location: location
335337
tags: tags
336-
identity: identity
338+
identity: {
339+
type: 'UserAssigned'
340+
userAssignedIdentities: {
341+
'${sqlServerIdentity.id}': {}
342+
}
343+
}
337344
properties: {
338345
administratorLogin: administratorLogin
339346
administratorLoginPassword: administratorLoginPassword
@@ -342,7 +349,7 @@ resource sqlServer 'Microsoft.Sql/servers@2024-05-01-preview' = {
342349
isIPv6Enabled: isIPv6Enabled
343350
version: version
344351
minimalTlsVersion: minimalTlsVersion
345-
primaryUserAssignedIdentityId: primaryUserAssignedIdentityResourceId
352+
primaryUserAssignedIdentityId: sqlServerIdentity.id
346353
publicNetworkAccess: publicNetworkAccess
347354
restrictOutboundNetworkAccess: restrictOutboundNetworkAccess
348355
}
@@ -453,10 +460,45 @@ resource keyVault 'Microsoft.KeyVault/vaults@2023-07-01' = {
453460
]
454461
}
455462
}
463+
{
464+
tenantId: subscription().tenantId
465+
objectId: sqlServerIdentity.properties.principalId
466+
permissions: {
467+
keys: [
468+
'get'
469+
'wrapKey'
470+
'unwrapKey'
471+
]
472+
}
473+
}
456474
]
457475
enableRbacAuthorization: false
458476
enableSoftDelete: true
459477
softDeleteRetentionInDays: 7
478+
enablePurgeProtection: true
479+
}
480+
}
481+
482+
resource tdeKey 'Microsoft.KeyVault/vaults/keys@2024-11-01' = {
483+
parent: keyVault
484+
name: tdeKeyName
485+
properties: {
486+
kty: 'RSA'
487+
keySize: 2048
488+
keyOps: [
489+
'wrapKey'
490+
'unwrapKey'
491+
]
492+
}
493+
}
494+
495+
module transparentDataEncryption 'modules/transparent-data-encryption.bicep' = {
496+
name: 'transparentDataEncryption'
497+
params: {
498+
sqlServerName: sqlServer.name
499+
keyVaultName: keyVault.name
500+
keyName: tdeKey.name
501+
keyUri: tdeKey.properties.keyUriWithVersion
460502
}
461503
}
462504

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
@description('Specifies the name of the SQL logical server.')
2+
param sqlServerName string
3+
4+
@description('Specifies the name of the Key Vault that holds the TDE protector key.')
5+
param keyVaultName string
6+
7+
@description('Specifies the name of the Key Vault key used as the TDE protector.')
8+
param keyName string
9+
10+
@description('Specifies the versioned URI of the Key Vault key used as the TDE protector.')
11+
param keyUri string
12+
13+
resource sqlServer 'Microsoft.Sql/servers@2024-05-01-preview' existing = {
14+
name: sqlServerName
15+
}
16+
17+
// A server key must be named after the vault, key and key version it points to.
18+
resource serverKey 'Microsoft.Sql/servers/keys@2023-08-01' = {
19+
parent: sqlServer
20+
name: '${keyVaultName}_${keyName}_${last(split(keyUri, '/'))}'
21+
properties: {
22+
serverKeyType: 'AzureKeyVault'
23+
uri: keyUri
24+
}
25+
}
26+
27+
resource encryptionProtector 'Microsoft.Sql/servers/encryptionProtector@2023-08-01' = {
28+
parent: sqlServer
29+
name: 'current'
30+
properties: {
31+
serverKeyType: 'AzureKeyVault'
32+
serverKeyName: serverKey.name
33+
autoRotationEnabled: true
34+
}
35+
}

‎samples/web-app-sql-database/dotnet/scripts/README.md‎

Lines changed: 41 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,8 @@ The [deploy.sh](deploy.sh) Bash script creates the following Azure resources usi
4040
4. [Azure App Service Plan](https://learn.microsoft.com/en-us/azure/app-service/overview-hosting-plans): The compute resource that hosts the web application.
4141
5. [Azure Web App](https://learn.microsoft.com/en-us/azure/app-service/overview): Hosts the ASP.NET Core Razor Pages single-page application (*Vacation Planner*), connected to Azure SQL Database.
4242
6. [App Service Source Control](https://learn.microsoft.com/en-us/rest/api/appservice/web-apps/create-or-update-source-control?view=rest-appservice-2024-11-01): (Optional) Configures automatic deployment from a public GitHub repository.
43-
7. [Azure Key Vault](https://learn.microsoft.com/en-us/azure/key-vault/general/overview): Stores the SQL connection string in a secret.
43+
7. [Azure Key Vault](https://learn.microsoft.com/en-us/azure/key-vault/general/overview): Stores the SQL connection string in a secret, a self-signed certificate for HTTPS, and the RSA key that serves as the [TDE protector](https://learn.microsoft.com/en-us/azure/azure-sql/database/transparent-data-encryption-byok-overview) of the SQL server.
44+
8. [User-Assigned Managed Identity](https://learn.microsoft.com/en-us/entra/identity/managed-identities-azure-resources/overview): The identity the SQL server uses to reach its TDE protector key in Key Vault.
4445

4546
The system implements a Vacation Planner web application that stores and retrieves activity data from Azure SQL Database. For more information, see [Azure Web App with Azure SQL Database and Azure Key Vault](../README.md).
4647

@@ -100,6 +101,7 @@ SQL_DATABASE_NAME='PlannerDB'
100101
WEB_APP_NAME="${PREFIX}-webapp-${SUFFIX}"
101102
KEY_VAULT_NAME="${PREFIX}-kv-${SUFFIX}"
102103
SECRET_NAME="${PREFIX}-secret-${SUFFIX}"
104+
TDE_KEY_NAME="${PREFIX}-tde-key-${SUFFIX}"
103105

104106
# Check resource group
105107
echo -e "[$RESOURCE_GROUP_NAME] resource group:\n"
@@ -130,6 +132,44 @@ az sql db show \
130132
--resource-group "$RESOURCE_GROUP_NAME" \
131133
--output table
132134

135+
# Check that the Key Vault key is the TDE protector of the Azure SQL Server
136+
echo -e "\n[$SQL_SERVER_NAME] SQL server TDE protector:\n"
137+
# Read the key through Azure Resource Manager: the Bicep variant grants the caller no Key Vault data-plane access.
138+
KEY_VAULT_ID=$(az keyvault show \
139+
--name "$KEY_VAULT_NAME" \
140+
--resource-group "$RESOURCE_GROUP_NAME" \
141+
--query "id" \
142+
--output tsv)
143+
TDE_KEY_ID=$(az resource show \
144+
--ids "$KEY_VAULT_ID/keys/$TDE_KEY_NAME" \
145+
--api-version 2024-11-01 \
146+
--query "properties.keyUriWithVersion" \
147+
--output tsv)
148+
TDE_PROTECTOR=$(az sql server tde-key show \
149+
--server "$SQL_SERVER_NAME" \
150+
--resource-group "$RESOURCE_GROUP_NAME" \
151+
--output json)
152+
echo "$TDE_PROTECTOR" | jq '{serverKeyType, uri, autoRotationEnabled}'
153+
if [[ "$(jq -r .serverKeyType <<< "$TDE_PROTECTOR")" != "AzureKeyVault" ||
154+
"$(jq -r .uri <<< "$TDE_PROTECTOR")" != "$TDE_KEY_ID" ||
155+
"$(jq -r .autoRotationEnabled <<< "$TDE_PROTECTOR")" != "true" ]]; then
156+
echo "The TDE protector of [$SQL_SERVER_NAME] is not the auto-rotated Key Vault key [$TDE_KEY_ID]"
157+
exit 1
158+
fi
159+
160+
# Check that TDE is enabled on the Azure SQL Database
161+
TDE_STATE=$(az sql db tde show \
162+
--database "$SQL_DATABASE_NAME" \
163+
--server "$SQL_SERVER_NAME" \
164+
--resource-group "$RESOURCE_GROUP_NAME" \
165+
--query "state" \
166+
--output tsv)
167+
echo -e "\n[$SQL_DATABASE_NAME] SQL database TDE state: [$TDE_STATE]"
168+
if [[ "$TDE_STATE" != "Enabled" ]]; then
169+
echo "TDE is not enabled on [$SQL_DATABASE_NAME]"
170+
exit 1
171+
fi
172+
133173
# Check Azure Key Vault
134174
echo -e "\n[$KEY_VAULT_NAME] Key Vault:\n"
135175
az keyvault show \

0 commit comments

Comments
 (0)