Configurar chaves gerenciadas pelo cliente em diferentes locatários

Este artigo descreve um cenário entre tenants em que um prestador de serviços aloja o Pesquisa de IA do Azure no seu próprio tenant e ativa a encriptação com chave gerida pelo cliente (CMK) usando uma aplicação Microsoft Entra multilocatário.

Nesta configuração, o cliente utiliza o Azure Key Vault no seu próprio tenant para gerir a sua chave de encriptação. O fornecedor de serviços não tem acesso a esta chave.

Pré-requisitos

• Tenant A: Um tenant e as permissões necessárias para criar o serviço Pesquisa de IA do Azure e os objetos associados (índices, listas de sinónimos, indexadores, fontes de dados, vetorizadores, conjuntos de competências). O suporte a chaves geridas pelo cliente (CMK) requer um nível de preços básico ou superior.

• Configure o serviço de pesquisa para acesso baseado em funções (recomendado para maior segurança, não obrigatório).

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

  • Key Vault Contributor: Esta função é necessária caso precise de criar um novo cofre de chaves.
  • Permissão para registar aplicações em Microsoft Entra ID: Para instalar a aplicação multitenant configurada pelo fornecedor de serviços para CMK entre inquilinos, deve ter permissão para criar registos de aplicações em Microsoft Entra ID. Isto normalmente requer o papel de Desenvolvedor de Aplicações ou um cargo administrativo superior, como Administrador de Aplicações ou Administrador Global.
  • Responsável pela Criptografia do Key Vault: Esta função é necessária para adicionar uma nova chave ao Key Vault.
  • Key Vault Crypto Service Encryption User: Este papel deve ser atribuído ao principal de serviço criado para a aplicação multitenant instalada, de modo a conceder ao principal de serviço acesso à chave gerida pelo cliente no key vault. Deve ter permissão de Administrador de Acesso ao Utilizador para fazer isto. Pode visualizar o principal de serviço GUID (também conhecido como ID de 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ções.

• CLI do Azure para enviar pedidos.

Escolha uma abordagem de autenticação

Pode configurar uma aplicação Microsoft Entra multitenant para usar chaves geridas pelo cliente num cenário entre inquilinos, utilizando uma das seguintes abordagens:

1. Suporte para identidade federada (pré-visualização, recomendado): Configure as credenciais de identidade federada (FIC) do Microsoft Entra com uma identidade gerida atribuída pelo utilizador (UAMI). Esta abordagem utiliza tokens de identidade gerida e troca-os por tokens de acesso, eliminando a necessidade de segredos de longa duração e alinhando-se com os princípios da federação de identidade de cargas de trabalho. Esta abordagem requer a propriedade de pré-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. Esta abordagem é menos segura e requer gestão adicional para proceder à rotação e proteção do segredo.

Criar uma aplicação Microsoft Entra com suporte a diversos inquilinos no inquilino A

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

1. Obtenha o ID do inquilino: az account show --query tenantId --output tsv

2. Certifique-se de que está registado no inquilino A: az login --tenant \<tenant-A-id\>

3. Crie o registo da candidatura: az ad app create --display-name cross-tenant-auth --sign-in-audience AzureADMultipleOrgs

4. Guarde a saída do ID da aplicação nesta etapa.

Utilize o suporte para identidade federada (pré-visualização)

Para usar identidade federada para suportar um cenário CMK entre inquilinos:

1. O fornecedor de serviços configura o serviço AI Search no respetivo inquilino (Tenant A). Para orientações sobre como fazer isto, consulte Criar um Serviço de Pesquisa (no portal Azure) ou use o comando az search service create no CLI do Azure.

2. O fornecedor de serviços cria um registo multitenant da aplicação Microsoft Entra. Para orientações sobre como fazer isto, consulte Como registar uma aplicação no Microsoft Entra ID, ou use o comando CLI do Azure: az ad app create. Regista o ID da Aplicação (cliente) depois de concluíres o registo da aplicação.

3. O fornecedor de serviços cria uma identidade gerida atribuída pelo utilizador. Para orientações sobre como o fazer, consulte Gerir identidades geridas atribuídas pelos utilizadores usando Azure portal ou Gerir identidades geridas atribuídas pelos utilizadores usando o CLI do Azure.

4. O fornecedor de serviços configura as identidades geridas atribuídas pelo utilizador como uma credencial de identidade federada na aplicação. Para orientações sobre como fazer isto, consulte Configurar uma aplicação para confiar num fornecedor de identidade externo.

5. Assim que o prestador de serviços partilha o ID da aplicação multi-inquilino, o cliente concede à aplicação do prestador de serviços acesso ao Key Vault no respetivo inquilino (Tenant B). Para instalar a aplicação no Tenant B, é necessário criar um principal de serviço com o ID da aplicação multiinquilino. Para criar o principal do serviço, constrói uma URL admin-consent e concede consentimento a nível de arrendatário ou use o comando az ad sp no CLI do Azure.

6. Se o cliente ainda não tiver um cofre de chaves para usar, veja Quickstart - Criar um Azure Key Vault com o portal Azure ou Quickstart - Criar um Azure Key Vault com a CLI do Azure. O Key Vault terá de ter o modelo de permissões definido como "Azure role-based access control (RBAC)", com a aplicação multi-inquilino do prestador de serviços a receber permissão mediante a atribuição da função Utilizador de Encriptação do Serviço de Criptografia do Key Vault. O cliente pode então criar uma chave de encriptação. Para orientações sobre como fazer isto, consulte Conceder permissão a aplicações para aceder a um cofre de chaves Azure usando Azure RBAC.

Uma vez concluídos estes passos, o prestador de serviços tem agora:

• Um ID de aplicação para uma aplicação multitenant instalada no locatário do cliente, à qual foi concedido acesso à chave gerida pelo cliente.

• Uma identidade gerida configurada como credencial federada na aplicação multiinquilino.

• A localização da chave no cofre de chaves do cliente.

Com estes três parâmetros, o fornecedor de serviços pode agora criar Pesquisa de IA do Azure objetos em Tenant A que podem ser encriptados com a chave gerida pelo cliente armazenada em Tenant B. Para orientações sobre como configurar chaves geridas pelo cliente em novos objetos de pesquisa, consulte Configure chaves geridas pelo cliente para Pesquisa de IA do Azure dados encriptados.

Validar a configuração de CMK entre tenants para identidade federada

Depois de configurar a aplicação multitenant Microsoft Entra e ligá-la ao Key Vault do cliente, verifique a configuração criando um objeto de teste no seu serviço de pesquisa (tenant A). Este exemplo cria um índice para confirmar que o serviço de pesquisa pode aceder à chave gerida pelo cliente usando autenticação federada de identidade.

1. Consulte Configurar chaves geridas pelo cliente para dados encriptados do Pesquisa de IA do Azure para obter orientações sobre como criar um serviço de pesquisa e um novo objeto de índice com uma chave gerida pelo cliente.

2. Depois de criado o objeto de índice, terá de preencher o seguinte:

   • keyVaultUri: O endereço URI do cliente.
   • keyVaultKeyName: O nome-chave do cliente.
   • keyVaultKeyVersion: A versão chave do cliente.
   • userAssignedIdentity: O <subscription-id> e <resource-group> do seu inquilino, e o <identity-name> é o nome de identidade gerida atribuído pelo utilizador.
   • federatedIdentityClientId: Este valor da propriedade, <application-client-id>, será o ID da aplicação multitenant (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 um GET pedido: 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 CMK entre locatários está a funcionar corretamente.

Se a criação de índice falhar devido a um erro de acesso à chave, verifique que:

• A identidade gerida atribuída pelo utilizador está configurada corretamente
• A credencial de identidade federada está definida na aplicação
• A política de acesso ao Key Vault ou as atribuições de funções RBAC estão corretas

Use um cliente secreto (se usar identidade federada não for uma opção)

Se a identidade federada não for uma opção, pode adicionar um segredo de cliente à aplicação multitenant para suportar um cenário de CMK entre inquilinos:

1. Para adicionar a chave secreta do cliente à aplicação multitenant no tenant A, execute o seguinte comando:

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

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

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

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

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

Crie um princípio de serviço no locatário B para a aplicação multilocatário

Referimo-nos ao inquilino que contém o Azure Key Vault como inquilino B. No inquilino B, crie um principal de serviço para a aplicação multi-inquilino no inquilino A.

1. Inicie sessão no cliente B.

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

2. Crie a entidade de serviço usando a saída do ID do aplicativo multilocatário desde a 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 vínculo entre o locatário A e B examinando o "appOwnerOrganizationId" no seguinte comando:

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

   Este comando exibe os detalhes do service principal em JSON. Procure o campo "appOwnerOrganizationId" na saída para confirmar que corresponde ao ID do locatário A.

4. Guarde o ID do objeto do principal de serviço (do campo "id") desta etapa. A ID do objeto é uma entrada necessária para configurar a 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 Usuário de Criptografia do Serviço de Criptografia do Cofre da Chave 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 secreta do cliente entre inquilinos CMK

Depois de configurar a aplicação multitenant Microsoft Entra e ligá-la ao Key Vault do cliente, verifique a configuração criando um objeto de teste no seu serviço de pesquisa (tenant A). Este exemplo cria um índice para confirmar que o serviço de pesquisa pode aceder à chave gerida pelo cliente usando o segredo do cliente.

1. Consulte Configurar chaves geridas pelo cliente para dados encriptados do Pesquisa de IA do Azure para obter orientações sobre como criar um serviço de pesquisa e um novo objeto de índice com uma chave gerida pelo cliente.

2. Pode usar o portal Azure para adicionar um índice e fornecer este JSON, ou usar um cliente REST para enviar um pedido Create Index. Depois de criado o objeto de índice, terá de preencher o seguinte:

   • keyVaultUri: O endereço URI do cliente.
   • keyVaultKeyName: O nome-chave do cliente.
   • keyVaultKeyVersion: A versão chave do cliente.
   • accessCredentials: O applicationId é algo como 00001111-aaaa-2222-bbbb-3333cccc4444, e o applicationSecret é o valor que acabaste 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.