Skip to content

Commit cc2035a

Browse files
BCS2022BCS2022
authored
Merge pull request #224143 from dileepraotv-github/tls_minimum
Adding new doc for self serve min tls enforcement
2 parents 9ce1c2d + 96ab608 commit cc2035a

File tree

2 files changed

+148
-0
lines changed

2 files changed

+148
-0
lines changed

‎articles/cosmos-db/nosql/TOC.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -747,6 +747,8 @@
747747
items:
748748
- name: Use Always Encrypted
749749
href: ../how-to-always-encrypted.md
750+
- name: Self-serve minimum tls version enforcement
751+
href: ../self-serve-minimum-tls-enforcement.md
750752
- name: Configure customer-managed keys with Azure key vault
751753
href: ../how-to-setup-customer-managed-keys.md
752754
- name: Configure customer-managed keys with Azure managed HSM key vault

‎articles/cosmos-db/self-serve-minimum-tls-enforcement.md

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
---
2+
title: Self-serve minimum tls version enforcement in Azure Cosmos DB
3+
titleSuffix: Azure Cosmos DB
4+
description: Learn how to self-serve minimum TLS version enforcement for your Azure Cosmos DB account to improve your security posture.
5+
author: dileepraotv-github
6+
ms.author: turao
7+
ms.service: cosmos-db
8+
ms.topic: conceptual
9+
ms.date: 01/18/2023
10+
---
11+
12+
# Self-serve minimum TLS version enforcement in Azure Cosmos DB
13+
14+
[!INCLUDE[NoSQL, MongoDB, Cassandra, Gremlin, Table](includes/appliesto-nosql-mongodb-cassandra-gremlin-table.md)]
15+
16+
This article discusses how to enforce a minimum version of the TLS protocol for your Cosmos DB account, using a self-service API.
17+
18+
## How minimum TLS version enforcement works in Azure Cosmos DB
19+
20+
Because of the multi-tenant nature of Cosmos DB, the service is required to meet the access and security needs of every user. To achieve this, **Cosmos DB enforces minimum TLS protocols at the application layer**, and not lower layers in the network stack where TLS operates. This enforcement occurs on any authenticated request to a specific database account, according to the settings set on that account by the customer.
21+
22+
The **minimum service-wide accepted version is TLS 1.0**. This can be changed on a per account basis, as discussed in the following section.
23+
24+
## How to set the minimum TLS version for my Cosmos DB database account
25+
26+
Starting with the [2022-11-15 API version of the Azure Cosmos DB Resource Provider API](), a new property is exposed for every Cosmos DB database account, called `minimalTlsVersion`. It accepts one of the following values:
27+
- `Tls` for setting the minimum version to TLS 1.0.
28+
- `Tls11` for setting the minimum version to TLS 1.1.
29+
- `Tls12` for setting the minimum version to TLS 1.2.
30+
31+
The **default value for new and existing accounts is `Tls`**.
32+
33+
> [!IMPORTANT]
34+
> Staring on April 1st, 2023, the **default value for new accounts will be switched to `Tls12`**.
35+
36+
### Set via Azure CLI
37+
38+
To set using Azure CLI, use the command below:
39+
40+
```azurecli-interactive
41+
subId=$(az account show --query id -o tsv)
42+
rg="myresourcegroup"
43+
dbName="mycosmosdbaccount"
44+
minimalTlsVersion="Tls12"
45+
az rest --uri "/subscriptions/$subId/resourceGroups/$rg/providers/Microsoft.DocumentDB/databaseAccounts/$dbName?api-version=2022-11-15" --method PATCH --body "{ 'properties': { 'minimalTlsVersion': '$minimalTlsVersion' } }" --headers "Content-Type=application/json"
46+
```
47+
48+
### Set via Azure PowerShell
49+
50+
To set using Azure PowerShell, use the command below:
51+
52+
```azurepowershell-interactive
53+
$minimalTlsVersion = 'Tls12'
54+
$patchParameters = @{
55+
ResourceGroupName = 'myresourcegroup'
56+
Name = 'mycosmosdbaccount'
57+
ResourceProviderName = 'Microsoft.DocumentDB'
58+
ResourceType = 'databaseaccounts'
59+
ApiVersion = '2022-11-15'
60+
Payload = "{ 'properties': {
61+
'minimalTlsVersion': '$minimalTlsVersion'
62+
} }"
63+
Method = 'PATCH'
64+
}
65+
Invoke-AzRestMethod @patchParameters
66+
```
67+
68+
### Set via ARM template
69+
70+
To set this property using an ARM template, update your existing template or export a new template for your current deployment, then add `"minimalTlsVersion"` to the properties for the `databaseAccounts` resources, with the desired minimum TLS version value. Below is a basic example of an Azure Resource Manager template with this property setting, using a parameter.
71+
72+
```json
73+
{
74+
{
75+
"type": "Microsoft.DocumentDB/databaseAccounts",
76+
"name": "mycosmosdbaccount",
77+
"apiVersion": "2022-11-15",
78+
"location": "[parameters('location')]",
79+
"kind": "GlobalDocumentDB",
80+
"properties": {
81+
"consistencyPolicy": {
82+
"defaultConsistencyLevel": "[parameters('defaultConsistencyLevel')]",
83+
"maxStalenessPrefix": 1,
84+
"maxIntervalInSeconds": 5
85+
},
86+
"locations": [
87+
{
88+
"locationName": "[parameters('location')]",
89+
"failoverPriority": 0
90+
}
91+
],
92+
"locations": "[variable('locations')]",
93+
"databaseAccountOfferType": "Standard",
94+
"minimalTlsVersion": "[parameters('minimalTlsVersion')]",
95+
}
96+
}
97+
}
98+
```
99+
100+
> [!IMPORTANT]
101+
> Make sure you include the other properties for your account and child resources when redeploying with this property. Do not deploy this template as is or it will reset all of your account properties.
102+
103+
### For new accounts
104+
105+
You can create accounts with the `minimalTlsVersion` property set by using the ARM template above, or by changing the PATCH method to a PUT on either Azure CLI or Azure PowerShell. Make sure to include the other properties for your account.
106+
107+
> [!IMPORTANT]
108+
> If the account exists and the `minimalTlsVersion` property is ommited in a PUT request, then the property will reset to its default value, starting with the 2022-11-15 API version.
109+
110+
## How to verify minimum TLS version enforcement
111+
112+
Because Cosmos DB enforces the minimum TLS version at the application layer, conventional TLS scanners that check whether handshakes are accepted by the service for a specific TLS version are unreliable to test enforcement in Cosmos DB. To verify enforcement, refer to the [official open-source cosmos-tls-scanner tool](https://github.com/Azure/cosmos-tls-scanner/).
113+
114+
You can also get the current value of the `minimalTlsVersion` property by using Azure CLI or Azure PowerShell.
115+
116+
### Get current value via Azure CLI
117+
118+
To get the current value of the property using Azure CLI, run the command below:
119+
120+
```azurecli-interactive
121+
subId=$(az account show --query id -o tsv)
122+
rg="myresourcegroup"
123+
dbName="mycosmosdbaccount"
124+
az rest --uri "/subscriptions/$subId/resourceGroups/$rg/providers/Microsoft.DocumentDB/databaseAccounts/$dbName?api-version=2022-11-15" --method GET
125+
```
126+
127+
### Get current value via Azure PowerShell
128+
129+
To get the current value of the property using Azure PowerShell, run the command below:
130+
131+
```azurepowershell-interactive
132+
$getParameters = @{
133+
ResourceGroupName = 'myresourcegroup'
134+
Name = 'mycosmosdbaccount'
135+
ResourceProviderName = 'Microsoft.DocumentDB'
136+
ResourceType = 'databaseaccounts'
137+
ApiVersion = '2022-11-15'
138+
Method = 'GET'
139+
}
140+
Invoke-AzRestMethod @getParameters
141+
```
142+
143+
## Next steps
144+
145+
For more information about security in Azure Cosmos DB, see [Overview of database security in Azure Cosmos DB
146+
](./database-security.md).

0 commit comments

Comments
 (0)