Azure Key Vault で Azure Cosmos アカウントのカスタマー マネージド キーを構成する

適用対象: SQL API Cassandra API Gremlin API Table API MongoDB 用 Azure Cosmos DB API

Azure Cosmos アカウントに格納されているデータは、Microsoft が管理するキー (サービス マネージド キー) を使用して自動的かつシームレスに暗号化されます。 自分で管理するキー (カスタマー マネージド キーまたは CMK) を使用する暗号化の 2 番目のレイヤーを追加することもできます。

顧客データに関する暗号化のレイヤー

カスタマー マネージド キーは Azure Key Vault に格納し、カスタマー マネージド キーが有効になっている Azure Cosmos アカウントごとにキーを指定する必要があります。 このキーは、そのアカウントに格納されているすべてのデータを暗号化するために使用されます。

Note

現在、カスタマー マネージド キーは新しい Azure Cosmos アカウントでのみ使用できます。 これらは、アカウントの作成時に構成します。

Azure サブスクリプション用の Azure Cosmos DB リソース プロバイダーを登録する

  1. Azure portal にサインインし、お使いの Azure サブスクリプションに移動して [設定] タブの [リソース プロバイダー] を選択します。

    左側のメニューの [リソース プロバイダー] エントリ

  2. Microsoft.DocumentDB リソース プロバイダーを検索します。 そのリソース プロバイダーが既に登録済みとしてマークされているどうかを確認します。 そうでない場合は、リソース プロバイダーを選択して [登録] を選択します。

    Microsoft.DocumentDB リソース プロバイダーの登録

Azure Key Vault インスタンスを構成する

重要

Azure Key Vault インスタンスは、パブリック ネットワーク アクセス経由でアクセス可能にするか、信頼された Microsoft サービスがそのファイアウォールをバイパスすることを許可する必要があります。 プライベート エンドポイント経由でしかアクセスできないインスタンスは、カスタマー マネージド キーのホスティングに使用できません。

Azure Cosmos DB でカスタマー マネージド キーを使用するには、暗号化キーをホストするために使用しようとしている Azure Key Vault インスタンスで 2 つのプロパティを設定する必要があります。論理的な削除消去保護です。

新しい Azure Key Vault インスタンスを作成する場合は、作成時にこれらのプロパティを有効にします。

新しい Azure Key Vault インスタンスの論理的な削除と消去保護を有効にする

既存の Azure Key Vault インスタンスを使用している場合は、Azure portal の [プロパティ] セクションを見て、これらのプロパティが有効であることを確認できます。 これらのプロパティのいずれかが有効になっていない場合は、次のいずれかの記事の「消去保護を有効にする」と「論理的な削除を有効にする」のセクションを参照してください。

Azure Key Vault インスタンスにアクセス ポリシーを追加する

  1. Azure portal から、暗号化キーをホストするために使用しようとしている Azure Key Vault インスタンスに移動します。 左側のメニューの [アクセス ポリシー] を選択します。

    左側のメニューの [アクセス ポリシー]

  2. [+ アクセス ポリシーの追加] を選択します。

  3. [キーのアクセス許可] ドロップダウン メニューで、 [取得][キーの折り返しを解除] 、および [キーを折り返す] アクセス許可を選択します。

    適切なアクセス許可の選択

  4. [プリンシパルの選択] で、 [選択されていません] を選択します。

  5. Azure Cosmos DB のプリンシパルを検索して、それを選びます (見つけやすいよう、すべての Azure リージョンでアプリケーション ID a232010e-820c-4083-83bb-3ace5fc29d0b を使って検索することもできます。ただし、Azure Government リージョンだけはアプリケーション ID 57506a73-e302-42a9-b869-6f12d9ec29e9 を使います)。 Azure Cosmos DB プリンシパルが一覧にない場合は、この記事のリソース プロバイダーの登録に関するセクションの説明に従って Microsoft.DocumentDB リソース プロバイダーを再登録することが必要になる場合があります。

    Note

    これにより、Azure Key Vault アクセス ポリシーに Azure Cosmos DB のファーストパーティ ID が登録されます。 このファーストパーティ ID を Azure Cosmos DB アカウントのマネージド ID に置き換えるには、「Azure Key Vault アクセス ポリシーでのマネージド ID の使用」を参照してください。

  6. 下部にある [選択] を選択します。

    Azure Cosmos DB プリンシパルを選択する

  7. [追加] を選択して新しいアクセス ポリシーを追加します。

  8. すべての変更を保存するには、Key Vault インスタンスで [保存] を選択します。

