Azure Key Vault를 사용하여 Azure Cosmos DB 계정에 대한 고객 관리형 키 구성

아티클
08/15/2024

적용 대상: NoSQL MongoDB Cassandra Gremlin 테이블

Azure Cosmos DB 계정에 저장된 데이터는 Microsoft에서 관리하는 키(서비스 관리형 키)로 자동으로 원활하게 암호화됩니다. 필요에 따라 직접 관리하는 키(고객 관리형 키 또는 CMK)를 사용하여 두 번째 암호화 계층을 추가하도록 선택할 수 있습니다.

고객 데이터를 둘러싸는 암호화 계층의 다이어그램.

고객 관리형 키를 Azure Key Vault에 저장하고 고객 관리형 키를 사용하도록 설정된 각 Azure Cosmos DB 계정에 키를 제공해야 합니다. 이 키는 해당 계정에 저장된 모든 데이터를 암호화하는 데 사용됩니다.

참고 항목

기존 Azure Cosmos DB 계정에서 고객 관리형 키를 사용하도록 설정하려는 경우 자세한 내용은 여기 링크를 참조하세요.

Warning

다음 필드 이름은 고객 관리형 키를 사용하여 계정의 Cassandra API 테이블에 예약되어 있습니다.

id
ttl
_ts
_etag
_rid
_self
_attachments
_epk

고객 관리형 키를 사용하도록 설정하지 않으면 __sys_로 시작하는 필드 이름만 예약됩니다.

필수 조건

활성 구독이 있는 Azure 계정. 체험 계정을 만듭니다.

Azure Cosmos DB 리소스 공급자 등록

Microsoft.DocumentDB 리소스 공급자가 아직 등록되지 않은 경우 이 공급자를 첫 번째 단계로 등록해야 합니다.

Azure Portal에 로그인하고 Azure 구독으로 이동하여 설정 탭에서 리소스 공급자를 선택합니다.
Microsoft.DocumentDB 리소스 공급자를 검색합니다. 리소스 공급자가 이미 등록된 것으로 표시되어 있는지 확인합니다. 그렇지 않으면 리소스 공급자를 선택하고 등록을 선택합니다.

Azure Key Vault 인스턴스 구성

Important

Azure Key Vault 인스턴스는 공용 네트워크 액세스를 통해 액세스할 수 있거나 신뢰할 수 있는 Microsoft 서비스가 방화벽을 바이패스하도록 허용해야 합니다. 프라이빗 엔드포인트를 통해서만 액세스할 수 있는 인스턴스는 고객 관리형 키를 호스팅하는 데 사용할 수 없습니다.

Azure Cosmos DB에서 고객 관리형 키를 사용하려면 암호화 키를 호스팅하는 데 사용할 Azure Key Vault 인스턴스에서 일시 삭제 및 보호 제거라는 두 가지 속성을 설정해야 합니다.

새 Azure Key Vault 인스턴스를 만드는 경우 생성 중에 이러한 속성을 사용하도록 설정합니다.
기존 Azure Key Vault 인스턴스를 사용하는 경우 Azure Portal에서 속성 섹션을 보면 이러한 속성을 사용하도록 설정되어 있는지 확인할 수 있습니다. 이러한 속성 중 하나라도 사용하도록 설정되어 있지 않으면 다음 문서 중 하나에서 "일시 삭제를 사용하도록 설정" 및 "제거 보호 활성화" 섹션을 참조하세요.
- PowerShell에서 일시 삭제를 사용하는 방법
- Azure CLI에서 일시 삭제를 사용하는 방법

기본 설정 보안 모델 선택

제거 보호 및 일시 삭제를 사용하도록 설정하면 액세스 정책 탭에서 사용할 기본 사용 권한 모델을 선택할 수 있습니다. 액세스 정책은 기본적으로 설정되지만 Azure 역할 기반 액세스 제어도 지원됩니다.

Cosmos DB에서 암호화 키를 사용할 수 있도록 허용하려면 필요한 권한을 부여해야 합니다. 이 단계는 Azure Key Vault가 액세스 정책을 사용하는지 또는 역할 기반 액세스 제어를 사용하는지에 따라 달라집니다.

참고 항목

한 번에 하나의 보안 모델만 활성 상태일 수 있으므로 Azure Key Vault가 액세스 정책을 사용하도록 설정된 경우 역할 기반 액세스 제어를 시드할 필요가 없으며 그 반대의 경우도 마찬가지입니다.

액세스 정책 추가

이 변형에서는 Azure Cosmos DB 보안 주체를 사용하여 적절한 권한으로 액세스 정책을 만듭니다.

