Azure AI 検索 の暗号化されたデータにカスタマー管理キーを構成する

Azure ポータル、Azure CLI、または Azure PowerShell を使用してキー コンテナーを作成できます。

1. Azure ポータルでキーボールトに移動します。

2. 左側の [オブジェクト]>[キー] を選択し、[生成/インポート] を選択します。

3. [キーの作成] ペインの [オプション] の一覧から [生成] を選択して新しいキーを作成します。

4. キーの [名前] を入力し、その他のキー プロパティの既定値をそのまま使用します。

5. 必要に応じて、自動ローテーションを有効にするようにキー ローテーション ポリシーを設定します。

6. [作成] を選択してデプロイを開始します。

7. キーが作成されたら、そのキー識別子を取得します。 キーを選択し、現在のバージョンを選択し、キー識別子をコピーします。 これは、キー値の URI、キー名、キー バージョンで構成されます。 Azure AI 検索で暗号化されたインデックスを定義するには、識別子が必要です。 必要な操作は Wrap、Unwrap、Encrypt、Decrypt であることを思い出す。

   

managed HSM は、Azure ポータル、Azure CLI、または Azure PowerShell で作成してアクティブ化できます。

キーを生成またはインポートするには、Azure CLIを使用します。

検索サービスのシステム割り当てマネージド ID を有効にします。 これは 2 クリック操作です。有効にして保存します。

Azure ポータルまたは Search Management REST API を使用して、ユーザー割り当てマネージド ID を作成し、その ID を検索サービスに割り当てることができます。 詳細については、「ユーザー割り当てマネージド ID を作成する」を参照してください。

暗号化キーへの検索サービス アクセスにロールの割り当てを使用できない場合は、次の手順に従います。

1. Azure ポータルで、サブスクリプションのMicrosoft Entra リソースを見つけます。

2. 左側の Manage で アプリの登録 を選択し、 New registration を選択します。

3. 登録の名前 (検索アプリケーション名に似た名前など) を入力します。 [登録] を選択します。

4. アプリの登録が作成されたら、アプリケーション ID をコピーします。 この文字列をアプリケーションに指定します。

   DotNetHowToEncryptionUsingCMK をステップ実行する場合は、この値を appsettings.json ファイルに貼り付けます。

   

5. 次に、 証明書とシークレットを選択します。

6. 新しいクライアント シークレット を選択します。 シークレットの表示名を入力し、[ 追加] を選択します。

7. アプリケーション シークレットをコピーします。 サンプルを順を追って実行している場合は、この値を appsettings.json ファイルに貼り付けます。

   

Azure ポータルで新しいオブジェクトを作成するときに、キー コンテナーで定義済みのカスタマー マネージド キーを指定できます。 Azure ポータルでは、次の CMK を使用して暗号化を有効にすることができます。

• インデックス
• データ ソース
• インデクサー

Azure ポータルを使用するには、キー コンテナーとキーが存在する必要があり、キーへの承認されたアクセスのために前の手順を完了する必要があります。

Azure ポータルでは、スキルセットは JSON ビューで定義されます。 REST API の例に示されている JSON を使用して、スキルセットに対するカスタマー マネージド キーを指定します。

1. Azure ポータルで検索サービスに移動します。

2. [ 検索の管理] で、[ インデックス]、[ インデクサー]、または [データ ソース] を選択します。

3. 新しいオブジェクトを追加します。 オブジェクト定義で、Microsoft マネージド暗号化 を選択します。

4. カスタマー マネージド キーを選択し、サブスクリプション、コンテナー、キー、およびバージョンを選択します。

1. 作成の API を呼び出して encryptionKey プロパティを指定します。

   • インデックスの作成
   • シノニム マップの作成
   • インデクサーの作成
   • データ ソースの作成
   • スキルセットを作成する