Azure Key Vault でキーを生成する

  1. Azure portal から、暗号化キーをホストするために使用しようとしている Azure Key Vault インスタンスに移動します。 次に、左側のメニューの [キー] を選択します。

    左側のメニューの [キー] エントリ

  2. [生成/インポート] を選択し、新しいキーに名前を付け、RSA キー サイズを選択します。 最高のセキュリティを得るには、最小で 3072 をお勧めします。 次に、 [作成] を選択します。

    新しいキーを作成する

  3. キーが作成されたら、新しく作成されたキーを選択し、次にその現在のバージョンを選択します。

  4. 最後のスラッシュの後の部分を除き、キーの [キー識別子] をコピーします。

    キーのキー識別子のコピー

新しい Azure Cosmos アカウントを作成する

Azure ポータルの使用

Azure portal から新しい Azure Cosmos DB アカウントを作成する場合は、 [暗号化] の手順で [カスタマー マネージド キー] を選択します。 [キー URI] フィールドで、前の手順でコピーした Azure Key Vault キーの URI/キー識別子を貼り付けます。

Azure portal での CMK パラメーターの設定

Azure PowerShell の使用

PowerShell で新しい Azure Cosmos DB アカウントを作成する場合、次を実行します。

  • 前に PropertyObjectkeyVaultKeyUri プロパティでコピーした Azure Key Vault キーの URI を渡します。

  • API バージョンとして 2019-12-12 以降を使用します。

重要

アカウントがカスタマー マネージド キーで正常に作成されるようにするには、locations プロパティを明示的に設定する必要があります。

$resourceGroupName = "myResourceGroup"
$accountLocation = "West US 2"
$accountName = "mycosmosaccount"

$failoverLocations = @(
    @{ "locationName"="West US 2"; "failoverPriority"=0 }
)

$CosmosDBProperties = @{
    "databaseAccountOfferType"="Standard";
    "locations"=$failoverLocations;
    "keyVaultKeyUri" = "https://<my-vault>.vault.azure.net/keys/<my-key>";
}

New-AzResource -ResourceType "Microsoft.DocumentDb/databaseAccounts" `
    -ApiVersion "2019-12-12" -ResourceGroupName $resourceGroupName `
    -Location $accountLocation -Name $accountName -PropertyObject $CosmosDBProperties

アカウントが作成されたら、Azure Key Vault キーの URI をフェッチすることで、カスタマー マネージド キーが有効であることを確認できます。

Get-AzResource -ResourceGroupName $resourceGroupName -Name $accountName `
    -ResourceType "Microsoft.DocumentDb/databaseAccounts" `
    | Select-Object -ExpandProperty Properties `
    | Select-Object -ExpandProperty keyVaultKeyUri

Azure Resource Manager テンプレートの使用

Azure Resource Manager テンプレートを使用して新しい Azure Cosmos アカウントを作成する場合、次を実行します。

  • 前に properties オブジェクトの keyVaultKeyUri プロパティでコピーした Azure Key Vault キーの URI を渡します。

  • API バージョンとして 2019-12-12 以降を使用します。

重要

アカウントがカスタマー マネージド キーで正常に作成されるようにするには、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 スクリプトを使用してテンプレートをデプロイします。

$resourceGroupName = "myResourceGroup"
$accountName = "mycosmosaccount"
$accountLocation = "West US 2"
$keyVaultKeyUri = "https://<my-vault>.vault.azure.net/keys/<my-key>"

New-AzResourceGroupDeployment `
    -ResourceGroupName $resourceGroupName `
    -TemplateFile "deploy.json" `
    -accountName $accountName `
    -location $accountLocation `
    -keyVaultKeyUri $keyVaultKeyUri

Azure CLI の使用

Azure CLI を使用して新しい Azure Cosmos アカウントを作成する場合は、先に --key-uri パラメーターでコピーした Azure Key Vault キーの URI を渡します。

resourceGroupName='myResourceGroup'
accountName='mycosmosaccount'
keyVaultKeyUri = 'https://<my-vault>.vault.azure.net/keys/<my-key>'

az cosmosdb create \
    -n $accountName \
    -g $resourceGroupName \
    --locations regionName='West US 2' failoverPriority=0 isZoneRedundant=False \
    --key-uri $keyVaultKeyUri

アカウントが作成されたら、Azure Key Vault キーの URI をフェッチすることで、カスタマー マネージド キーが有効であることを確認できます。

az cosmosdb show \
    -n $accountName \
    -g $resourceGroupName \
    --query keyVaultKeyUri

Azure Key Vault アクセス ポリシーでのマネージド ID の使用

このアクセス ポリシーにより、Azure Cosmos DB アカウントから暗号化キーにアクセスできるようになります。 アクセス ポリシーを実装するには、特定の Azure Active Directory (AD) ID にアクセス権を付与します。 次の 2 種類の ID がサポートされています。

  • Azure Cosmos DB のファーストパーティ ID は、Azure Cosmos DB サービスへのアクセス権を付与するために使用できます。
  • Azure Cosmos DB アカウントのマネージド ID は、ご使用のアカウントへのアクセス権を明示的に付与するために使用できます。

システム割り当てマネージド ID を使用する方法

システムによって割り当てられたマネージド ID を取得できるのは、アカウントの作成後のみになります。そのため、上記で説明したように、最初にファーストパーティ ID を使用してアカウントを作成する必要があります。 その後、以下を実行します。

  1. アカウントの作成時にシステム割り当てマネージド ID が構成されなかった場合は、アカウントでシステム割り当てマネージド ID を有効にし、割り当てられた principalId をコピーします。

  2. 上記で説明したように、新しいアクセス ポリシーを Azure Key Vault アカウントに追加しますが、Azure Cosmos DB のファーストパーティ ID ではなく、前の手順でコピーした principalId を使用します。

  3. Azure Key Vault 内の暗号化キーにアクセスするときは、Azure Cosmos DB アカウントを更新して、システムによって割り当てられたマネージド ID を使用するように指定します。 2 つのオプションがあります。

    • アカウントの Azure Resource Manager テンプレートにプロパティを指定します。

      {
          "type": " Microsoft.DocumentDB/databaseAccounts",
          "properties": {
              "defaultIdentity": "SystemAssignedIdentity",
              // ...
          },
          // ...
      }
      
    • Azure CLI を使用してアカウントを更新します。

          resourceGroupName='myResourceGroup'
          accountName='mycosmosaccount'
      
          az cosmosdb update --resource-group $resourceGroupName --name $accountName --default-identity "SystemAssignedIdentity"
      
  4. その後、必要に応じて、Azure Cosmos DB のファーストパーティ ID を Azure Key Vault アクセス ポリシーから削除できます。