Azure Portal에서 암호화 키를 호스트하는 데 사용할 Azure Key Vault 인스턴스로 이동합니다. 왼쪽 메뉴에서 액세스 정책을 선택합니다.
+ 액세스 정책 추가를 선택합니다.
키 권한 드롭다운 메뉴에서 가져오기, 키 래핑 해제, 키 래핑 권한을 선택합니다.
주체 선택에서 선택된 항목 없음을 선택합니다.
Azure Cosmos DB 보안 주체를 검색하여 선택합니다.(쉽게 찾을 수 있도록 애플리케이션 ID가 11112222-bbbb-3333-cccc-4444dddd5555인 Azure Government 지역을 제외한 모든 Azure 지역에 대해 애플리케이션 ID: 00001111-aaaa-2222-bbbb-3333cccc4444로 검색할 수도 있습니다.)

팁

그러면 Azure Key Vault 액세스 정책에 Azure Cosmos DB 자사 ID가 등록됩니다. Azure Cosmos DB 보안 주체가 목록에 없으면 Microsoft.DocumentDB 리소스 공급자를 다시 등록해야 할 수도 있습니다.
아래쪽에서 선택을 선택합니다.
추가를 선택하여 새로운 액세스 정책을 추가합니다.
Key Vault 인스턴스에서 저장을 선택하여 모든 변경 내용을 저장합니다.

역할 기반 액세스 제어 역할 추가

Azure Portal에서 암호화 키를 호스트하는 데 사용할 Azure Key Vault 인스턴스로 이동합니다. 왼쪽 메뉴에서 액세스 제어(IAM)를 선택하고 이 리소스에 액세스 권한 부여를 선택합니다.
Key Vault 관리자 역할을 검색하고 자신에게 할당합니다. 이 할당은 먼저 목록에서 역할 이름을 검색한 다음 “구성원” 탭을 클릭하여 수행됩니다. 탭에 있는 라디오에서 “사용자, 그룹 또는 서비스 주체” 옵션을 선택한 다음, Azure 계정을 조회합니다. 계정이 선택되면 역할을 할당할 수 있습니다.
그런 다음, 필요한 권한을 Cosmos DB의 보안 주체에 할당해야 합니다. 따라서 마지막 역할 할당과 마찬가지로 할당 페이지로 이동하지만 이번에는 "Key Vault 암호화 서비스 암호화 사용자" 역할을 찾고 멤버 탭에서 Cosmos DB의 보안 주체를 찾습니다. 보안 주체를 찾으려면 Azure Cosmos DB 보안 주체를 검색하고 선택합니다.

Important

Azure Government 지역에서 애플리케이션 ID는 11112222-bbbb-3333-cccc-4444dddd5555입니다.
검토 + 할당을 선택하면 역할이 Cosmos DB에 할당됩니다.

역할이 올바르게 설정되었는지 확인

다음으로 액세스 제어 페이지를 사용하여 모든 역할이 올바르게 구성되었는지 확인합니다.

역할이 할당되면 Access Control IAM 페이지에서 "이 리소스에 대한 액세스 권한 보기"를 선택하여 모든 권한이 올바르게 설정되었는지 확인합니다.
이 페이지에서 범위를 "이 리소스"로 설정하고 본인에게 Key Vault 관리자 역할이 있고 Cosmos DB 보안 주체에 Key Vault 암호화 사용자 역할이 있는지 확인합니다.

Azure Key Vault에서 새 키 생성

여기서는 Azure Key Vault를 사용하여 새 키를 만들고 고유 식별자를 검색합니다.

Azure Portal에서 암호화 키를 호스트하는 데 사용할 Azure Key Vault 인스턴스로 이동합니다. 그런 다음, 왼쪽 메뉴에서 키를 선택합니다.
생성/가져오기를 선택하고 새 키의 이름을 제공하고 RSA 키 크기를 선택합니다. 최상의 보안을 위해 3072 이상을 사용하는 것이 좋습니다. 만들기를 선택합니다.
팁

또는 Azure CLI를 사용하여 다음을 사용하여 키를 생성할 수 있습니다.
```
az keyvault key create \
    --vault-name <name-of-key-vault> \
    --name <name-of-key>
```
Azure CLI를 사용하여 키 자격 증명 모음을 관리하는 방법에 대한 자세한 내용은 Azure CLI를 사용하여 Azure Key Vault 관리를 참조하세요.
키가 생성되면 새로 생성된 키를 선택한 다음, 현재 버전을 선택합니다.
마지막 슬래시 뒷 부분을 제외하고 키의 키 식별자를 복사합니다.

새 Azure Cosmos DB 계정 만들기

Azure Portal 또는 Azure CLI를 사용하여 새 Azure Cosmos DB 계정을 만듭니다.

