Configure customer-managed keys for Azure AI Search encrypted data

Enabling customer‑managed keys (CMK) adds additional security on top of the default encryption at rest when using Microsoft-managed keys. When you enable CMK, you control the encryption keys used to protect your data, including the ability to:

• Rotate keys on a customer‑defined schedule
• Disable or revoke keys to block access to encrypted content (cached keys may persist for up to 60 minutes)
• Audit key usage through Azure Key Vault logging

You can create, store, and manage keys by using either:

• Azure Key Vault

• Azure Key Vault Managed HSM (Hardware Security Module). An Azure Key Vault Managed HSM is an FIPS 140-2 Level 3 validated HSM. To migrate from Azure Key Vault to HSM, rotate your keys and choose Managed HSM for storage.

This article explains how to configure CMK for additional protection of your encrypted data in Azure AI Search.

Configure CMK on Azure AI Search objects

Objects with encrypted data that can be configured with a customer-managed key (CMK) include indexes, synonym lists, indexers, data sources, vectorizers, and skillsets. Encryption is computationally expensive to decrypt so only sensitive content is encrypted.

Encryption is performed over:

• All content within indexes and synonym lists.

• Sensitive content in indexers, data sources, skillsets, and vectorizers. Sensitive content refers to connection strings, descriptions, identities, keys, and user inputs. For example, skillsets have Foundry Tools keys, and some skills accept user inputs, such as custom entities. In both cases, keys and user inputs are encrypted. Any references to external resources (such as Azure data sources or Azure OpenAI models) are also encrypted.

Adding a customer-managed key to an object must happen when the object is newly created. It is important to keep in mind:

• You cannot retroactively add CMK to an existing object. If you want to add a customer-managed key to an existing object, you must delete and recreate that object with encryption enabled.

• Once CMK is configured, encryption happens every time the service writes data, including both data at rest (long-term storage) or temporary cached data (short-term storage). For objects like data sources, indexers, and skillsets, the object definition is encrypted. For indexes, the indexed documents themselves (not just the index schema) are encrypted.

• Although you can't add encryption to an existing object, once an object is configured for encryption, you can change all parts of its encryption definition, including switching to a different key vault or HMS storage as long as the resource is in the same tenant.

• Encryption with a CMK is irreversible. You can rotate keys and change CMK configuration, but index encryption lasts for the lifetime of the index. After encryption with CMK, an index is only accessible if the search service has access to the key. If you revoke access to the key by deleting or changing role assignment, the index is unusable and the service can't be scaled until the index is deleted or access to the key is restored. If you delete or rotate keys, the most recent key is cached for up to 60 minutes.

• If you require CMK across your search service, set an enforcement policy.

• CMK enforcement by using Azure Policy and service-level CMK configuration (which is still in preview) are independent settings. You can use either or both, depending on your needs. Service-level CMK configuration applies a default key to new objects, while Azure Policy enforcement ensures that all objects comply with your encryption requirements. If you enable a CMK enforcement policy without a service‑level key, all CMK‑enabled objects must specify their own encryption key at creation time. Object creation requests that omit CMK configuration fail.

Enable service-level CMK on new objects by default (preview)

Beginning in the 2026-03-01-preview release, you have the ability to configure a customer-managed key at the service-level on the Azure AI Search service itself. This feature makes it possible to configure the key once at the service level and have it apply to all newly created objects by default. This ensures all sensitive data in your search service is protected by a key you control, without having to specify key information each time an object is created.

Enabling CMK at the service level means:

• All new objects created on your Azure AI Search service automatically use the service‑level customer‑managed key by default, so you no longer need to explicitly specify encryption key details each time you create an object.

• This feature is optional, and you can continue to configure CMK on a per‑object basis. You can also override the service‑level key for individual objects and rotate the service‑level key independently, allowing you to use different keys for different objects as needed.

You can also rotate this default key by specifying a new key, specific to the object that you are creating. The object-level key that you specify will override the default service-level key for that object.

Prerequisites

• Azure AI Search on a billable tier (Basic or higher, in any region).

• Azure Key Vault and a key vault with soft-delete and purge protection enabled. Or, Azure Key Vault Managed HSM. This resource can be in any subscription and in a different tenant. These instructions assume a single tenant. For cross-tenant configuration, see Configure customer-managed keys across different tenants.

