Autoatendimento de imposição de versão mínima do TLS no Azure Cosmos DB

APLICA-SE AO: NoSQL MongoDB Cassandra Gremlin Table

Este artigo discute como impor uma versão mínima do protocolo TLS para a conta do Cosmos DB usando uma API de autoatendimento.

Como a imposição de versão mínima do TLS funciona no Azure Cosmos DB

Devido à natureza de multilocatário do Cosmos DB, o serviço é necessário para atender às necessidades de acesso e segurança de cada usuário. Para fazer isso, o Cosmos DB impõe protocolos TLS mínimos na camada do aplicativo e não em camadas inferiores na pilha de rede onde o TLS opera. Essa imposição ocorre em qualquer solicitação autenticada para uma conta de banco de dados específica, de acordo com as configurações definidas nessa conta pelo cliente.

A versão mínima aceita em todo o serviço é TLS 1.0. Essa seleção pode ser alterada com base em cada conta, conforme discutido na seção a seguir.

Como definir a versão mínima do TLS para minha conta de banco de dados do Cosmos DB

A partir da versão 2022-11-15 da API do Provedor de Recursos do Azure Cosmos DB, uma nova propriedade, chamada minimalTlsVersion, é exposta para cada conta de banco de dados do Cosmos DB. Aceita um dos seguintes valores:

• Tls para definir a versão mínima como TLS 1.0.
• Tls11 para definir a versão mínima como TLS 1.1.
• Tls12 para definir a versão mínima como TLS 1.2.

O valor padrão para novas contas é Tls12.

Importante

A partir de 31 de agosto de 2025, todas as contas de banco de dados do Cosmos DB devem usar o TLS (Transport Layer Security) 1.2 ou superior, pois o suporte para TLS 1.0 e 1.1 será descontinuado.

Definir o protocolo TLS mínimo no Azure Cosmos DB usando o Portal

Esse recurso de autoatendimento está disponível no Portal durante a criação e edição de uma conta. As contas do Azure Cosmos DB impõem o protocolo TLS 1.2. No entanto, o Azure Cosmos DB também dá suporte aos seguintes protocolos TLS, dependendo do tipo de API selecionado.

• MongoDB: TLS 1.2

• Cassandra: TLS 1.2

• Table, SQL e Graph: TLS 1.0, TLS 1.1 e TLS 1.2

Etapas para definir o protocolo TLS mínimo ao criar uma conta

Se você estiver usando um tipo de API que dá suporte apenas ao TLS 1.2, verá o protocolo TLS desabilitado na guia Rede, na parte inferior.

Se você estiver usando um tipo de API que aceita vários protocolos TLS, navegue até a guia Rede e a opção Protocolo TLS mínimo estará disponível. Você pode alterar o protocolo selecionado clicando na lista suspensa e selecionando o protocolo desejado.

Depois de configurar sua conta, você pode examinar na guia Examinar + criar, na parte inferior da seção Rede, que o protocolo TLS selecionado está definido como você especificou.

Etapas para definir o protocolo TLS mínimo durante a edição de uma conta

1. Navegue até sua conta do Azure Cosmos DB no portal do Azure.

2. Selecione Rede no menu à esquerda e escolha a guia Conectividade.

3. Você encontrará a opção Protocolo TLS mínimo. Se você estiver usando um tipo de API que dá suporte apenas ao TLS 1.2, essa opção estará desabilitada. Caso contrário, você poderá selecionar o protocolo TLS desejado apenas clicando nele.

4. Clique em Salvar depois de alterar o protocolo TLS.

5. Depois de salvo, você receberá uma notificação de êxito. Ainda assim, essa alteração pode levar até 15 minutos para entrar em vigor após a conclusão da atualização de configuração.

Definir via CLI do Azure

Para definir usando a CLI do Azure, use o comando:

rg="myresourcegroup"
dbName="mycosmosdbaccount"
minimalTlsVersion="Tls12"
az cosmosdb update -n $dbName -g $rg --minimal-tls-version $minimalTlsVersion