2. オブジェクト定義に encryptionKey コンストラクトを挿入します。 このプロパティは、名前および説明と同じレベルにある第 1 レベルのプロパティです。 同じコンテナー、キー、バージョンを使用している場合は、同じ encryptionKey コンストラクトを各オブジェクト定義に貼り付けることができます。

   キー識別子が https://contoso-keyvault.vault.azure.net/keys/contoso-cmk/aaaaaaaa-0b0b-1c1c-2d2d-333333333333されている場合、URI は https://contoso-keyvault.vault.azure.netされ、キー名は contoso-cmkされ、バージョンは aaaaaaaa-0b0b-1c1c-2d2d-333333333333。

   {
     "encryptionKey": {
       "keyVaultUri": "<YOUR-KEY-VAULT-URI>",
       "keyVaultKeyName": "<YOUR-ENCRYPTION-KEY-NAME>",
       "keyVaultKeyVersion": "<YOUR-ENCRYPTION-KEY-VERSION>",
       "identity" : { 
           "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
           "userAssignedIdentity" : "/subscriptions/<your-subscription-ID>/resourceGroups/<your-resource-group-name>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<your-managed-identity-name>"
       }
     }
   }
   

   最初の例は、マネージド ID を使用して接続する検索サービスの encryptionKey を示しています。

   {
     "encryptionKey": {
       "keyVaultUri": "<YOUR-KEY-VAULT-URI>",
       "keyVaultKeyName": "<YOUR-ENCRYPTION-KEY-NAME>",
       "keyVaultKeyVersion": "<YOUR-ENCRYPTION-KEY-VERSION>"
     }
   }
   

   2 番目の例には、Microsoft Entra IDにアプリケーションを登録した場合に必要な accessCredentials が含まれています。

   {
     "encryptionKey": {
       "keyVaultUri": "<YOUR-KEY-VAULT-URI>",
       "keyVaultKeyName": "<YOUR-ENCRYPTION-KEY-NAME>",
       "keyVaultKeyVersion": "<YOUR-ENCRYPTION-KEY-VERSION>",
       "accessCredentials": {
         "applicationId": "<YOUR-APPLICATION-ID>",
         "applicationSecret": "<YOUR-APPLICATION-SECRET>"
       }
     }
   }
   

3. オブジェクトに対して GET を発行して、暗号化キーが存在することを確認します。

   • インデックスの取得
   • シノニム マップの取得
   • インデクサーの取得
   • データ ソースの取得
   • スキルセットの取得

4. 暗号化されたインデックスのクエリなどのタスクを実行して、オブジェクトが動作していることを確認します。

検索サービスで暗号化されたオブジェクトを作成した後は、その種類の他のオブジェクトと同様に使用できます。 暗号化は、ユーザーと開発者に対して透過的です。

これらのキーボールトの詳細はいずれも秘密とは見なされておらず、Azureポータルで関連するAzure Key Vaultページを参照することで簡単に取得できます。

検索オブジェクトに対する CMK の構成は、Azure SDK for .NET、Azure SDK for Java、Azure SDK for JavaScript、および Azure SDK for Python を含む Azure SDK パッケージでサポートされています。

次の例では、オブジェクト定義内ののencryptionKey表現を示します。 インデックス、データ ソース、スキルセット、インデクサー、シノニム マップにも同じ定義が適用されます。 検索サービスとキー コンテナーでこの例を試すには、azure-search-python-samples からノートブックをダウンロードします。

1. いくつかのパッケージをインストールします。

   ! pip install python-dotenv
   ! pip install azure-core
   ! pip install azure-search-documents==11.5.1
   ! pip install azure-identity
   

2. 暗号化キーを持つインデックスを作成します。

   from azure.search.documents.indexes import SearchIndexClient
   from azure.search.documents.indexes.models import (
     SimpleField,
     SearchFieldDataType,
     SearchableField,
     SearchIndex,
     SearchResourceEncryptionKey,
   )
   from azure.identity import DefaultAzureCredential
   
   endpoint = "<PUT YOUR AZURE SEARCH SERVICE ENDPOINT HERE>"
   credential = DefaultAzureCredential()
   
   index_name = "test-cmk-index"
   index_client = SearchIndexClient(endpoint=AZURE_SEARCH_SERVICE, credential=credential)
   fields = [
     SimpleField(name="Id", type=SearchFieldDataType.String, key=True),
     SearchableField(name="Description", type=SearchFieldDataType.String),
   ]
   
   encryption_key = SearchResourceEncryptionKey()
   encryption_key.vault_uri = "<PUT YOUR KEY VAULT URI HERE>"
   encryption_key.key_name = "<PUT YOUR KEY VAULT KEY NAME HERE>"
   encryption_key.key_version = "<PUT YOUR ALPHANUMERIC KEY VERSION HERE>"
   
   index = SearchIndex(name=index_name, fields=fields, encryption_key=encryption_key)
   result = index_client.create_or_update_index(index)
   print(f"{result.name} created")
   

