Azure AI 검색 암호화된 데이터에 대한 고객 관리형 키 구성

Azure Portal, Azure CLI 또는 Azure PowerShell 사용하여 키 자격 증명 모음을 만들 수 있습니다.

1. Azure Portal에서 키 자격 증명 모음으로 이동합니다.

2. 왼쪽에서 개체>키를 선택한 다음 생성/가져오기를 선택합니다.

3. 키 만들기 창의 옵션 목록에서 생성을 선택하여 새 키를 만듭니다.

4. 키의 이름을 입력하고 다른 키 속성에 대한 기본값을 적용합니다.

5. 필요에 따라 자동 회전을 사용하도록 키 회전 정책을 설정합니다.

6. 만들기를 선택하여 배포를 시작합니다.

7. 키를 만든 후 키 식별자를 가져옵니다. 키를 선택하고 현재 버전을 선택한 다음 키 식별자를 복사합니다. 키 값 Uri, 키이름 및 키 버전으로 구성됩니다. Azure AI 검색 암호화된 인덱스 정의에는 식별자가 필요합니다. 필수 작업은 래핑, 래핑 해제, 암호화 및 암호 해독입니다.

   

Azure 포털, Azure CLI 또는 Azure PowerShell 관리형 HSM을 만들고 활성화할 수 있습니다.

키를 생성하거나 가져오려면 Azure CLI 사용합니다.

검색 서비스에 대해 시스템 할당 관리 ID를 사용하도록 설정합니다. 두 번의 클릭 작업인 사용 및 저장입니다.

Azure 포털 또는 Search Management REST API를 사용하여 사용자 할당 관리 ID를 만들고 검색 서비스에 ID를 할당할 수 있습니다. 자세한 내용은 사용자 할당 관리 ID 만들기를 참조하세요.

암호화 키에 대한 검색 서비스 액세스에 역할 할당을 사용할 수 없는 경우 다음 지침을 따릅니다.

1. Azure 포털 구독에 대한 Microsoft Entra 리소스를 찾습니다.

2. 왼쪽의 Manage 아래에서 앱 등록 선택한 다음, 새 등록 선택합니다.

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 구문을 삽입합니다. 이 속성은 이름 및 설명과 동일한 수준의 첫 번째 수준 속성입니다. 동일한 자격 증명 모음, 키 및 버전을 사용하는 경우 동일한 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>"
     }
   }
   

   두 번째 예제에는 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을 실행하여 암호화 키가 있는지 확인합니다.

   • GET 인덱스
   • 동의어 맵 가져오기
   • GET 인덱서
   • 데이터 원본 가져오기
   • GET Skillset

4. 암호화된 인덱스 쿼리와 같은 작업을 수행하여 개체가 작동하는지 확인합니다.

검색 서비스에서 암호화된 개체를 만든 후에는 해당 형식의 다른 개체와 마찬가지로 사용할 수 있습니다. 암호화는 사용자 및 개발자에게 투명합니다.

이러한 키 자격 증명 모음 세부 정보는 비밀로 간주되지 않으며 Azure Portal의 관련 Azure Key Vault 페이지로 이동하여 쉽게 검색할 수 있습니다.

검색 개체의 CMK 구성은 Azure SDK 패키지에서 지원됩니다. 여기에는 Azure SDK for .NET, Azure SDK for Java, Azure SDK for JavaScript 및 Azure SDK for Python가 포함됩니다.

다음 예제에서는 개체 정의에서 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를 사용하여 암호화를 구성하려면 Services - Create Or Update with PATCH 를 사용하여 기존 검색 서비스를 업데이트하거나 PUT 새 검색 서비스를 만듭니다. 서비스 수준 구성을 지원하려면 API 버전이 2026-03-01-preview 이상이어야 합니다.

이 예제에서는 {{subscription-id}}을(를) 구독 ID로, {{resource-group}}을(를) 리소스 그룹 이름으로, {{search-service}}을(를) 검색 서비스 이름으로, {{token}}을(를) 액세스 토큰으로 각각 대체해야 합니다. 키 정의는 개체 수준 CMK와 동일한 스키마를 사용하며 세 가지 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-resourcemanager-search 변경 로그
• JavaScript: @azure/arm-search 변경 로그
• Python: azure-mgmt-search 변경 로그 (changelog)

현재 Azure 포털은 서비스 수준 암호화를 지원하지 않습니다. REST API를 직접 사용합니다.

데이터 평면 API 버전 2026-05-01-preview 이후에서는 encryptionKey.isServiceLevelKey를 검사하기 위해 GET 객체 호출을 사용합니다.

아래 코드 조각은 예제입니다. 사용 사례와 관련된 값으로 업데이트해야 합니다.

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서비스 수준 키를 상속하며 명시적 개체 수준 재정의가 없습니다.

특정 개체의 수명 주기 결합을 해제하려면, 명시적인 object-level key를 설정하고 개체를 업데이트하는 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 상속으로 전환하려면 업데이트 요청으로 설정합니다 isServiceLevelKeytrue .

데이터 평면 API 버전 2026-05-01-preview 이상에서는 요청 유효성 검사가 개체에 encryptionKey 적용됩니다. encryptionKey를 제공하는 경우, keyVaultUri의 존재 여부나 값과 관계없이 keyVaultKeyName 및 isServiceLevelKey는 필수 문자열 필드입니다. 이 유효성 검사는 키 존재가 아닌 필드의 현재 상태를 확인합니다. 자리 표시자 문자열 값은 이 스키마 유효성 검사를 충족하며 필수 필드가 누락되면 HTTP 400이 발생합니다.

이 경우 isServiceLevelKeytrue서비스는 구성된 서비스 수준 키를 개체에 적용합니다. 또는 동일한 요청에서 제공하는 keyVaultUrikeyVaultKeyNamekeyVaultKeyVersion 경우 서비스는 해당 작업의 키 선택에 대해 해당 값을 무시합니다.

명확성과 유지 관리를 위해 요청에서 현재 서비스 수준 키 값을 제공하고 개체에 대한 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-resourcemanager-search 변경 로그
• JavaScript: @azure/arm-search 변경 로그
• Python: azure-mgmt-search 변경 로그 (changelog)

이 예제는 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가 암호화되지 않은 기존 개체가 있음을 의미합니다. 준수를 달성하려면 암호화 키를 지정하여 각 개체를 다시 만듭니다.