Definir por meio do Azure PowerShell

Para definir usando o Azure PowerShell, use o comando:

$minimalTlsVersion = 'Tls12'
$patchParameters = @{
  ResourceGroupName = 'myresourcegroup'
  Name = 'mycosmosdbaccount'
  ResourceProviderName = 'Microsoft.DocumentDB'
  ResourceType = 'databaseaccounts'
  ApiVersion = '2022-11-15'
  Payload = "{ 'properties': {
      'minimalTlsVersion': '$minimalTlsVersion'
  } }"
  Method = 'PATCH'
}
Invoke-AzRestMethod @patchParameters

Definir por meio do modelo do ARM

Para definir essa propriedade usando um modelo do ARM, atualize o modelo existente ou exporte um novo modelo para a implantação atual e inclua o "minimalTlsVersion" nas propriedades dos recursos de databaseAccounts, com o valor da versão mínimo do TLS desejado. Um exemplo básico de um modelo do Azure Resource Manager com essa configuração de propriedade, usando um parâmetro, é fornecido aqui.

{
    {
      "type": "Microsoft.DocumentDB/databaseAccounts",
      "name": "mycosmosdbaccount",
      "apiVersion": "2022-11-15",
      "location": "[parameters('location')]",
      "kind": "GlobalDocumentDB",
      "properties": {
        "consistencyPolicy": {
          "defaultConsistencyLevel": "[parameters('defaultConsistencyLevel')]",
          "maxStalenessPrefix": 1,
          "maxIntervalInSeconds": 5
        },
        "locations": [
          {
            "locationName": "[parameters('location')]",
            "failoverPriority": 0
          }
        ],
        "locations": "[variable('locations')]",
        "databaseAccountOfferType": "Standard",
        "minimalTlsVersion": "[parameters('minimalTlsVersion')]",
      }
    }
}

Importante

Certifique-se de incluir as outras propriedades para a conta e os recursos filho ao reimplantar com essa propriedade. Não implante este modelo como está ou ele redefinirá todas as suas propriedades de conta.

Para novas contas

Você pode criar contas com a propriedade minimalTlsVersion definida usando o modelo do ARM acima ou alterando o método PATCH para um PUT na CLI do Azure ou no Azure PowerShell. Lembre-se de incluir as outras propriedades para sua conta.

Importante

Se a conta existir e a propriedade minimalTlsVersion for omitida em uma solicitação PUT, a propriedade será redefinida para seu valor padrão, a partir da versão 2022-11-15 da API.

Como verificar a imposição da versão mínima do TLS

Como o Cosmos DB impõe a versão mínima do TLS na camada de aplicativo, os verificadores de TLS convencionais que verificam se os handshakes são aceitos pelo serviço para uma versão específica do TLS não são confiáveis para testar a imposição no Cosmos DB. Para verificar a imposição, consulte a ferramenta oficial de código aberto verificadora de TLS do Cosmos.

Você também pode obter o valor atual da propriedade minimalTlsVersion usando a CLI do Azure ou o Azure PowerShell.

Obter o valor atual por meio da CLI do Azure

Para obter o valor atual da propriedade usando a CLI do Azure, execute o comando:

subId=$(az account show --query id -o tsv)
rg="myresourcegroup"
dbName="mycosmosdbaccount"
az rest --uri "/subscriptions/$subId/resourceGroups/$rg/providers/Microsoft.DocumentDB/databaseAccounts/$dbName?api-version=2022-11-15" --method GET

Obter o valor atual por meio do Azure PowerShell

Para obter o valor atual da propriedade usando o Azure PowerShell, execute o comando:

$getParameters = @{
  ResourceGroupName = 'myresourcegroup'
  Name = 'mycosmosdbaccount'
  ResourceProviderName = 'Microsoft.DocumentDB'
  ResourceType = 'databaseaccounts'
  ApiVersion = '2022-11-15'
  Method = 'GET'
}
Invoke-AzRestMethod @getParameters