Azure Portal에서 새 Azure Cosmos DB 계정을 생성할 때 암호화 단계에서 고객 관리형 키를 선택합니다. 키 URI 필드에 이전 단계에서 복사한 Azure Key Vault 키의 URI/키 식별자를 붙여넣습니다.

PowerShell을 사용하여 새 Azure Cosmos DB 계정을 만드는 경우:

앞서 PropertyObject의 keyVaultKeyUri 속성 아래에서 복사한 Azure Key Vault 키의 URI를 전달합니다.
2019-12-12 이상의 API 버전을 사용합니다.

Important

고객 관리형 키를 사용하여 계정을 만들려면 locations 속성을 명시적으로 설정해야 합니다.

# Variable for resource group name
$RESOURCE_GROUP_NAME = "<resource-group-name>"

# Variable for location
$LOCATION = "<azure-region>"

# Variable for account name
$ACCOUNT_NAME = "<globally-unique-account-name>"

# Variable for key URI in the key vault
$KEY_VAULT_KEY_URI="https://<key-vault-name>.vault.azure.net/keys/<key-name>"

$parameters = @{
    ResourceType = "Microsoft.DocumentDb/databaseAccounts"
    ApiVersion = "2019-12-12"
    ResourceGroupName = $RESOURCE_GROUP_NAME
    Location = $LOCATION 
    Name = $ACCOUNT_NAME 
    PropertyObject = @{
        databaseAccountOfferType = "Standard"
        locations = @(
            @{ 
                locationName = $LOCATION 
                failoverPriority = 0
            }
        )
        keyVaultKeyUri = $KEY_VAULT_KEY_URI
    }
}
New-AzResource @parameters

계정이 생성되면 Azure Key Vault 키의 URI를 가져와서 고객 관리형 키를 사용하도록 설정되었는지 확인할 수 있습니다.

$parameters = @{
    ResourceGroupName = $RESOURCE_GROUP_NAME
    Name = $ACCOUNT_NAME
    ResourceType = "Microsoft.DocumentDb/databaseAccounts"
}
Get-AzResource @parameters
    | Select-Object -ExpandProperty Properties
    | Select-Object -ExpandProperty keyVaultKeyUri

Azure Resource Manager 템플릿을 통해 새 Azure Cosmos DB 계정을 만드는 경우:

앞서 properties 개체의 keyVaultKeyUri 속성 아래에서 복사한 Azure Key Vault 키의 URI를 전달합니다.
2019-12-12 이상의 API 버전을 사용합니다.

Important

고객 관리형 키를 사용하여 계정을 만들려면 locations 속성을 명시적으로 설정해야 합니다.

{
  "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "accountName": {
      "type": "string"
    },
    "location": {
      "type": "string"
    },
    "keyVaultKeyUri": {
      "type": "string"
    }
  },
  "resources": [
    {
      "type": "Microsoft.DocumentDB/databaseAccounts",
      "name": "[parameters('accountName')]",
      "apiVersion": "2019-12-12",
      "kind": "GlobalDocumentDB",
      "location": "[parameters('location')]",
      "properties": {
        "locations": [
          {
            "locationName": "[parameters('location')]",
            "failoverPriority": 0,
            "isZoneRedundant": false
          }
        ],
        "databaseAccountOfferType": "Standard",
        "keyVaultKeyUri": "[parameters('keyVaultKeyUri')]"
      }
    }
  ]
}

다음 PowerShell 스크립트를 사용하여 템플릿을 배포합니다.

# Variable for resource group name
$RESOURCE_GROUP_NAME = "<resource-group-name>"

# Variable for location
$LOCATION = "<azure-region>"

# Variable for account name
$ACCOUNT_NAME = "<globally-unique-account-name>"

# Variable for key URI in the key vault
$KEY_VAULT_KEY_URI="https://<key-vault-name>.vault.azure.net/keys/<key-name>"

$parameters = @{
    ResourceGroupName = $RESOURCE_GROUP_NAME
    TemplateFile = "deploy.json"
    accountName = $ACCOUNT_NAME
    location = $LOCATION
    keyVaultKeyUri = $KEY_VAULT_KEY_URI
}
New-AzResourceGroupDeployment @parameters

Azure CLI를 통해 새 Azure Cosmos DB 계정을 만드는 경우 앞서 --key-uri 매개 변수 아래에서 복사한 Azure Key Vault 키의 URI를 전달합니다.

# Variable for resource group name
resourceGroupName="<resource-group-name>"

# Variable for location
location="<azure-region>"

# Variable for account name
accountName="<globally-unique-account-name>"

# Variable for key URI in the key vault
keyVaultKeyUri="https://<key-vault-name>.vault.azure.net/keys/<key-name>"