• Ability to set up permissions for key access and to assign roles. To create keys, you must be Key Vault Crypto Officer in Azure Key Vault or Managed HSM Crypto Officer in Azure Key Vault Managed HSM.

  To assign roles, you must be subscription Owner, User Access Administrator, Role-based Access Control Administrator, or be assigned to a custom role with Microsoft.Authorization/roleAssignments/write permissions.

Step 1: Create an encryption key

Use either Azure Key Vault or Azure Key Vault Managed HSM to create a key. Azure AI Search encryption supports RSA keys of sizes 2048, 3072 and 4096. For more information about supported key types, see About keys.

We recommend reviewing these tips before you start.

Required operations are Wrap, Unwrap, Encrypt, and Decrypt.

Step 2: Create a security principal

Create a security principal that your search service uses to access to the encryption key. You can use a managed identity and role assignment, or you can register an application and have the search service provide the application ID on requests.

Use a managed identity and roles. You can use either a system-managed identity or user-managed identity. A managed identity enables your search service to authenticate through Microsoft Entra ID, without storing credentials (ApplicationID or ApplicationSecret) in code. The lifecycle of this type of managed identity is tied to the lifecycle of your search service, which can only have one system assigned managed identity. For more information about how managed identities work, see What are managed identities for Azure resources.

Step 3: Grant permissions

If you configured your search service to use a managed identity, assign roles that give it access to the encryption key.

Role-based access control is recommended over the Access Policy permission model. For more information or migration steps, start with Azure role-based access control (Azure RBAC) vs. access policies (legacy).

1. Go to your key vault in the Azure portal.

2. Select Access control (IAM) and select Add role assignment.

3. Select a role:

   • On Azure Key Vault, select Key Vault Crypto Service Encryption User.
   • On Managed HSM, select Managed HSM Crypto Service Encryption User.

4. Select managed identities, select members, and then select the managed identity of your search service. If you're testing locally, assign this role to yourself as well.

5. Select Review + Assign.

Wait a few minutes for the role assignment to become operational.

Step 4: Add encryption key information to Azure AI Search objects

When you create an encrypted object, enter the key vault URI, key name, and key version. If you're using a Microsoft Entra ID application for authentication, also enter the application ID and secret.

You can configure new search objects with a customer-managed key at the service level or at the object level. When you configure CMK at the service level, you apply the same key by default to all newly created objects in the service, unless you specify a different object-level key to override the service-level default.

Specify the customer-managed key in the object definition when you create an encrypted object. This object can be an index, indexer, data source, skillset, vectorizer, or synonym map.

To configure CMK on an object, use the Azure portal, Search Service REST APIs, or an Azure SDK.

Configure CMK at the service-level (preview)

To enable service-level CMK configuration, we recommend that you use the Search Management REST API or an Azure SDK package that has been updated to support Search Management REST API version 2026-03-01-preview or later. This feature is not yet supported in the Azure portal. Enabling CMK at the service level does not add encryption to existing objects, but it applies the same key by default to all newly-created objects in the service, unless you specify a different object-level key to override the service-level default.

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

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

{
  "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>"
      }
    }
  }
}

{
  "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>"
      }       
    }
  }
}

Step 5: Test encryption

To verify encryption is working, revoke the encryption key, query the index (it should be unusable), and then reinstate the encryption key.

Use the Azure portal for this task. Make sure you have a role assignment that grants read access to the key.

1. On the Azure Key Vault page, select Objects > Keys.

2. Select the key you created, and then select Delete.

3. On the Azure AI Search page, select Search management > Indexes.

4. Select your index and use Search Explorer to run a query. You should get an error.

5. Return to the Azure Key Vault Objects > Keys page.

6. Select Manage deleted keys.

7. Select your key, and then select Recover.

8. Return to your index in Azure AI Search and rerun the query. You should see search results. If you don't see immediate results, wait a minute and try again.

Set up a policy to enforce CMK compliance

Azure policies help to enforce organizational standards and to assess compliance at-scale. Azure AI Search has two optional built-in policies related to CMK. These policies apply to new and existing search services.

Assign a policy

