Imposizione self-service della versione minima di TLS in Azure Cosmos DB

SI APPLICA A: NoSQL MongoDB Cassandra Gremlin Tabella

Questo articolo illustra come imporre una versione minima del protocollo TLS per l'account Cosmos DB usando un'API self-service.

Come funziona l'imposizione self-service della versione minima di TLS in Azure Cosmos DB

A causa della natura multi-tenant di Cosmos DB, è necessario che il servizio soddisfi le esigenze di accesso e sicurezza di ogni utente. A tale scopo, Cosmos DB applica protocolli TLS minimi a livello di applicazione, e non livelli inferiori, nello stack di rete in cui opera TLS. Questa imposizione si verifica in qualsiasi richiesta autenticata in un account di database, in base alle impostazioni configurate nell'account dal cliente.

La versione minima accettata a livello di servizio è TLS 1.0. Questa selezione può essere modificata a livello di account attenendosi alla procedura illustrata nella sezione seguente.

Come impostare la versione minima di TLS per un account di database Cosmos DB

A partire dalla versione 2022-11-15 dell'API del provider di risorse Azure Cosmos DB, viene esposta una nuova proprietà per ogni account di database Cosmos DB, denominata minimalTlsVersion. Il valore può essere uno dei seguenti:

• Tls per impostare la versione minima su TLS 1.0.
• Tls11 per impostare la versione minima su TLS 1.1.
• Tls12 per impostare la versione minima su TLS 1.2.

Il valore predefinito per gli account nuovi è Tls12.

Importante

A partire dal 31 agosto 2025, tutti gli account di database Cosmos DB devono usare Transport Layer Security (TLS) 1.2 o versione successiva, perché il supporto per TLS 1.0 e 1.1 non sarà più disponibile.

Impostare il protocollo TLS minimo in Azure Cosmos DB usando il portale

Questa funzionalità self-service risulta disponibile nel portale durante la creazione e la modifica di un account. Gli account Azure Cosmos DB applicano il protocollo TLS 1.2. Azure Cosmos DB, tuttavia, può supportare anche i protocolli TLS seguenti, a seconda del tipo di API selezionato.

• MongoDB: TLS 1.2

• Cassandra: TLS 1.2

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

Procedura per impostare il protocollo TLS minimo durante la creazione di un account

Se si usa un tipo di API che supporta solo TLS 1.2, si noterà che nella parte bassa della scheda Rete, l'opzione relativa al protocollo TSL risulterà disabilita.

Se invece si usa un tipo di API che accetta più protocolli TLS, nella scheda Rete l'opzione Protocollo Transport Layer Security minimo risulterà disponibile. È possibile modificare il protocollo selezionato facendo clic sull'elenco a discesa e selezionando il protocollo desiderato.

Dopo aver configurato l'account, è possibile verificare che nella scheda Rivedi e crea, nella parte inferiore della sezione Rete, il protocollo TLS selezionato è impostato come specificato.

Procedura per impostare il protocollo TLS minimo durante la modifica di un account

1. Nel portale di Azure passare all'account Azure Cosmos DB.

2. Selezionare Rete dal menu a sinistra e quindi selezionare la scheda Connettività.

3. L'opzione Protocollo Transport Layer Security minimo risulterà disponibile. Se si usa un tipo di API che supporta solo TLS 1.2, si noterà che questa opzione è disabilitata. In caso contrario, sarà possibile selezionare il protocollo TLS desiderato facendo clic su di esso.

4. Fare clic su Salva dopo aver modificato il protocollo TLS.

5. Dopo il salvataggio, si riceverà una notifica di esito positivo. Per avere effetto, tuttavia, questa modifica può richiedere fino a 15 minuti dopo l'aggiornamento della configurazione.

Impostare il protocollo tramite l'interfaccia della riga di comando di Azure

Per impostare il protocollo tramite l'interfaccia della riga di comando di Azure, usare il comando:

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

Impostare il protocollo tramite Azure PowerShell

Per impostare il protocollo tramite Azure PowerShell, usare il 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

Impostare il protocollo tramite un modello di ARM

Per impostare questa proprietà usando un modello di Azure Resource Manager, aggiornare il modello esistente o esportare un nuovo modello per la distribuzione corrente, quindi aggiungere "minimalTlsVersion" alle proprietà delle risorse databaseAccounts, con il valore minimo desiderato della versione TLS. Di seguito è riportato l'esempio di un modello di Azure Resource Manager con questa proprietà impostata tramite un parametro.

{
    {
      "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

Assicurarsi di includere le altre proprietà per l'account e le risorse figlio durante la ridistribuzione con questa proprietà. Non distribuire questo modello così com'è poiché, in caso contrario, verranno reimpostate tutte le proprietà dell'account.

Per nuovi account

È possibile creare account con la proprietà minimalTlsVersion impostata usando il modello di ARM precedente o modificando il metodo PATCH in un'operazione PUT nell'interfaccia della riga di comando di Azure o in Azure PowerShell. Assicurarsi di includere le altre proprietà per l'account.

Importante

Se l'account esiste e in una richiesta PUT viene omessa la proprietà minimalTlsVersion, questa verrà reimpostata sul valore predefinito (a partire dalla versione 2022-11-15 dell'API).

Come verificare l'imposizione della versione TLS minima

Poiché Cosmos DB impone la versione minima di TLS a livello di applicazione, gli scanner TLS convenzionali che controllano se gli handshake vengono accettati dal servizio per una specifica versione TLS non sono affidabili per verificare l'imposizione in Cosmos DB. Per verificare l'imposizione, fare riferimento allo strumento cosmos-tls-scanner open source ufficiale.

È possibile ottenere il valore corrente della proprietà minimalTlsVersion anche tramite l'interfaccia della riga di comando di Azure o Azure PowerShell.

Ottenere il valore corrente tramite l'interfaccia della riga di comando di Azure

Per ottenere il valore corrente della proprietà usando l'interfaccia della riga di comando di Azure, eseguire il 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

Ottenere il valore corrente tramite Azure PowerShell

Per ottenere il valore corrente della proprietà usando Azure PowerShell, eseguire il comando:

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