az cosmosdb create \
    --resource-group $resourceGroupName \
    --name $accountName \
    --locations regionName=$location \
    --key-uri $keyVaultKeyUri

계정이 생성되면 Azure Key Vault 키의 URI를 가져와서 고객 관리형 키를 사용하도록 설정되었는지 확인할 수 있습니다.

az cosmosdb show \
    --resource-group $resourceGroupName \
    --name $accountName \
    --query "keyVaultKeyUri"

Important

네트워크 구성에 따라 다른 Azure 서비스에서 Azure Cosmos DB에 대한 액세스를 허용해야 할 수도 있습니다.

Azure Key Vault 액세스 정책에서 관리 ID 사용

이 액세스 정책을 사용하면 Azure Cosmos DB 계정에서 암호화 키에 액세스할 수 있습니다. 액세스 정책은 특정 Microsoft Entra ID에 대한 액세스 권한을 부여하여 구현됩니다. 지원되는 두 가지 유형의 ID는 다음과 같습니다.

Azure Cosmos DB의 자사 ID를 사용하여 Azure Cosmos DB 서비스에 대한 액세스 권한을 부여할 수 있습니다.
계정에 대한 액세스 권한을 부여하는 데에는 Azure Cosmos DB 계정의 관리 ID를 사용할 수 있습니다.

ARM 템플릿을 사용하여 액세스 정책에 관리 ID를 할당할 수 있습니다.

시스템 할당 관리 ID는 계정을 만든 후에만 검색할 수 있으므로 먼저 자사 ID를 사용하여 계정을 만들어야 합니다. 다음 작업:

시스템 할당 관리 ID가 계정을 만드는 동안 구성되지 않은 경우 사용자 계정에서 시스템 할당 관리 ID를 사용하도록 설정하고 할당된 principalId를 복사합니다.
앞에서 설명한 대로 Azure Key Vault 계정에 대리 권한을 추가합니다. Cosmos DB 보안 주체를 사용하는 대신, Azure Cosmos DB의 자사 ID 대신 이전 단계에서 복사한 principalId를 사용합니다.
Azure Key Vault의 암호화 키에 액세스할 때 시스템 할당 관리 ID를 사용하도록 지정하려면 Azure Cosmos DB 계정을 업데이트합니다.
```
{
  "type": " Microsoft.DocumentDB/databaseAccounts",
  "properties": {
    "defaultIdentity": "SystemAssignedIdentity",
    // ...
  },
  // ...
}
```
필요에 따라 Azure Key Vault 액세스 정책에서 Azure Cosmos DB 자사 ID를 제거할 수 있습니다.

사용자가 할당한 관리 ID를 사용하여 유사한 단계를 수행할 수도 있습니다.

Azure Key Vault 계정에서 새 액세스 정책 또는 역할 할당을 만들 때 Azure Cosmos DB의 자사 ID 대신 사용하려는 관리 ID의 Object ID를 사용합니다.

Azure Cosmos DB 계정을 만들 때 사용자 할당 관리 ID를 사용하도록 설정하고 Azure Key Vault에서 암호화 키에 액세스할 때 이 ID를 사용하도록 지정해야 합니다.

{
  "type": "Microsoft.DocumentDB/databaseAccounts",
  "identity": {
    "type": "UserAssigned",
    "userAssignedIdentities": {
      "<identity-resource-id>": {}
    }
  },
  // ...
  "properties": {
    "defaultIdentity": "UserAssignedIdentity=<identity-resource-id>",
    "keyVaultKeyUri": "<key-vault-key-uri>"
    // ...
  }
}

Azure CLI를 사용하여 액세스 정책에 관리 ID를 할당할 수 있습니다.

시스템 할당 관리 ID는 계정을 만든 후에만 검색할 수 있으므로 먼저 자사 ID를 사용하여 계정을 만들어야 합니다. 다음 작업:

시스템 할당 관리 ID가 계정을 만드는 동안 구성되지 않은 경우 사용자 계정에서 시스템 할당 관리 ID를 사용하도록 설정하고 할당된 principalId를 복사합니다.
앞에서 설명한 대로 Azure Key Vault 계정에 대리 권한을 추가합니다. Cosmos DB 보안 주체를 사용하는 대신, Azure Cosmos DB의 자사 ID 대신 이전 단계에서 복사한 principalId를 사용합니다.

Azure Key Vault의 암호화 키에 액세스할 때 시스템 할당 관리 ID를 사용하도록 지정하려면 Azure Cosmos DB 계정을 업데이트합니다.

# Variables for resource group and account names
resourceGroupName="<resource-group-name>"
accountName="<azure-cosmos-db-account-name>"

az cosmosdb update \
    --resource-group $resourceGroupName \
    --name $accountName \
    --default-identity "SystemAssignedIdentity"