ユーザー割り当てマネージド ID を使用する方法

  1. 上記で説明したように、Azure Key Vault アカウントで新しいアクセス ポリシーを作成する場合は、Azure Cosmos DB のファースト パーティ ID ではなく、使用するマネージド ID の Object ID を使用します。

  2. Azure Cosmos DB アカウントを作成する場合は、ユーザー割り当てマネージド ID を有効にし、Azure Key Vault で暗号化キーにアクセスするときにこの ID を使用するように指定する必要があります。 次のオプションがあります。

    • Azure Resource Manager テンプレートの使用:

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

      resourceGroupName='myResourceGroup'
      accountName='mycosmosaccount'
      keyVaultKeyUri = 'https://<my-vault>.vault.azure.net/keys/<my-key>'
      
      az cosmosdb create \
          -n $accountName \
          -g $resourceGroupName \
          --key-uri $keyVaultKeyUri
          --assign-identity <identity-resource-id>
          --default-identity "UserAssignedIdentity=<identity-resource-id>"  
      

継続的バックアップで CMK を使用する

Azure CLI または Azure Resource Manager テンプレートを使って、継続的バックアップ アカウントを作成できます。

現在、継続的バックアップ アカウントの作成では、ユーザー割り当てマネージド ID のみがサポートされています。

Azure CLI を使用して継続的バックアップ アカウントを作成するには

resourceGroupName='myResourceGroup'
accountName='mycosmosaccount'
keyVaultKeyUri = 'https://<my-vault>.vault.azure.net/keys/<my-key>'

az cosmosdb create \
    -n $accountName \
    -g $resourceGroupName \
    --key-uri $keyVaultKeyUri \
    --locations regionName=<Location> \
    --assign-identity <identity-resource-id> \
    --default-identity "UserAssignedIdentity=<identity-resource-id>" \
    --backup-policy-type Continuous 

Azure Resource Manager テンプレートを使用して継続的バックアップ アカウントを作成するには

Azure Resource Manager テンプレートを使用して新しい Azure Cosmos アカウントを作成する場合、次を実行します。

  • 前に properties オブジェクトの keyVaultKeyUri プロパティでコピーした Azure Key Vault キーの URI を渡します。
  • API バージョンとして 2021-11-15 以降を使います。

重要

カスタマー マネージド キーでアカウントが正常に作成されるには、次の例で示すように、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>"
        // ...
    }
}

カスタマー マネージド キーと二重暗号化

カスタマー マネージド キーを使用する場合、Azure Cosmos DB アカウントに格納するデータは最終的に 2 回暗号化されます。

  • Microsoft マネージド キーを使用して実行される既定の暗号化で 1 回。
  • カスタマー マネージド キーを使用して実行される追加の暗号化で 1 回。

二重暗号化は、メインの Azure Cosmos DB トランザクション ストレージにのみ適用されます。 カスタマー マネージド キーを使用していても、機能によっては、二重暗号化が提供されない第 2 階層のストレージにデータが内部で複製されます。 これには次の機能があります。

キーの交換

