Configurar uma conexão Azure Key Vault no Microsoft Foundry

Se você não configurar uma conexão Key Vault, o Microsoft Foundry armazenará os detalhes da conexão em uma Key Vault gerenciada por Microsoft fora de sua assinatura. Para gerenciar seus próprios segredos, conecte seu Azure Key Vault ao Foundry. Antes de começar, examine as limitações para conexões do Key Vault.

Azure Key Vault é um serviço de nuvem para armazenar e acessar segredos com segurança. Um segredo é tudo o que você deseja controlar firmemente o acesso, como chaves de API, senhas, certificados ou chaves criptográficas. Para obter mais informações, consulte About Azure Key Vault.

Pré-requisitos

Limitações

Crie Azure Key Vault conexões somente quando precisar delas.

Se você trouxer seu próprio Azure Key Vault, examine estas limitações:

  • Limite as conexões de Azure Key Vault a uma por recurso do Foundry. Exclua uma conexão Azure Key Vault somente se nenhuma outra conexão existir no nível de projeto ou recurso do Foundry.

  • A Foundry não dá suporte à migração secreta. Remova e recrie as conexões por conta própria.

  • Excluir o Azure Key Vault subjacente interrompe o recurso do Foundry. Azure Key Vault armazena segredos para conexões que não usam Microsoft Entra ID. Qualquer recurso do Foundry que dependa dessas conexões para de funcionar.

  • A exclusão de segredos de conexão que o recurso Foundry armazena em seu BYO Azure Key Vault pode interromper conexões com outros serviços.

Usar um modelo de Bicep

Implante uma conexão Key Vault usando Azure Bicep. O modelo a seguir cria uma conexão entre o recurso foundry e um Azure Key Vault existente e atribui a função Key Vault Secrets Officer à identidade gerenciada do recurso Foundry.

/*

Set up your Key Vault connection

Select which RBAC role to assign:
1. Key Vault Administrator:  00482a5a-887f-4fb3-b363-3b7fe8e74483 - https://learn.microsoft.com/en-us/azure/role-based-access-control/built-in-roles/security#key-vault-administrator
2. Key Vault Contributor:    f25e0fa2-a7c8-4377-a976-54943a77a395 - https://learn.microsoft.com/en-us/azure/role-based-access-control/built-in-roles/security#key-vault-contributor
3. Key Vault Secret Officer: b86a8fe4-44ce-4948-aee5-eccb2c155cd7 - https://learn.microsoft.com/en-us/azure/role-based-access-control/built-in-roles/security#key-vault-secrets-officer
This template defaults to using the Key Vault Secret Officer role.


Run command:
az deployment group create \
  --name AzDeploy \
  --resource-group {RESOURCE-GROUP-NAME} \
  --template-file connection-key-vault.bicep \
  --parameters aiFoundryName={Foundry-resource-name} keyVaultName={KV-resource-name}

az deployment group create --name AzDeploy --resource-group {RESOURCE-GROUP-NAME} --template-file connection-key-vault.bicep --parameters aiFoundryName={Foundry-resource-name} keyVaultName={KV-resource-name}

*/

param aiFoundryName string = '<your-account-name>'
param keyVaultName string
//param resourceGroupName string = '<your-resource-group-name>'


resource aiFoundry 'Microsoft.CognitiveServices/accounts@2025-04-01-preview' existing = {
  name: aiFoundryName
  scope: resourceGroup()
}

// Conditionally refers your existing Azure Key Vault resource
resource existingKeyVault 'Microsoft.KeyVault/vaults@2024-11-01' existing = {
  name: keyVaultName
  scope: resourceGroup()
}

resource connection 'Microsoft.CognitiveServices/accounts/connections@2025-04-01-preview' = {
  name: '${aiFoundryName}-keyvault'
  parent: aiFoundry
  properties: {
    category: 'AzureKeyVault'
    target: existingKeyVault.id
    authType: 'AccountManagedIdentity'
    isSharedToAll: true
    metadata: {
      ApiType: 'Azure'
      ResourceId: existingKeyVault.id
      location: existingKeyVault.location
    }
  }
}

// Include RBAC on Key Vault for Foundry
resource rbacAssignment 'Microsoft.Authorization/roleAssignments@2020-04-01-preview' = {
  name: guid(existingKeyVault.id, 'KeyVaultSecretsOfficer')
  scope: existingKeyVault
  properties: {
    roleDefinitionId: '/providers/Microsoft.Authorization/roleDefinitions/b86a8fe4-44ce-4948-aee5-eccb2c155cd7'
    principalId: aiFoundry.identity.principalId
  }
}

// All following connections should be created with the dependsOn property for both the key vault connection and the role assignment

Parâmetros

Parâmetro Descrição
aiFoundryName O nome do recurso Foundry.
keyVaultName O nome do Azure Key Vault existente.

Implantar o modelo

Execute o seguinte comando para implantar o modelo:

az deployment group create \
  --name AzDeploy \
  --resource-group <resource-group-name> \
  --template-file connection-key-vault.bicep \
  --parameters aiFoundryName=<foundry-resource-name> keyVaultName=<keyvault-name>

Verificar a implantação