필요에 따라 Azure Key Vault 액세스 정책에서 Azure Cosmos DB 자사 ID를 제거할 수 있습니다.

사용자가 할당한 관리 ID를 사용하여 유사한 단계를 수행할 수도 있습니다.

Azure Key Vault 계정에서 새 액세스 정책 또는 역할 할당을 만들 때 Azure Cosmos DB의 자사 ID 대신 사용하려는 관리 ID의 Object ID를 사용합니다.

# Variables for resource group and account name
resourceGroupName="<resource-group-name>"
accountName="<azure-cosmos-db-account-name>"

# Variable for location
location="<azure-region>"

# Variable for key URI in the key vault
keyVaultKeyUri="https://<key-vault-name>.vault.azure.net/keys/<key-name>"

# Variables for identities
identityId="<identity-resource-id>"

az cosmosdb create \
    --resource-group $resourceGroupName \
    --name $accountName \
    --locations regionName=$location \
    --key-uri $keyVaultKeyUri
    --assign-identity $identityId \
    --default-identity "UserAssignedIdentity=$identityId"

사용할 수 없음

연속 백업과 함께 고객 관리형 키 사용

Azure CLI 또는 Azure Resource Manager 템플릿을 사용하여 지속적인 백업 계정을 만들 수 있습니다.

현재, 지속적인 백업 계정 만들기에는 사용자가 할당한 관리 ID만 지원됩니다.

계정이 만들어지면 ID를 시스템 할당 관리 ID로 업데이트할 수 있습니다.

또는 사용자가 주기적 백업 모드를 사용하여 시스템 ID를 먼저 만든 다음, Azure Cosmos DB 계정을 주기적 백업 모드에서 연속 백업 모드로 마이그레이션 지침을 사용하여 계정을 연속 백업 모드로 마이그레이션할 수도 있습니다.

# Variables for resource group and account name
resourceGroupName="<resource-group-name>"
accountName="<azure-cosmos-db-account-name>"

# Variable for location
location="<azure-region>"

# Variable for key URI in the key vault
keyVaultKeyUri="https://<key-vault-name>.vault.azure.net/keys/<key-name>"

# Variables for identities
identityId="<identity-resource-id>"

az cosmosdb create \
    --resource-group $resourceGroupName \
    --name $accountName \
    --locations regionName=$location \
    --key-uri $keyVaultKeyUri
    --assign-identity $identityId \
    --default-identity "UserAssignedIdentity=$identityId" \
    --backup-policy-type "Continuous"

Azure Resource Manager 템플릿을 통해 새 Azure Cosmos DB 계정을 만드는 경우:

앞서 properties 개체의 keyVaultKeyUri 속성 아래에서 복사한 Azure Key Vault 키의 URI를 전달합니다.
2021-11-15 이상의 API 버전을 사용합니다.

Important

앞의 예와 같이 고객 관리형 키로 계정을 성공적으로 만들려면 locations 속성을 명시적으로 설정해야 합니다.

{
  "type": "Microsoft.DocumentDB/databaseAccounts",
  "identity": {
    "type": "UserAssigned",
    "userAssignedIdentities": {
      "<identity-resource-id>": {}
    }
  },
  // ...
  "properties": {
    "backupPolicy": {
      "type": "Continuous"
    },
    "defaultIdentity": "UserAssignedIdentity=<identity-resource-id>""keyVaultKeyUri": "<key-vault-key-uri>"
    // ...
  }
}

사용할 수 없음

관리 ID로 구성된 연속 계정 복원

원본 계정 관리 ID(사용자 할당 및 시스템 할당 ID)를 대상 데이터베이스 계정으로 자동으로 전달될 수 없으므로 복원 요청에 사용자 할당 ID가 필요합니다.

Azure CLI
PowerShell/Azure Resource Manager 템플릿/Azure Portal

Azure CLI를 사용하여 시스템 할당 또는 사용자 할당 관리 ID를 사용하여 이미 구성된 연속 계정을 복원합니다.

복원 프로세스에 대해 새 사용자 할당 ID를 만들거나 기존 ID를 사용합니다.
앞에서 설명한 대로 Azure Key Vault 계정에 새 액세스 정책을 만들고 1단계에서 가져온 관리 ID의 개체 ID를 사용합니다.

Azure CLI를 사용하여 복원을 트리거합니다.

# Variables for resource group and account names
resourceGroupName="<resource-group-name>"
sourceAccountName="<source-azure-cosmos-db-account-name>"
targetAccountName="<target-azure-cosmos-db-account-name>"

# Variable for location
location="<azure-region>"

# Variables for identities
identityId="<identity-resource-id>"

# Variable for timestamp to restore to
timestamp="<timestamp-in-utc>"