Azure Cosmos アカウントで使用されるカスタマー マネージド キーのローテーションは、次の 2 つの方法で行うことができます。

  • Azure Key Vault から、現在使用されているキーの新しいバージョンを作成します。

    Azure portal の [バージョン] ページの [新しいバージョン] オプションのスクリーンショット。

  • アカウントのキー URI を更新して、現在使用されているキーを別のキーに切り替えます。 Azure portal から、Azure Cosmos アカウントに移動し、左側のメニューから [データ暗号化] を選択します。

    Azure portal の [データ暗号化] メニュー オプションのスクリーンショット。

    次に、 [キー URI] を使用する新しいキーに置き換え、 [保存] を選択します。

    Azure portal の [キー] ページの [保存] オプションのスクリーンショット。

    PowerShell で同じ結果を実現するには、次のようにします。

    $resourceGroupName = "myResourceGroup"
    $accountName = "mycosmosaccount"
    $newKeyUri = "https://<my-vault>.vault.azure.net/keys/<my-new-key>"
    
    $account = Get-AzResource -ResourceGroupName $resourceGroupName -Name $accountName `
        -ResourceType "Microsoft.DocumentDb/databaseAccounts"
    
    $account.Properties.keyVaultKeyUri = $newKeyUri
    
    $account | Set-AzResource -Force
    

前のキーまたはキー バージョンは、Azure Key Vault 監査ログに Azure Cosmos DB からそのキーまたはキー バージョンに対するアクティビティが出現しなくなった後に無効にすることができます。 キーのローテーションから 24 時間が経過すれば、以前のキーまたはキーのバージョンに対するアクティビティが実行されることはないでしょう。

エラー処理

Azure Cosmos DB でカスタマー マネージド キーによるエラーが発生した場合、Azure Cosmos DB によって、エラーの詳細が HTTP サブ状態コードと共に応答で返されます。 HTTP サブ状態コードを使用して、問題の根本原因をデバッグできます。 サポートされている HTTP サブ状態コードの一覧については、「Azure Cosmos DB の HTTP 状態コード」を参照してください。

よく寄せられる質問

カスタマー マネージド キーを有効にするために追加料金は発生しますか?

いいえ、この機能を有効にするためにかかる料金はありません。

カスタマー マネージド キーは容量計画にどのような影響がありますか?

カスタマー マネージド キーを使用する場合、データベース操作によって使用される要求ユニットは、データの暗号化と復号化を実行するために必要な追加の処理を反映して増加します。 追加の RU の使用により、プロビジョニングされた容量の使用率が若干高くなる可能性があります。 次の表を参考にしてください。

操作の種類 要求ユニットの増加
ポイント読み取り (ID による項目のフェッチ) + 5%/操作
任意の書き込み操作 + 6%/操作
インデックス付きプロパティあたり約 + 0.06 RU
クエリ、変更フィードの読み取り、または競合フィード + 15%/操作

カスタマー マネージド キーでどのようなデータが暗号化されますか?

カスタマー マネージド キーでは、次のメタデータを除き、ご自分の Azure Cosmos アカウントに格納されているすべてのデータが暗号化されます。

カスタマー マネージド キーは既存の Azure Cosmos アカウントでサポートされますか?

この機能は現在、新しいアカウントでのみ使用できます。

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 アカウントでカスタマー マネージド キーが有効かどうかを確認するにはどうすればよいですか?

Azure portal から、Azure Cosmos アカウントに移動し、左側のメニューで [データ暗号化] のエントリを探します。このエントリが存在する場合は、カスタマー マネージド キーがアカウントで有効になっています。

[データ暗号化] のメニュー エントリ

プログラムで Azure Cosmos アカウントの詳細をフェッチして、keyVaultKeyUri プロパティの存在を確認することもできます。 PowerShell で、また Azure CLI を使用してこれを行う方法については、上記を参照してください。

カスタマー マネージド キーは定期的なバックアップにどのように影響しますか?

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 は、継続的バックアップを使用するアカウントでは現在サポートされていません。

ポイントインタイム リストアが正常に実行するには、次の条件が必要です。

  • バックアップ時に使用した暗号化キーは、Azure Key Vault で使用できる必要があります。 この要件は、失効されておらず、バックアップの時点で使用していたキーのバージョンがまだ有効であることを意味します。
  • ソース アカウントでもともと使われていたユーザー割り当てマネージド ID が、Key Vault のアクセス ポリシーでまだ宣言されていることを確認する必要があります。

重要

アカウントを削除する前に暗号化キーを取り消した場合、取り消しが行われる前の最大 1 時間の間に書き込まれたデータが、アカウントのバックアップで失われる可能性があります。

暗号化キーを失効させるにはどうすればよいですか?

キーの失効は、そのキーの最新バージョンを無効にすることによって行われます。

キーのバージョンを無効にする

あるいは、Azure Key Vault インスタンスからすべてのキーを失効させるために、Azure Cosmos DB プリンシパルに付与されているアクセス ポリシーを削除することもできます。

Azure Cosmos DB プリンシパルのアクセス ポリシーの削除

カスタマー マネージド キーが失効した後、どのような操作を使用できますか?

暗号化キーが失効しているときに使用できる唯一の操作はアカウントの削除です。

次のステップ