Após a conclusão da implantação:

  1. Navegue até o recurso Foundry no portal do Azure.
  2. Selecione o Centro de Gerenciamento no painel inferior esquerdo.
  3. Selecione Recursos conectados e confirme se a conexão Azure Key Vault aparece na lista.
  4. Selecione a conexão para exibir suas propriedades e verificar a ID do recurso Key Vault.

Para verificar se a atribuição de função RBAC está em vigor, execute o seguinte comando:

az role assignment list \
  --scope /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.KeyVault/vaults/<keyvault-name> \
  --query "[?roleDefinitionName=='Key Vault Secrets Officer']" \
  --output table

Referência

gerenciamento de conexão com Key Vault

Criação

Verifique se não existem outras conexões no nível de projeto ou recurso do Foundry. O serviço bloqueia a criação de conexões do Key Vault se existirem outras conexões. Se a interface do usuário não mostrar uma categoria de conexão Key Vault quando você escolher uma conexão, esse problema pode ser o motivo. Exclua outras conexões e tente novamente.

Quando você cria uma conexão Key Vault, o serviço não usa o Key Vault gerenciado no Azure.

Exclusão

Antes de excluir uma conexão Azure Key Vault do Foundry, remova todas as outras conexões. Depois de remover todas as outras conexões nos níveis de projeto e recursos do Foundry, exclua a conexão Key Vault. A Foundry não dá suporte à migração secreta.

Atualizar ou alterar

Para alternar de Azure Key Vault 1 para Azure Key Vault 2, exclua a conexão Azure Key Vault 1 e crie a conexão Azure Key Vault 2. Siga as etapas de exclusão e criação e recrie manualmente todos os segredos de conexão.

Key Vault ciclo de vida secreto

Quando você exclui conexões de seu Key Vault gerenciado, os segredos correspondentes são excluídos. Excluir uma conexão do Key Vault também exclui seus segredos armazenados.

Concedendo ao Foundry acesso ao cofre de chaves

Dependendo de como o cofre de chaves é provisionado, talvez seja necessário aplicar permissões adicionais. Verifique se o Azure Key Vault usa RBAC (controle de acesso baseado em função) ou políticas de acesso e continue.

RBAC (controle de acesso baseado em função)

Depois de criar a conexão Key Vault, atribua uma função RBAC apropriada no portal Azure. Key Vault Colaborador e Administrador de Key Vault são duas funções que funcionam. Para permissões mínimas, use o Responsável pelos segredos do Key Vault.

Políticas de acesso

Semelhante às funções RBAC, atribua a política de acesso apropriada do cofre de chaves (se aplicável) à identidade gerenciada do recurso da Fábrica.

Infraestrutura como modelos de código

Como prática recomendada, ao configurar modelos ARM, Bicep ou Terraform para criar recursos, verifique se a conexão Azure Key Vault é a primeira conexão que você cria e faça com que todas as outras conexões dependam do sucesso da conexão Key Vault. Essa ordem ajuda a reduzir falhas de conexão do Key Vault. Se você não seguir essa prática recomendada, seus modelos poderão encontrar condições de corrida em suas conexões. Como resultado, as implantações podem funcionar às vezes e falhar em outras ocasiões porque o Foundry não dá suporte à migração secreta.

Depois de criar o recurso Foundry e a conexão Key Vault, atribua as funções RBAC apropriadas ao recurso Foundry. Fazer com que todas as outras conexões dependam da êxito dessa atribuição de função. O mesmo se aplica se o Key Vault usa políticas de acesso em vez de RBAC.

Siga esta ordem em sua infraestrutura como modelos de código

  1. Crie o recurso Foundry.
  2. Criar um projeto do Foundry.
  3. Crie a conexão Azure Key Vault.
  4. Atribua a função RBAC apropriada no Key Vault para o recurso Foundry.
  5. (Opcional) Valide se a função RBAC está em vigor.
  6. Crie outras conexões no nível do recurso ou do projeto e defina o campo dependsOn para as etapas 3 e 4.

Exclusão

Para limpeza, se você automatizar a exclusão de recursos usando modelos, siga as etapas de criação na ordem inversa:

  1. Exclua todas as conexões no nível de recurso ou projeto do Foundry.
  2. Exclua a conexão Azure Key Vault.
  3. Exclua todos os projetos do Foundry.
  4. Exclua o recurso Foundry.

Solucionando problemas

Atrasos na atribuição de função RBAC

Depois de atribuir a função de Oficial de Segredos do Key Vault, pode levar até 30 minutos para que as permissões sejam propagadas. Se você receber erros de permissão imediatamente após a atribuição de função, aguarde e tente novamente.

A conexão não aparece

Se a conexão Key Vault não aparecer nos recursos Conectados:

  1. Verifique se a implantação foi concluída com êxito.
  2. Atualize a página do portal.
  3. Verifique se não existem outras conexões no nível do recurso ou do projeto. O serviço bloqueia a criação de conexões do Key Vault quando existem outras conexões.

Erros de implantação

Se a implantação falhar:

  • Confirme se você tem a função Colaborador ou Proprietário no grupo de recursos.
  • Verifique se o nome do Key Vault está correto e se o cofre existe em sua assinatura.
  • Verifique se o nome do recurso Foundry corresponde exatamente.

Próximas etapas

  • Last updated on