az cosmosdb restore \ 
    --resource-group $resourceGroupName \
    --account-name $sourceAccountName \
    --target-database-account-name $targetAccountName \
    --location $location \
    --restore-timestamp $timestamp \
    --assign-identity $identityId \
    --default-identity "UserAssignedIdentity=$identityId" \

복원이 완료되면 대상(복원된) 계정에 사용자 할당 ID가 있습니다. 원할 경우 시스템 할당 관리 ID를 사용하도록 계정을 업데이트할 수 있습니다.

사용할 수 없음

고객 관리형 키 및 이중 암호화

고객 관리형 키를 사용할 때 Azure Cosmos DB 계정에 저장하는 데이터는 두 번 암호화됩니다.

기본 암호화를 통해 Microsoft 관리형 키로 수행되는 경우.
추가 암호화를 통해 고객 관리형 키로 수행되는 경우.

이중 암호화는 기본 Azure Cosmos DB 트랜잭션 스토리지에만 적용됩니다. 일부 기능에는 고객 관리형 키를 사용하더라도 이중 암호화가 제공되지 않는 두 번째 스토리지 계층으로 데이터를 내부 복제하는 것이 포함됩니다. 다음과 같은 기능이 있습니다.

키 회전

Azure Cosmos DB 계정에서 사용하는 고객 관리형 키 회전은 두 가지 방법으로 수행할 수 있습니다.

Azure Key Vault에서 현재 사용되는 키의 새 버전을 만듭니다.

계정에 대한 키 URI를 업데이트하여 현재 사용되는 키를 다른 키로 바꿉니다. Azure Portal에서 Azure Cosmos DB 계정으로 이동하고 왼쪽 메뉴에서 데이터 암호화를 선택합니다.

리소스 탐색 메뉴의 데이터 암호화 옵션 스크린샷.

그런 다음, 키 URI를 사용하려는 새 키로 바꾸고 저장을 선택합니다.

PowerShell에서 동일한 결과를 얻기 위해 수행하는 방법은 다음과 같습니다.

# Variable for resource group name
$RESOURCE_GROUP_NAME = "<resource-group-name>"

# Variable for account name
$ACCOUNT_NAME = "<globally-unique-account-name>"

# Variable for new key URI in the key vault
$NEW_KEY_VAULT_KEY_URI="https://<key-vault-name>.vault.azure.net/keys/<new-key-name>"

$parameters = @{
    ResourceGroupName = $RESOURCE_GROUP_NAME 
    Name = $ACCOUNT_NAME
    ResourceType = "Microsoft.DocumentDb/databaseAccounts"
}
$ACCOUNT = Get-AzResource @parameters

$ACCOUNT.Properties.keyVaultKeyUri = $NEW_KEY_VAULT_KEY_URI

$ACCOUNT | Set-AzResource -Force

이전 키 또는 키 버전은 해당 키 또는 키 버전의 Azure Cosmos DB 활동이 Azure Key Vault 감사 로그에 더 이상 표시되지 않으면 사용하지 않도록 설정할 수 있습니다. 키 회전 24시간 후에는 이전 키 또는 키 버전에서 더 이상 활동이 진행되지 않아야 합니다.

이전 키가 사용하지 않도록 설정되거나 삭제되지 않는 한 Azure Key Vault의 키 자동 회전이 지원됩니다. 내부 시스템에서는 계정이 해지된 상태가 아니거나 고객 관리형 키를 사용하도록 설정하기 위한 전환 중인지 유효성을 검사한 후 새 버전의 키를 따라잡는 데 시간이 필요합니다.

오류 처리

Azure Cosmos DB의 고객 관리형 키에 오류가 있는 경우 Azure Cosmos DB는 응답에 HTTP 하위 상태 코드와 함께 오류 세부 정보를 반환합니다. HTTP 하위 상태 코드를 사용하여 문제의 근본 원인을 디버그할 수 있습니다. 지원되는 HTTP 하위 상태 코드 목록을 가져오려면 Azure Cosmos DB에 대한 HTTP 상태 코드 문서를 참조하세요.

자주 묻는 질문

여기에는 Azure Cosmos DB에서 고객 관리형 키를 설정하는 방법에 대한 질문과 대답이 포함되어 있습니다.

고객 관리형 키를 사용하도록 설정하는 데 추가 요금이 있나요?

아니요,이 기능을 사용하도록 설정하는 데 청구되는 요금은 없습니다.

고객 관리형 키는 용량 계획에 어떤 영향을 주나요?

데이터베이스 작업에서 사용하는 요청 단위는 고객 관리형 키를 사용할 때 데이터의 암호화 및 암호 해독을 수행하는 데 필요한 추가 처리를 반영하기 위해 증가합니다. 추가 RU 소비는 프로비전된 용량의 사용률을 약간 높일 수 있습니다. 이 표를 가이드로 참조하세요.

