다음을 통해 공유


Azure Cosmos DB에서 최소 TLS 버전 적용 셀프 서비스

적용 대상: NoSQL MongoDB Cassandra Gremlin Table

이 문서에서는 셀프 서비스 API를 사용하여 Cosmos DB 계정에 최소 버전의 TLS 프로토콜을 적용하는 방법을 설명합니다.

Azure Cosmos DB에서 최소 TLS 버전 적용이 작동하는 방식

Cosmos DB의 다중 테넌트 특성으로 인해 이 서비스는 모든 사용자의 액세스 및 보안 요구 사항을 충족해야 합니다. 이를 위해 Cosmos DB는 TLS가 작동하는 네트워크 스택의 하위 계층이 아니라 애플리케이션 계층에 최소 TLS 프로토콜을 적용합니다. 이러한 적용은 고객이 해당 계정에 대해 설정한 사항에 따라, 특정 데이터베이스 계정에 대한 인증된 요청에서 발생합니다.

허용되는 최소 서비스 전체 버전은 TLS 1.0입니다. 이 선택은 다음 섹션에 설명된 대로 계정별로 변경할 수 있습니다.

내 Cosmos DB 데이터베이스 계정에 대한 최소 TLS 버전을 설정하는 방법

Azure Cosmos DB 리소스 공급자 API 2022-11-15 API 버전부터 모든 Cosmos DB 데이터베이스 계정에 대해 minimalTlsVersion이라는 새 속성이 노출됩니다. 다음 값 중 하나를 허용합니다.

  • 최소 버전을 TLS 1.0으로 설정하기 위한 Tls
  • 최소 버전을 TLS 1.1로 설정하기 위한 Tls11
  • 최소 버전을 TLS 1.2로 설정하기 위한 Tls12

새 계정의 기본값은 Tls12입니다.

Important

2024년 10월 31일부터 모든 Cosmos DB 데이터베이스 계정은 TLS 1.0 및 1.1에 대한 지원이 중단되므로 TLS(전송 계층 보안) 1.2 이상을 사용해야 합니다.

포털을 사용하여 Azure Cosmos DB에서 최소 TLS 프로토콜 설정

이 셀프 서비스 기능은 계정을 만들고 편집하는 동안 포털에서 사용할 수 있습니다. Azure Cosmos DB 계정은 TLS 1.2 프로토콜을 적용합니다. 그러나 Azure Cosmos DB는 선택한 API 종류에 따라 다음 TLS 프로토콜도 지원합니다.

  • MongoDB: TLS 1.2

  • Cassandra: TLS 1.2

  • 테이블, SQL 및 그래프: TLS 1.0, TLS 1.1 및 TLS 1.2

계정을 만드는 동안 최소 TLS 프로토콜을 설정하는 단계

TLS 1.2만 지원하는 API 종류를 사용하는 경우 네트워킹 탭 아래쪽에서 TLS 프로토콜이 비활성화된 것을 확인할 수 있습니다.

TLS 1.2만 지원하는 API 종류 스크린샷

여러 TLS 프로토콜을 허용하는 API 종류를 사용하는 경우 네트워킹 탭으로 이동하면 최소 전송 계층 보안 프로토콜 옵션을 사용할 수 있습니다. 드롭다운을 클릭하고 원하는 프로토콜을 선택하면 선택된 프로토콜을 변경할 수 있습니다.

여러 TLS 프로토콜을 허용하는 API 종류의 스크린샷

계정을 설정한 후 네트워킹 섹션 아래쪽에 있는 검토 + 만들기 탭에서 선택한 TLS 프로토콜이 지정한 대로 설정되어 있는지 검토할 수 있습니다.

선택한 TLS 프로토콜이 지정한 대로 설정된 스크린샷

계정을 편집하는 동안 최소 TLS 프로토콜을 설정하는 단계

  1. Azure Portal에서 Azure Cosmos DB 계정으로 이동합니다.

  2. 왼쪽 메뉴에서 네트워킹을 선택한 다음, 연결 탭을 선택합니다.

  3. 최소 전송 계층 보안 프로토콜 옵션을 찾을 수 있습니다. TLS 1.2만 지원하는 API 종류를 사용하는 경우 이 옵션이 비활성화된 것을 알 수 있습니다. 그렇지 않으면 원하는 TLS 프로토콜을 클릭하여 선택할 수 있습니다.

최소 전송 계층 보안 프로토콜 옵션의 스크린샷

  1. TLS 프로토콜을 변경한 후 저장을 클릭합니다.

변경 후 저장 스크린샷

  1. 저장되면 성공 알림을 받게 됩니다. 그러나 구성 업데이트가 완료된 후 이 변경 내용이 적용되는 데 최대 15분이 걸릴 수 있습니다.

성공 알림 스크린샷

Azure CLI를 통해 설정

Azure CLI를 사용하여 설정하려면 다음 명령을 사용합니다.

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

Azure PowerShell을 통해 설정

Azure PowerShell을 사용하여 설정하려면 다음 명령을 사용합니다.

$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

ARM 템플릿을 통해 설정

ARM 템플릿을 사용하여 이 속성을 설정하려면 기존 템플릿을 업데이트하거나 현재 배포에 대한 새 템플릿을 내보낸 다음, 원하는 최소 TLS 버전 값을 사용하여 databaseAccounts 리소스의 속성에 "minimalTlsVersion"를 추가합니다. 여기에 제공된 기본 예는 이 속성 설정과 매개 변수를 사용하는 Azure Resource Manager 템플릿입니다.

{
    {
      "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')]",
      }
    }
}

Important

이 속성을 사용하여 재배포할 때 계정 및 자식 리소스에 대한 다른 속성을 포함해야 합니다. 이 템플릿을 그대로 배포하면 모든 계정 속성이 초기화됩니다.

새 계정의 경우

위의 ARM 템플릿을 사용하거나 PATCH 메서드를 Azure CLI 또는 Azure PowerShell에서 PUT으로 변경하여 minimalTlsVersion 속성이 설정된 계정을 만들 수 있습니다. 계정에 대한 다른 속성을 포함해야 합니다.

Important

계정이 있고 minimalTlsVersion 속성이 PUT 요청에서 생략된 경우 속성은 2022-11-15 API 버전부터 기본값으로 다시 설정됩니다.

최소 TLS 버전 적용을 확인하는 방법

Cosmos DB는 애플리케이션 계층에서 최소 TLS 버전을 적용하므로 특정 TLS 버전에 대해 서비스에서 핸드셰이크를 허용하는지 여부를 검사하는 기존 TLS 스캐너는 Cosmos DB에서 적용을 테스트하는 데 신뢰할 수 없습니다. 적용을 확인하려면 공식 오픈 소스 cosmos-tls-scanner 도구를 참조하세요.

Azure CLI 또는 Azure PowerShell을 사용하여 minimalTlsVersion 속성의 현재 값을 가져올 수도 있습니다.

Azure CLI를 통해 현재 값 가져오기

Azure CLI를 사용하여 속성의 현재 값을 얻으려면 다음 명령을 실행합니다.

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

Azure PowerShell을 통해 현재 값 가져오기

Azure PowerShell을 사용하여 속성의 현재 값을 얻으려면 다음 명령을 실행합니다.

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