3. 暗号化キーの構成が存在することを確認するインデックス定義を取得します。

   index_name = "test-cmk-index"
   index_client = SearchIndexClient(endpoint=AZURE_SEARCH_SERVICE, credential=credential)  
   
   result = index_client.get_index(index_name)  
   print(f"{result}")  
   

4. インデックスにいくつかのドキュメントをロードします。 すべてのフィールド コンテンツは機密性が高いと見なされ、カスタマー マネージド キーを使用してディスク上で暗号化されます。

   from azure.search.documents import SearchClient
   
   # Create a documents payload
   documents = [
       {
       "@search.action": "upload",
       "Id": "1",
       "Description": "The hotel is ideally located on the main commercial artery of the city in the heart of New York. A few minutes away is Time's Square and the historic centre of the city, as well as other places of interest that make New York one of America's most attractive and cosmopolitan cities."
       },
       {
       "@search.action": "upload",
       "Id": "2",
       "Description": "The hotel is situated in a  nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts."
       },
       {
       "@search.action": "upload",
       "Id": "3",
       "Description": "The hotel stands out for its gastronomic excellence under the management of William Dough, who advises on and oversees all of the Hotel's restaurant services."
       },
       {
       "@search.action": "upload",
       "Id": "4",
       "Description": "The hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Palace is part of a lovingly restored 1800 palace."
       }
   ]
   
   search_client = SearchClient(endpoint=AZURE_SEARCH_SERVICE, index_name=index_name, credential=credential)
   try:
       result = search_client.upload_documents(documents=documents)
       print("Upload of new document succeeded: {}".format(result[0].succeeded))
   except Exception as ex:
       print (ex)
   
       index_client = SearchClient(endpoint=AZURE_SEARCH_SERVICE, credential=credential)
   

5. クエリを実行して、インデックスが動作することを確認します。

   from azure.search.documents import SearchClient
   
   query = "historic"  
   
   search_client = SearchClient(endpoint=AZURE_SEARCH_SERVICE, credential=credential, index_name=index_name)
   
   results = search_client.search(  
       query_type='simple',
       search_text=query, 
       select=["Id", "Description"],
       include_total_count=True
       )
   
   for result in results:  
       print(f"Score: {result['@search.score']}")
       print(f"Id: {result['Id']}")
       print(f"Description: {result['Description']}")
   

   クエリからの出力では、次の例のような結果が生成されます。

   Score: 0.6130029
   Id: 4
   Description: The hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Palace is part of a lovingly restored 1800 palace.
   Score: 0.26286605
   Id: 1
   Description: The hotel is ideally located on the main commercial artery of the city in the heart of New York. A few minutes away is Time's Square and the historic centre of the city, as well as other places of interest that make New York one of America's most attractive and cosmopolitan cities.
   

   暗号化されたコンテンツはデータの更新またはクエリの前に復号化されるため、暗号化の視覚的証拠は表示されません。 暗号化が機能していることを確認するには、リソース ログを確認します。

現在、Azure ポータルではサービス レベルの暗号化はサポートされていません。 REST API を直接使用します。

検索サービスのサービス レベルで CMK を使用して暗号化を構成するには、を使用して既存の検索サービスを更新するか、PATCHを使用して新しい検索サービスを作成します。 サービス レベルの構成をサポートするには、API バージョンが 2026-03-01-preview 以降である必要があります。

この例では、 {{subscription-id}}、 {{resource-group}}、 {{search-service}}、 {{token}} をそれぞれサブスクリプション ID、リソース グループ名、検索サービス名、アクセス トークンに置き換えてください。 キー定義ではオブジェクト レベルの CMK と同じスキーマが使用され、3 つの ID オプション (システム割り当てマネージド ID、ユーザー割り当てマネージド ID、または登録済みアプリケーション) がすべてサポートされます。

PATCH https://management.azure.com/subscriptions/{{subscription-id}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2026-03-01-preview
Authorization: Bearer {{token}}
Content-Type: application/json

さまざまな ID の種類のサービス レベルで serviceLevelEncryptionKey コンストラクトを挿入する方法については、次の例を参照してください。

システム割り当てマネージド ID の使用例:

{
  "encryptionWithCmk": {
    "serviceLevelEncryptionKey": {
      "keyVaultUri": "<YOUR-KEY-VAULT-URI>",
      "keyVaultKeyName": "<YOUR-ENCRYPTION-KEY-NAME>",
      "keyVaultKeyVersion": "<YOUR-ENCRYPTION-KEY-VERSION>"
    }
  }
}