1. In the Azure portal, navigate to a built-in policy and then select Assign.

   • AuditIfExists

   • Deny

   Here's an example of the AuditIfExists policy in the Azure portal:

   

2. Set the policy scope by selecting the subscription and resource group. Exclude any search services for which the policy shouldn't apply.

3. Accept or modify the default values. Select Review + create, and then select Create.

Enable CMK policy enforcement

When you assign a policy to a resource group in your subscription, it takes effect immediately. Audit policies flag non-compliant resources, but Deny policies prevent the creation and update of non-compliant search services. This section explains how to create a compliant search service or update a service to make it compliant. To bring objects into compliance, start at step one of this article.

Create a compliant search service

For new search services, create them with SearchEncryptionWithCmk set to Enabled.

Neither the Azure portal nor the command-line tools (the Azure CLI and Azure PowerShell) provide this property natively, but you can use Management REST API to provision a search service with a CMK policy definition.

### 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"
        }
      }
    }

Update an existing search service

For existing search services that are now non-compliant, patch them using Services - Update API or the Azure CLI az resource update command. Patching the services restores the ability to update search service properties.

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"
    }
...

Rotate or update encryption keys

Use the following instructions to rotate keys or to migrate from Azure Key Vault to the Hardware Security Model (HSM).

For key rotation, use the autorotation capabilities of Azure Key Vault. If you use autorotation, omit the key version in object definitions. The latest key is used, rather than a specific version.

When you change a key or its version, update any object that uses the key to use the new values before you delete the old values. Otherwise, the object becomes unusable because it can't be decrypted.

If you configured CMK at the service level, rotating the service-level key applies to newly created objects going forward. Objects that already inherited the previous service-level key automatically pick up the new key, so you don't need to update them. However, if you had any objects that were configured with an object-level key that you also want to rotate, then you need to update those objects to use the new key.

Keys are cached for 60 minutes. Remember this when testing and rotating keys.

1. Determine the key used by an index or synonym map.

2. Create a new key in key vault, but leave the original key available. In this step, you can switch from key vault to HSM.

3. Update the encryptionKey properties on an index or synonym map to use the new values. Only objects that were originally created with this property can be updated to use a different value.

4. Disable or delete the previous key in the key vault. Monitor key access to verify the new key is being used.

For performance reasons, the search service caches the key for up to several hours. If you disable or delete the key without providing a new one, queries continue to work on a temporary basis until the cache expires. However, once the search service can no longer decrypt content, you get this message: "Access forbidden. The query key used might have been revoked - please retry."

Key Vault tips

• If you're new to Azure Key Vault, review this quickstart to learn about basic tasks: Set and retrieve a secret from Azure Key Vault using PowerShell.

• Use as many key vaults as you need. Managed keys can be in different key vaults. A search service can have multiple encrypted objects, each one encrypted with a different customer-managed encryption key, stored in different key vaults.

• Use the same Azure tenant so that you can retrieve your managed key through role assignments and by connecting through a system or user-managed identity. For more information about creating a tenant, see Set up a new tenant.

• Enable purge protection and soft-delete on a key vault. Due to the nature of encryption with customer-managed keys, no one can retrieve your data if your Azure Key Vault key is deleted. To prevent data loss caused by accidental Key Vault key deletions, soft-delete and purge protection must be enabled on the key vault. Soft-delete is enabled by default, so you'll only encounter issues if you purposely disable it. Purge protection isn't enabled by default, but it's required for encryption with a CMK in Azure AI Search.

• Enable logging on the key vault so that you can monitor key usage.

• Enable autorotation of keys or follow strict procedures during routine rotation of key vault keys and application secrets and registration. Always update all encrypted content to use new secrets and keys before deleting the old ones. If you miss this step, your content can't be decrypted.

Work with encrypted content

Using CMK, you might notice latency for both indexing and queries due to the extra encrypt/decrypt work. Azure AI Search doesn't log encryption activity, but you can monitor key access through key vault logging.

We recommend that you enable logging as part of key vault configuration.

1. Create a log analytics workspace.

2. Add a diagnostic setting in key vault that uses the workspace for data retention.

3. Select audit or allLogs for the category, give the diagnostic setting a name, and then save it.

Next steps

If you're unfamiliar with Azure security architecture, review the Azure Security documentation, and in particular, this article: