Configurar chaves gerenciadas pelo cliente em diferentes locatários

Este artigo descreve um cenário entre locatários em que um provedor de serviços hospeda Pesquisa de IA do Azure  em seu próprio locatário e habilita criptografia CMK (chave gerenciada por usuário) usando um aplicativo de Microsoft Entra multilocatário.

Nessa configuração, o cliente usa Azure Key Vault em seu próprio locatário para gerenciar sua chave de criptografia. O provedor de serviços não tem acesso a essa chave.

Pré-requisitos

• Tenant A: um locatário e as permissões necessárias para criar o serviço Pesquisa de IA do Azure  e objetos associados (índices, listas de sinônimos, indexadores, fontes de dados, vetorizadores, conjuntos de habilidades). O suporte a CMK (chaves gerenciadas pelo cliente) requer a camada de preço Basic ou superior.

• Configure o serviço de pesquisa para acesso baseado em função (recomendado para segurança aprimorada, não necessário).

• Tenant B: um locatário de cliente separado com um Azure Key Vault e as permissões necessárias nesse locatário:

  • Colaborador do Key Vault: Essa função é necessária se você precisar criar um novo cofre de chaves.
  • Permissão para registrar aplicativos no Microsoft Entra ID: Para instalar o aplicativo multilocatário configurado pelo provedor de serviços para CMK entre locatários, você deve ter permissão para criar registros de aplicativos no Microsoft Entra ID. Isso normalmente requer a função de Desenvolvedor de Aplicativos ou uma função administrativa mais alta, como Administrador de Aplicativos ou Administrador Global.
  • Key Vault Crypto Officer: essa função é necessária para adicionar uma nova chave ao key vault.
  • Usuário do Serviço de Criptografia do Key Vault: essa função deve ser atribuída à entidade de serviço criada para o aplicativo multilocatário instalado, a fim de conceder à entidade de serviço acesso à chave gerenciada pelo cliente no cofre de chaves. Você deve ter permissão de Administrador de Acesso do Usuário para fazer isso. Você pode exibir o GUID da entidade de serviço (também conhecido como ID do Objeto) em: Enterprise applications\<installed multitenant application>\Manage\Properties\Object ID.

• O Azure Key Vault também deve ser configurado para acesso baseado em função.

• CLI do Azure para enviar solicitações.

Escolher uma abordagem de autenticação

Você pode configurar um aplicativo de Microsoft Entra multilocatário para usar chaves gerenciadas pelo cliente em um cenário entre locatários usando uma das seguintes abordagens:

1. Suporte à identidade federada (versão prévia, recomendado): configure Microsoft Entra FIC (credenciais de identidade federadas) com uma UAMI (identidade gerenciada atribuída pelo usuário). Essa abordagem usa tokens de identidade gerenciados e os troca por tokens de acesso, eliminando a necessidade de segredos de longa duração e alinhando-se aos princípios de federação de identidade de carga de trabalho. Essa abordagem requer a propriedade de visualização federatedIdentityClientId , introduzida na versão 2026-05-01-previewda API.

2. Segredos do cliente: configure um segredo do cliente usando a accessCredentials propriedade. Essa abordagem é menos segura e requer gerenciamento adicional para rotacionar e proteger o segredo.

Criar um aplicativo multitenant Microsoft Entra no tenant A

Use a CLI do Azure para enviar solicitações. O locatário do provedor de serviços que contém o Pesquisa de IA do Azure  será referido como locatário A.

1. Obtenha a ID do locatário: az account show --query tenantId --output tsv

2. Verifique se você está conectado ao tenant A: az login --tenant \<tenant-A-id\>

3. Crie o registro do aplicativo: az ad app create --display-name cross-tenant-auth --sign-in-audience AzureADMultipleOrgs

4. Salve a saída do ID do aplicativo desta etapa.

Usar suporte de identidade federada (versão prévia)

Para usar a identidade federada para oferecer suporte a um cenário de CMK entre locatários:

1. O provedor de serviços configura o serviço de Pesquisa de IA em seu locatário (Locatário A). Para obter diretrizes sobre como fazer isso, consulte Criate a Search Service (no Azure portal) ou use o comando az search service create no CLI do Azure.

2. O provedor de serviços cria um registro de aplicativo multilocatário do Microsoft Entra. Para obter diretrizes sobre como fazer isso, consulte Como registrar um aplicativo no Microsoft Entra ID ou use o comando CLI do Azure: az ad app create. Registre a ID do aplicativo (cliente) depois de concluir o registro do aplicativo.

3. O provedor de serviços configura uma identidade gerenciada atribuída pelo usuário. Para obter diretrizes sobre como fazer isso, consulte Manage identidades gerenciadas atribuídas pelo usuário usando Azure portal ou Manage identidades gerenciadas atribuídas pelo usuário usando o CLI do Azure.

4. O provedor de serviços configura as identidades gerenciadas atribuídas pelo usuário como uma credencial de identidade federada no aplicativo. Para obter diretrizes sobre como fazer isso, consulte Configurar um aplicativo para confiar em um provedor de identidade externo.

5. Depois que o provedor de serviços compartilha o ID do aplicativo multitenant, o cliente concede ao aplicativo do provedor de serviços acesso ao Key Vault no seu locatário (Locatário B). Para instalar o aplicativo no locatário B, um principal de serviço deve ser criado usando o ID do aplicativo multilocatário. Para criar a entidade de serviço, crie uma URL de admin-consent e conceda consentimento para todo o locatário ou use o comando az ad sp na CLI do Azure.

6. Se o cliente ainda não tiver um cofre de chaves para usar, consulte Início Rápido – Criar um Azure Key Vault com o portal Azure ou Início Rápido – Criar um Azure Key Vault com o CLI do Azure. O Key Vault precisará do modelo de permissão definido como "RBAC (controle de acesso baseado em função) do Azure" com a permissão concedida pelo aplicativo multilocatário do provedor de serviços, atribuindo-lhe a função Usuário de Criptografia do Serviço de Criptografia do Key Vault. Em seguida, o cliente pode criar uma chave de criptografia. Para obter orientações sobre como fazer isso, consulte Conceder permissão a aplicativos para acessar um cofre de chaves do Azure usando o RBAC do Azure.

Depois que essas etapas forem concluídas, o provedor de serviços agora terá:

• Uma ID de aplicativo para um aplicativo multilocatário instalado no locatário do cliente, ao qual foi concedido acesso à chave gerenciada pelo cliente.

• Uma identidade gerenciada configurada como credencial federada do aplicativo multilocatário.

• O local da chave no cofre de chaves do cliente.

Com esses três parâmetros, o provedor de serviços agora pode criar objetos Pesquisa de IA do Azure  em Tenant A que podem ser criptografados com a chave gerenciada pelo cliente armazenada em Tenant B. Para obter diretrizes sobre como configurar chaves gerenciadas pelo cliente em novos objetos de pesquisa, consulte Configurar chaves gerenciadas pelo cliente para Pesquisa de IA do Azure  dados criptografados.

Validar a configuração do CMK de identidade federada entre locatários

Depois de configurar o aplicativo multilocatário do Microsoft Entra e conectá-lo ao Key Vault do cliente, verifique a configuração criando um objeto de teste no seu serviço de busca (locatário A). Este exemplo cria um índice para confirmar se o serviço de pesquisa pode acessar a chave gerenciada pelo cliente usando a autenticação de identidade federada.

1. Consulte Configurar chaves gerenciadas pelo cliente para Pesquisa de IA do Azure  dados criptografados para obter diretrizes sobre como criar um serviço de pesquisa e um novo objeto de índice com uma chave gerenciada pelo cliente.

2. Depois que o objeto de índice for criado, você precisará preencher o seguinte:

   • keyVaultUri: o endereço URI do cliente.
   • keyVaultKeyName: O nome da chave fornecido pelo cliente.
   • keyVaultKeyVersion: a versão de chave do cliente.
   • userAssignedIdentity: o <subscription-id> e o <resource-group> do seu locatário, e o <identity-name> é o nome da identidade gerenciada atribuída pelo usuário.
   • federatedIdentityClientId: este valor de propriedade, <application-client-id>, será o ID do aplicativo multilocatário (cliente).

   {
     "name": "cross-tenant-cmk-test",
     "fields": [
       {
         "name": "id",
         "type": "Edm.String",
         "key": true
       }
     ],
     "encryptionKey": {
       "keyVaultUri": "https://<key-vault-name>.vault.azure.net/",
       "keyVaultKeyName": "<key-name>",
       "keyVaultKeyVersion": "<key-version>",
       "identity": {
         "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
         "userAssignedIdentity": "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<identity-name>",
         "federatedIdentityClientId": "<application-client-id>"
       }
     }
   }
   

3. Verifique o índice enviando uma solicitação GET : GET https://<search-service>.search.windows.net/indexes/cross-tenant-cmk-test?api-version=2026-08-01-preview

Se a solicitação for bem-sucedida, a configuração do CMK entre locatários estará funcionando corretamente.

Se a criação do índice falhar com um erro de acesso à chave, verifique se:

• A identidade gerenciada atribuída pelo usuário está configurada corretamente
• A credencial de identidade federada é definida no aplicativo
• A política de acesso do Key Vault ou as atribuições de função RBAC estão corretas

Usar um segredo do cliente (se usar a identidade federada não for uma opção)

Se a identidade federada não for uma opção, você pode adicionar um segredo do cliente ao aplicativo multilocatário para dar suporte a um cenário de CMK entre locatários:

1. Para adicionar o segredo do cliente ao aplicativo multilocatário no locatário A, execute o seguinte comando:

   az ad app credential reset --id <multitenant-app-id>

2. Salve o resultado da senha desta etapa. A saída de senha é uma entrada necessária para configurar o CMK no Pesquisa de IA do Azure .

3. Para especificar quando o segredo do cliente expira, você pode especificar um parâmetro de data de término para esse comando.

   az ad app credential reset --id <multitenant-app-id> --end-date <end-date>

   O parâmetro de data de término aceita uma data no formato ISO 8601. Por exemplo: az ad app credential reset --id <multitenant-app-id> --end-date 2026-12-31.

Criar uma entidade de serviço no locatário B para o aplicativo multilocatário

Nos referimos ao locatário que contém o Azure Key Vault como locatário B. No locatário B, crie um principal de serviço para o aplicativo multilocatário no locatário A.

1. Conecte-se ao inquilino B:

   az login --tenant <tenant-B-id>

2. Crie a entidade de serviço usando a saída do ID do aplicativo multilocatário da primeira etapa:

   az ad sp create --id <multitenant-app-id>

   Essa entidade de serviço é uma instância do aplicativo multilocatário no locatário A. As funções atribuídas a essa entidade de serviço no locatário B também são atribuídas ao aplicativo multilocatário no locatário A.

3. Verifique o link entre o locatário A e B examinando a "appOwnerOrganizationId" no seguinte comando:

   az ad sp show --id <multitenant-app-id>

   Este comando exibe os detalhes da entidade de serviço em formato JSON. Procure o campo "appOwnerOrganizationId" na saída para confirmar se ele corresponde à ID do locatário A.

4. Salve o ID do objeto da entidade de serviço (do campo "id") desta etapa. A ID do objeto é uma entrada necessária para configurar o CMK no Pesquisa de IA do Azure .

5. Obtenha a ID do recurso para o Azure Key Vault:

   az keyvault show --name <key-vault-name> --query id --output tsv

6. Atribua a função Key Vault de Criptografia do Serviço de Criptografia função no cofre de chaves no locatário B à nova entidade de serviço.

   az role assignment create --assignee <service-principal-object-id> --role "Key Vault Crypto Service Encryption User" --scope <key-vault-resource-id>

   Um exemplo dessa atribuição pode ter esta aparência:

   az role assignment create --assignee 00001111-aaaa-2222-bbbb-3333cccc4444 --role "Key Vault Crypto Service Encryption User" --scope /subscriptions/87654321-4321-4321-4321-210987654321/resourceGroups/myKeyVaultRG/providers/Microsoft.KeyVault/vaults/myCompanyKeyVault

Validar a configuração do CMK do segredo do cliente entre locatários

Depois de configurar o aplicativo multilocatário do Microsoft Entra e conectá-lo ao Key Vault do cliente, verifique a configuração criando um objeto de teste no seu serviço de busca (locatário A). Este exemplo cria um índice para confirmar se o serviço de pesquisa pode acessar a chave gerenciada pelo cliente usando o segredo do cliente.

1. Consulte Configurar chaves gerenciadas pelo cliente para Pesquisa de IA do Azure  dados criptografados para obter diretrizes sobre como criar um serviço de pesquisa e um novo objeto de índice com uma chave gerenciada pelo cliente.

2. Você pode usar o portal Azure para adicionar um índice e fornecer esse JSON ou usar um cliente REST para enviar uma solicitação Create Index. Depois que o objeto de índice for criado, você precisará preencher o seguinte:

   • keyVaultUri: o endereço URI do cliente.
   • keyVaultKeyName: O nome da chave fornecido pelo cliente.
   • keyVaultKeyVersion: a versão de chave do cliente.
   • accessCredentials: O applicationId é algo como 00001111-aaaa-2222-bbbb-3333cccc4444, e o applicationSecret é o valor que você acabou de criar.

{
  "name": "cross-tenant-cmk-test",
  "fields": [
        {
            "name": "id",
            "type": "Edm.String",
            "key": true
        }
      ],
 "encryptionKey": {
        "keyVaultUri": "https://<key-vault-name>.vault.azure.net/",
        "keyVaultKeyName": "<key-name>",
        "keyVaultKeyVersion": "<key-version>",
    "accessCredentials": {
      "applicationId": "<application-client-id>",
      "applicationSecret": "<application-client-secret>"
    }
  }
}

Verifique se o índice foi criado com êxito:

GET https://<search-service>.search.windows.net/indexes/cross-tenant-cmk-test?api-version=2026-04-01

Para obter mais informações sobre como girar ou gerenciar chaves, consulte Configurar chaves gerenciadas pelo cliente para criptografia de dados.