ユーザーマネージド ID の使用例:

{
  "encryptionWithCmk": {
    "serviceLevelEncryptionKey": {
      "keyVaultUri": "<YOUR-KEY-VAULT-URI>",
      "keyVaultKeyName": "<YOUR-ENCRYPTION-KEY-NAME>",
      "keyVaultKeyVersion": "<YOUR-ENCRYPTION-KEY-VERSION>",
      "identity": {
        "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
        "userAssignedIdentity": "/subscriptions/<your-subscription-ID>/resourceGroups/<your-resource-group-name>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<your-managed-identity-name>"
      }
    }
  }
}

アプリケーション ID の使用例:

{
  "encryptionWithCmk": {
    "serviceLevelEncryptionKey": {
          "keyVaultUri": "<YOUR-KEY-VAULT-URI>",
          "keyVaultKeyName": "<YOUR-ENCRYPTION-KEY-NAME>",
          "keyVaultKeyVersion": "<YOUR-ENCRYPTION-KEY-VERSION>",
          "accessCredentials": {
                  "applicationId": "<YOUR-APPLICATION-ID>",
                  "applicationSecret": "<YOUR-APPLICATION-SECRET>"
      }       
    }
  }
}

サービス レベル CMK の構成は、Search Management REST API バージョン 2026-03-01-preview 以降を対象とするAzure SDK パッケージでサポートされています。 サポートを確認するには、パッケージの変更ログを確認します。

• .NET: Azure.ResourceManager.Search 変更ログ
• Java: Azure リソース マネージャー検索の変更履歴
• JavaScript: @azure/arm-search の変更ログ
• Python: azure-mgmt-search 変更履歴

現在、Azure ポータルではサービス レベルの暗号化はサポートされていません。 REST API を直接使用します。

データ プレーン API バージョン 2026-05-01-preview 以降では、オブジェクト GET 呼び出しを使用して encryptionKey.isServiceLevelKeyを検査します。

次のコード スニペットは例です。 ユース ケースに固有の値で更新する必要があります。

GET https://{{search-service}}.search.windows.net/indexes/{{index-name}}?api-version=2026-08-01-preview
api-key: {{admin-api-key}}

{
  "name": "hotels-cmk",
  "fields": [
    {
      "name": "id",
      "type": "Edm.String",
      "key": true,
      "searchable": false,
      "retrievable": true
    }
  ],
  "encryptionKey": {
    "keyVaultUri": "<YOUR-KEY-VAULT-URI>",
    "keyVaultKeyName": "<YOUR-ENCRYPTION-KEY-NAME>",
    "keyVaultKeyVersion": "<YOUR-ENCRYPTION-KEY-VERSION>",
    "isServiceLevelKey": true
  }
}

isServiceLevelKeyがtrueされると、オブジェクトはサービス レベル のキーを継承し、明示的なオブジェクト レベルのオーバーライドはありません。

特定のオブジェクトのライフサイクルを切り離すには、明示的なオブジェクト レベルのキーを設定し、オブジェクトを更新するisServiceLevelKey要求でfalseをPUTに設定します。

PUT https://{{search-service}}.search.windows.net/indexes/{{index-name}}?api-version=2026-08-01-preview
api-key: {{admin-api-key}}
Content-Type: application/json

{
  "name": "regulated-index",
  "fields": [
    {
      "name": "id",
      "type": "Edm.String",
      "key": true,
      "searchable": false,
      "retrievable": true
    }
  ],
  "encryptionKey": {
    "keyVaultUri": "<YOUR-KEY-VAULT-URI>",
    "keyVaultKeyName": "<YOUR-ENCRYPTION-KEY-NAME>",
    "keyVaultKeyVersion": "<YOUR-ENCRYPTION-KEY-VERSION>",
    "isServiceLevelKey": false
  }
}

このオーバーライドにより、オブジェクト レベルのキー ライフサイクルはサービス レベルの既定値から切り離されます。 他のオブジェクトで使用されるサービス レベル キーを変更することなく、オブジェクト レベルのキーを個別に回転させることができます。

サービスレベルの CMK を有効にすると、作成要求では encryptionKey を省略でき、オブジェクトは既定でサービスレベルのキーを継承します。 既存のオブジェクトを明示的なオブジェクト レベルのキーからサービス レベルの CMK 継承に切り替えるには、更新要求で isServiceLevelKey を true に設定します。

データ プレーン API バージョン 2026-05-01-preview 以降では、要求の検証が encryptionKey オブジェクトに適用されます。 encryptionKeyを指定する場合、keyVaultUriとkeyVaultKeyNameは、isServiceLevelKeyが存在するか、どのような値を持っているかに関係なく、必須の文字列フィールドです。 この検証では、キーの存在ではなく、フィールドの存在がチェックされます。 プレースホルダー文字列の値はこのスキーマ検証を満たし、必須フィールドが見つからないと HTTP 400 になります。

isServiceLevelKeyがtrueされると、構成されたサービス レベル キーがオブジェクトに適用されます。 同じ要求で keyVaultUri、 keyVaultKeyName、または keyVaultKeyVersion を指定した場合、サービスはその操作でのキー選択の値を無視します。

わかりやすく、保守容易にするために、要求に現在のサービス レベルのキー値を指定し、オブジェクトに対する GET 操作を使用して有効なキーを確認します。

PUT https://{{search-service}}.search.windows.net/indexes/{{index-name}}?api-version=2026-08-01-preview
api-key: {{admin-api-key}}
Content-Type: application/json

{
  "name": "regulated-index",
  "fields": [
    {
      "name": "id",
      "type": "Edm.String",
      "key": true,
      "searchable": false,
      "retrievable": true
    }
  ],
  "encryptionKey": {
    "isServiceLevelKey": true,
    "keyVaultUri": "<SERVICE-LEVEL-KEY-VAULT-URI>",
    "keyVaultKeyName": "<SERVICE-LEVEL-KEY-NAME>",
    "keyVaultKeyVersion": "<SERVICE-LEVEL-KEY-VERSION>"
  }
}

この更新後、検索オブジェクトはサービス レベルのキーを継承します。 有効なキーを確認するには、GET 要求を発行し、 isServiceLevelKey が trueされていることを確認します。

オブジェクト レベルのキーを設定するには、オブジェクト レベルのキー値を encryptionKey 指定し、 isServiceLevelKey を false に設定するか、 isServiceLevelKeyを省略します。 isServiceLevelKeyがtrueされている場合、要求はオブジェクトをオブジェクト レベルのキーに切り替えません。 更新要求で encryptionKey を省略すると、現在の暗号化キーの構成が保持されます。

サービス レベル CMK の構成は、Search Management REST API バージョン 2026-03-01-preview 以降を対象とするAzure SDK パッケージでサポートされています。 サポートを確認するには、パッケージの変更ログを確認します。

• .NET: Azure.ResourceManager.Search 変更ログ
• Java: Azure リソース マネージャー検索の変更履歴
• JavaScript: @azure/arm-search の変更ログ
• Python: azure-mgmt-search 変更履歴

この例は、 REST API を使用してAzure AI 検索 サービスを管理します、SearchEncryptionWithCmk プロパティを含むように変更されています。

### Create a search service (provide an existing resource group)
@resource-group = my-rg
@search-service-name = my-search
PUT https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2025-05-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

    {
        "location": "North Central US",
        "sku": {
            "name": "basic"
        },
        "properties": {
            "replicaCount": 1,
            "partitionCount": 1,
            "hostingMode": "default",
            "encryptionWithCmk": {
                "enforcement": "Enabled"
        }
      }
    }

PATCH https://management.azure.com/subscriptions/<your-subscription-Id>/resourceGroups/<your-resource-group-name>/providers/Microsoft.Search/searchServices/<your-search-service-name>?api-version=2025-05-01

{
  "properties": {
      "encryptionWithCmk": {
          "enforcement": "Enabled"
      }
  }
}

検索サービスとリソース グループの有効な値に置き換えて、次のコマンドを実行します。

az resource update --name SEARCH-SERVICE-PLACEHOLDER --resource-group RESOURCE-GROUP-PLACEHOLDER --resource-type searchServices --namespace Microsoft.Search --set properties.encryptionWithCmk.enforcement=Enabled

応答には、次のステートメントを含める必要があります。

"encryptionWithCmk": {
      "encryptionComplianceStatus": "NonCompliant",
      "enforcement": "Enabled"
    }
...

"非準拠" とは、検索サービスに CMK 暗号化されていない既存のオブジェクトがあることを意味します。 コンプライアンスを実現するには、暗号化キーを指定して各オブジェクトを再作成します。