Configurar uma conexão Azure Key Vault em Microsoft Foundry

Se não configurar uma ligação ao Key Vault, o Microsoft Foundry armazena os detalhes da ligação num Key Vault gerido pela Microsoft fora da sua subscrição. Para gerir os seus próprios segredos, ligue o seu Azure Key Vault à Foundry. Antes de começar, reveja as limitações para as conexões do Key Vault.

Azure Key Vault é um serviço na cloud para armazenar e aceder a segredos de forma segura. Um segredo é qualquer coisa a que queiras controlar apertadamente o acesso, como chaves API, palavras-passe, certificados ou chaves criptográficas. Para mais informações, consulte Sobre Azure Key Vault.

Pré-requisitos

Limitações

Cria ligações ao Azure Key Vault apenas quando precisares delas.

Se trouxer o seu próprio Azure Key Vault, reveja estas limitações:

  • Limitar as ligações do Azure Key Vault a uma por recurso Foundry. Elimine uma ligação ao Azure Key Vault apenas se não existirem outras ligações ao nível do recurso ou projeto da Foundry.

  • A Foundry não suporta migração secreta. Remove e refaz as ligações você mesmo.

  • Eliminar o Azure Key Vault subjacente quebra o recurso da Foundry. O Azure Key Vault armazena segredos para ligações que não usam o Microsoft Entra ID. Qualquer funcionalidade do Foundry que dependa dessas ligações deixa de funcionar.

  • Eliminar segredos de ligação que o seu recurso Foundry armazena no seu próprio Azure Key Vault (BYO) pode quebrar ligações a outros serviços.

Use um modelo de Bicep

Implemente uma ligação Key Vault usando Azure Bicep. O modelo seguinte cria uma ligação entre o seu recurso Foundry e um Azure Key Vault existente, e atribui o papel de Oficial de Segredos Key Vault à identidade gerida 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 seu recurso Foundry.
keyVaultName O nome do seu Azure Key Vault atual.

Implementar o modelo

Execute o seguinte comando para implementar 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 implementação

Após a conclusão do destacamento:

  1. Navegue até ao seu recurso Foundry no portal Azure.
  2. Selecione Centro de Gestão no painel inferior esquerdo.
  3. Selecione Recursos Conectados e confirme que a Azure Key Vault ligação aparece na lista.
  4. Selecione a ligação para visualizar as suas propriedades e verifique o ID do recurso do Key Vault.

Para verificar se a atribuição de papéis 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

Gestão de ligações ao Key Vault

Criação

Certifique-se de que não existem outras ligações ao nível do recurso ou projeto da Foundry. O serviço bloqueia a criação de ligações ao Key Vault se existirem outras ligações. Se a interface não mostrar uma categoria de ligação ao Key Vault quando escolhes uma ligação, este problema pode ser a causa. Apaga outras ligações e depois tenta novamente.

Quando crias uma ligação ao Key Vault, o serviço não utiliza o Key Vault gerido no Azure.

Eliminação

Antes de eliminar uma ligação ao Azure Key Vault do Foundry, remova todas as outras ligações. Depois de remover todas as outras ligações ao nível de recursos e projetos da Foundry, apague a ligação ao Key Vault. A Foundry não suporta migração secreta.

Atualização ou alteração

Para mudar do Azure Key Vault 1 para o Azure Key Vault 2, elimine a ligação do Azure Key Vault 1 e depois crie a ligação do Azure Key Vault 2. Siga os passos de eliminação e criação, e recrie manualmente quaisquer segredos de ligação.

Ciclo de vida secreto do Key Vault

Quando apaga conexões do seu Key Vault administrado, os respetivos segredos são apagados. Eliminar uma ligação ao Key Vault também elimina os seus segredos.

Conceder à Foundry acesso ao teu cofre de chaves

Dependendo de como o teu cofre de chaves está provisionado, poderás precisar de aplicar permissões adicionais. Verifique se o seu Azure Key Vault utiliza controlo de acesso baseado em funções (RBAC) ou políticas de acesso, e depois continue.

Controlo de acesso baseado em funções (RBAC)

Depois de criares a ligação ao Key Vault, atribui um papel RBAC apropriado no portal Azure. Colaborador do Key Vault e Administrador do Key Vault são dois papéis que funcionam. Para permissões mínimas, use o Key Vault Secrets Officer.

Políticas de acesso

Semelhante às funções RBAC, atribuir a política de acesso apropriada ao Key Vault (se aplicável) à identidade gerida do recurso Foundry.

Infraestrutura como modelos de código

Como boa prática, ao configurar templates ARM, Bicep ou Terraform para criar recursos, certifique-se de que a ligação Azure Key Vault é a primeira que criar, e que todas as outras ligações dependam do sucesso da ligação Key Vault. Esta ordem ajuda a reduzir falhas na ligação ao Key Vault. Se não seguir estas melhores práticas, os seus modelos podem enfrentar situações de disputa nas suas conexões. Como resultado, as implementações podem funcionar por vezes e falhar noutras porque o Foundry não suporta migração secreta.

Depois de criares o recurso Foundry e a ligação Key Vault, atribui os papéis RBAC apropriados ao recurso Foundry. Faça com que todas as outras ligações dependam do sucesso desta atribuição. O mesmo se aplica se o seu Key Vault usar políticas de acesso em vez de RBAC.

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

  1. Cria o recurso Foundry.
  2. Cria um projeto Foundry.
  3. Crie a ligação ao Azure Key Vault.
  4. Atribuir a função RBAC apropriada ao Key Vault para o recurso da Foundry.
  5. (Opcional) Valide que o papel do RBAC entra em vigor.
  6. Crie quaisquer outras ligações ao nível do recurso ou projeto e defina o dependsOn campo para os passos 3 e 4.

Eliminação

Para a limpeza, se automatizar a eliminação de recursos usando modelos, siga os passos de criação por ordem inversa:

  1. Apague todas as ligações ao nível do recurso ou projeto da Foundry.
  2. Apague a ligação do Azure Key Vault.
  3. Apague todos os projetos da Foundry.
  4. Apaga o recurso da Foundry.

Resolução de problemas

Atrasos na atribuição de funções do RBAC

Depois de atribuir o papel de Oficial de Segredos do Key Vault, pode demorar até 30 minutos para as permissões se propagarem. Se receberes erros de permissão imediatamente após a atribuição de funções, espera e tenta novamente.

A conexão não aparece

Se a ligação Key Vault não aparecer em Connected resources:

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

Erros de implementação

Se a implementação falhar:

  • Confirma que tens o papel de Contribuinte ou Proprietário no grupo de recursos.
  • Verifique se o nome do Key Vault está correto e se o cofre existe na sua subscrição.
  • Verifica se o nome do recurso Foundry corresponde exatamente.

Próximos passos

  • Last updated on