작업 유형	요청 단위 증가
포인트 읽기(ID별 항목 가져오기)	작업당 +5%
모든 쓰기 작업	작업당 6% 이상 \| 인덱싱된 속성당 약 0.06RU 이상
쿼리, 변경 피드 읽기 또는 충돌 피드	작업당 +15%

고객 관리형 키로 어떤 데이터가 암호화되나요?

Azure Cosmos DB 계정에 저장된 모든 데이터는 고객 관리형 키로 암호화되며 단, 다음 메타데이터는 제외됩니다.

Azure Cosmos DB 계정, 데이터베이스 및 컨테이너의 이름
저장 프로시저의 이름
인덱싱 정책에 선언된 속성 경로
컨테이너의 파티션 키 값

기존 Azure Cosmos DB 계정에 고객 관리형 키가 지원되나요?

예. 기존 Azure Cosmos DB 계정에 고객 관리형 키를 설정하는 방법을 참조하세요.

고객 관리형 키를 Azure Cosmos DB 분석 저장소에서 사용할 수 있나요?

예, Azure Synapse Link는 Azure Cosmos DB 계정의 관리 ID를 사용하는 고객 관리형 키 구성만 지원합니다. 하지만 계정에서 Azure Synapse Link를 사용하도록 설정하기 전에 Azure Key Vault 액세스 정책에서 Azure Cosmos DB 계정의 관리 ID를 사용해야 합니다. 관리 ID를 사용하도록 설정하고 액세스 정책에서 사용하는 방법에 대한 방법 가이드는 관리 ID를 사용하여 Azure Cosmos DB에서 Azure Key Vault에 액세스를 참조하세요.

계정 수준 키보다 세부적인 수준을 지원할 계획이 있나요?

현재는 아니지만, 컨테이너 수준 키를 고려하고 있습니다.

Azure Cosmos DB 계정에서 고객 관리형 키를 사용하도록 설정되어 있는지 어떻게 알 수 있나요?

Azure Portal에서 Azure Cosmos DB 계정으로 이동하고 왼쪽 메뉴에서 데이터 암호화 항목을 확인합니다. 이 항목이 있으면 계정에서 고객 관리형 키를 사용할 수 있습니다.

리소스 탐색 메뉴의 데이터 암호화 옵션 스크린샷.

또한 Azure Cosmos DB 계정에 대한 세부 정보를 프로그래밍 방식으로 가져와서 keyVaultKeyUri 속성이 있는지 확인할 수 있습니다.

고객 관리형 키는 정기 백업에 어떤 영향을 주나요?

Azure Cosmos DB는 계정에 저장된 데이터를 정기적으로 자동 백업합니다. 이러한 작업은 암호화된 데이터를 백업합니다.

정기 백업을 성공적으로 복원하려면 다음 조건이 필요합니다.

백업 시 사용한 암호화 키가 필요하며 Azure Key Vault에서 사용할 수 있어야 합니다. 이 조건에서는 취소가 이루어지지 않았으며 백업 시 사용된 키 버전이 여전히 사용하도록 설정되어 있어야 합니다.
액세스 정책에서 시스템 할당 관리 ID를 사용한 경우 데이터를 복원하기 전에 Azure Cosmos DB 자사 ID에 대한 액세스 권한을 일시적으로 부여합니다. 이 요구 사항은 시스템 할당 관리 ID가 계정에 고유하고 대상 계정에서 재사용할 수 없기 때문에 존재합니다. 데이터가 대상 계정으로 완전히 복원되면 원하는 ID 구성을 설정하고 Key Vault 액세스 정책에서 자사 ID를 제거할 수 있습니다.

고객 관리형 키는 지속적인 백업에 어떤 영향을 주나요?

Azure Cosmos DB는 계정에서 지속적 백업을 구성할 수 있는 옵션을 제공합니다. 지속적인 백업을 사용하면 지난 30일 이내의 어느 시점으로든 데이터를 복원할 수 있습니다. 고객 관리형 키가 사용하도록 설정된 계정에서 지속적인 백업을 사용하려면 Key Vault 액세스 정책에서 시스템 지정되거나 혹은 사용자 지정 관리 ID를 사용해야 합니다. Azure Cosmos DB 자사 ID는 현재 지속적인 백업을 사용하는 계정에서 지원되지 않습니다.

사용자 할당 ID를 업데이트하기 위한 고객 관리형 키 사용 계정의 필수 구성 요소 단계입니다.

