Imposição de versão mínima de TLS de autoatendimento no Azure Cosmos DB

APLICA-SE A: NoSQL MongoDB Cassandra Gremlin Tabela

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

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

Devido à natureza multilocatária do Cosmos DB, o serviço é necessário para atender às necessidades de acesso e segurança de cada usuário. Para conseguir isso, o Cosmos DB impõe protocolos TLS mínimos na camada de aplicativo, e não 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 por 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 é exposta para cada conta de banco de dados do Cosmos DB, chamada minimalTlsVersion. 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 para TLS 1.1.
• Tls12 para definir a versão mínima para 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 Transport Layer Security (TLS) 1.2 ou superior, pois o suporte para TLS 1.0 e 1.1 será descontinuado.

Definir Protocolo TLS Mínimo no Azure Cosmos DB usando o Portal

Este 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

• Tabela, SQL e Gráfico: 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 suporte apenas TLS 1.2, você notará na guia Rede na parte inferior o protocolo TLS desativado.

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

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

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

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

2. Selecione Rede no menu esquerdo e, em seguida, selecione a guia Conectividade.

3. Você encontrará a opção Protocolo de Segurança da Camada de Transporte Mínimo. Se você estiver usando um tipo de API que suporte apenas TLS 1.2, você notará essa opção desativada. 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 sucesso. 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 através 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 via modelo ARM

Para definir essa propriedade usando um modelo ARM, atualize seu modelo existente ou exporte um novo modelo para sua implantação atual e, em seguida, adicione "minimalTlsVersion" às propriedades dos databaseAccounts recursos, com o valor mínimo desejado da versão TLS. Fornecido aqui está um exemplo básico de um modelo do Azure Resource Manager com essa configuração de propriedade, usando um parâmetro.

{
    {
      "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 sua conta e recursos filho ao reimplantar com essa propriedade. Não implante este modelo como está ou ele redefinirá todas as propriedades da sua conta.

Para novas contas

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

Importante

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

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

Como o Cosmos DB impõe a versão mínima do TLS na camada de aplicativo, os scanners 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 aplicação no Cosmos DB. Para verificar a aplicação, consulte a ferramenta oficial de código aberto cosmos-tls-scanner.

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

Obtenha 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

Obtenha 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