Cosmos DB 계정에 사용자 할당 ID를 추가하고 키 자격 증명 모음 액세스 정책에 권한을 부여합니다.
Azure CLI 또는 ARM을 통해 사용자가 할당한 ID를 기본 ID로 설정합니다.

az cosmosdb update --resource-group MyResourceGroup --name MyAccountName --default-identity UserAssignedIdentity=/subscriptions/MySubscriptionId/resourcegroups/MyResourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/MyUserAssignedIdentity

특정 시점 복원을 성공적으로 수행하려면 다음 조건이 필요합니다.

백업 시 사용한 암호화 키가 필요하며 Azure Key Vault에서 사용할 수 있어야 합니다. 이 요구 사항은 취소가 이루어지지 않았으며 백업 시 사용된 키 버전이 여전히 사용하도록 설정되어 있음을 의미합니다.
원본 계정에서 원래 사용된 사용자 할당 관리 ID가 여전히 Key Vault 액세스 정책에 선언되어 있는지 확인해야 합니다.

Important

계정을 삭제하기 전에 암호화 키를 해지한 경우 최대 1시간 전에 작성된 데이터가 계정 백업에서 누락될 수 있습니다.

암호화 키를 어떻게 해지하나요?

키 해지는 최신 버전의 키를 사용하지 않도록 설정하여 수행됩니다.

또는 Azure Key Vault 인스턴스에서 모든 키를 해지하려면 Azure Cosmos DB 보안 주체에 부여된 액세스 정책을 삭제하면 됩니다.

고객 관리형 키가 해지되면 어떤 작업을 수행할 수 있나요?

암호화 키가 해지된 경우 가능한 유일한 작업은 계정 삭제입니다.

복원된 데이터베이스 계정에 새 관리 ID를 할당하여 데이터베이스 계정에 계속 액세스하거나 액세스 권한을 복구합니다.

사용자 할당 ID는 지정된 Cosmos DB 계정에 연결되며, 계정에 사용자 할당 ID를 할당할 때마다 ARM은 관리 서비스 ID에 요청을 전달하여 이 연결을 만듭니다. 현재 CMK + 사용자 할당 ID를 복원하는 동안(연속 및 주기적 백업 복원 모두 해당) 원본 데이터베이스 계정에서 대상 데이터베이스 계정으로 사용자 ID 정보를 전달합니다.

ID 메타데이터는 원본 데이터베이스 계정과 바인딩되고 복원 워크플로는 ID 범위를 대상 데이터베이스 계정으로 다시 지정하지 않습니다. 이렇게 하면 복원된 데이터베이스 계정이 잘못된 상태가 되며, 원본 계정이 삭제되고 ID의 갱신 시간이 만료된 후에 액세스할 수 없게 됩니다.

새 관리 ID를 할당하는 단계:

다음 단계

Azure Cosmos DB의 데이터 암호화에 대해 알아봅니다.

다음을 통해 공유

Azure Key Vault를 사용하여 Azure Cosmos DB 계정에 대한 고객 관리형 키 구성

필수 조건

Azure Cosmos DB 리소스 공급자 등록

Azure Key Vault 인스턴스 구성

기본 설정 보안 모델 선택

액세스 정책 추가

역할 기반 액세스 제어 역할 추가

역할이 올바르게 설정되었는지 확인

Azure Key Vault에서 새 키 생성

새 Azure Cosmos DB 계정 만들기

Azure Key Vault 액세스 정책에서 관리 ID 사용

연속 백업과 함께 고객 관리형 키 사용

관리 ID로 구성된 연속 계정 복원

고객 관리형 키 및 이중 암호화

키 회전

오류 처리

자주 묻는 질문

고객 관리형 키를 사용하도록 설정하는 데 추가 요금이 있나요?

고객 관리형 키는 용량 계획에 어떤 영향을 주나요?

고객 관리형 키로 어떤 데이터가 암호화되나요?

기존 Azure Cosmos DB 계정에 고객 관리형 키가 지원되나요?

고객 관리형 키를 Azure Cosmos DB 분석 저장소에서 사용할 수 있나요?

계정 수준 키보다 세부적인 수준을 지원할 계획이 있나요?

Azure Cosmos DB 계정에서 고객 관리형 키를 사용하도록 설정되어 있는지 어떻게 알 수 있나요?

고객 관리형 키는 정기 백업에 어떤 영향을 주나요?

고객 관리형 키는 지속적인 백업에 어떤 영향을 주나요?

암호화 키를 어떻게 해지하나요?

고객 관리형 키가 해지되면 어떤 작업을 수행할 수 있나요?

복원된 데이터베이스 계정에 새 관리 ID를 할당하여 데이터베이스 계정에 계속 액세스하거나 액세스 권한을 복구합니다.

다음 단계

피드백

추가 리소스