Configurare una connessione Azure Key Vault in Microsoft Foundry

Se non si configura una connessione Key Vault, Microsoft Foundry archivia i dettagli della connessione in un Key Vault gestito da Microsoft all'esterno della sottoscrizione. Per gestire i propri segreti, connettere il Azure Key Vault a Foundry. Prima di iniziare, esaminare le limitations per le connessioni Key Vault.

Azure Key Vault è un servizio cloud per l'archiviazione e l'accesso ai segreti in modo sicuro. Un segreto è qualsiasi elemento a cui si vuole controllare rigorosamente l'accesso, ad esempio chiavi API, password, certificati o chiavi crittografiche. Per altre informazioni, vedere About Azure Key Vault.

Prerequisiti

  • Sottoscrizione Azure.
  • Risorsa Foundry senza connessioni esistenti a livello di risorsa o progetto.
  • Un Azure Key Vault nella tua sottoscrizione o autorizzazioni per crearne uno nuovo.
  • Uno dei seguenti ruoli RBAC di Azure per il Key Vault:

Limitazioni

Creare connessioni Azure Key Vault solo quando sono necessarie.

Se porti il tuo Azure Key Vault, esamina queste limitazioni:

  • Limitare le connessioni Azure Key Vault a una per risorsa Foundry. Eliminare una connessione Azure Key Vault solo se non esistono altre connessioni a livello di risorsa o progetto Foundry.

  • Foundry non supporta la migrazione dei segreti di configurazione. Rimuovere e ricreare le connessioni manualmente.

  • L'eliminazione dell'Azure Key Vault sottostante interrompe la risorsa Foundry. Azure Key Vault archivia i segreti per le connessioni che non usano Microsoft Entra ID. Qualsiasi funzionalità foundry che dipende da tali connessioni smette di funzionare.

  • L'eliminazione dei segreti di connessione archiviati dalle risorse Foundry nei Azure Key Vault BYO (Bring Your Own) può interrompere le connessioni ad altri servizi.

Usare un modello di Bicep

Distribuire una connessione Key Vault usando Azure Bicep. Il modello seguente crea una connessione tra la risorsa Foundry e un Azure Key Vault esistente e assegna il ruolo Key Vault Secrets Officer all'identità gestita della risorsa 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

Parametri

Parametro Descrizione
aiFoundryName Nome della risorsa Foundry.
keyVaultName Nome del Azure Key Vault esistente.

Distribuire il modello

Eseguire il comando seguente per distribuire il modello:

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>

Verificare la distribuzione

Al termine della distribuzione:

  1. Passare alla risorsa Foundry nel portale di Azure.
  2. Selezionare Centro gestione nel riquadro in basso a sinistra.
  3. Selezionare Risorse connesse e verificare che l'Azure Key Vault connessione venga visualizzata nell'elenco.
  4. Selezionare la connessione per visualizzarne le proprietà e verificare l'ID risorsa Key Vault.

Per verificare che l'assegnazione del ruolo RBAC sia effettiva, eseguire il comando seguente:

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

Riferimento

gestione delle connessioni Key Vault

Creazione

Assicurarsi che non esistano altre connessioni a livello di risorsa o progetto Foundry. Il servizio blocca la creazione di connessioni a Key Vault se sono già presenti altre connessioni. Se l'interfaccia utente non mostra una categoria di connessione Key Vault quando si sceglie una connessione, questo problema potrebbe essere il motivo. Eliminare altre connessioni e riprovare.

Quando si crea una connessione Key Vault, il servizio non usa il Key Vault gestito in Azure.

Eliminazione

Prima di eliminare una connessione Azure Key Vault da Foundry, rimuovere tutte le altre connessioni. Dopo aver rimosso tutte le altre connessioni a livello di risorsa e progetto Foundry, eliminare la connessione Key Vault. Foundry non supporta la migrazione dei segreti di configurazione.

Aggiornare o modificare

Per passare da Azure Key Vault 1 a Azure Key Vault 2, eliminare la connessione Azure Key Vault 1 e quindi creare la connessione Azure Key Vault 2. Seguire i passaggi di eliminazione e creazione e ricreare manualmente tutti i segreti di connessione.

Ciclo di vita dei segreti di Key Vault

Quando si eliminano le connessioni dal Key Vault gestito, i segreti corrispondenti vengono eliminati. L'eliminazione di una connessione con Key Vault comporta anche l'eliminazione dei suoi segreti.

Concessione dell'accesso al tuo insieme di credenziali a Foundry

A seconda della modalità di provisioning dell'insieme di credenziali delle chiavi, potrebbe essere necessario applicare autorizzazioni aggiuntive. Controllare se il Azure Key Vault usa il controllo degli accessi in base al ruolo o i criteri di accesso e quindi continuare.

Controllo degli accessi in base al ruolo

Dopo aver creato la connessione al Key Vault nel portale di Azure, assegnare un ruolo di controllo degli accessi basato sui ruoli appropriato. Key Vault Collaboratore e amministratore di Key Vault sono due ruoli che funzionano. Per le autorizzazioni minime, usare Key Vault Secrets Officer.

Criteri di accesso

Analogamente ai ruoli RBAC, assegnare la politica di accesso al key vault appropriata (se applicabile) all'identità gestita della risorsa Foundry.

Infrastruttura come modelli di codice

Come procedura consigliata, quando si configurano i modelli di ARM, Bicep o Terraform per creare risorse, assicurarsi che la connessione a Azure Key Vault sia la prima connessione creata e fare in modo che tutte le altre connessioni dipendano dal successo della connessione a Key Vault. Questo ordine consente di ridurre gli errori di connessione Key Vault. Se non si segue questa procedura consigliata, i modelli possono riscontrare condizioni di competizione attraverso le loro connessioni. Di conseguenza, le distribuzioni possono funzionare a volte e fallire in altri momenti perché Foundry non supporta la migrazione dei segreti.

Dopo aver creato la risorsa Foundry e la connessione Key Vault, assegnare i ruoli RBAC appropriati alla risorsa Foundry. Fare in modo che tutte le altre connessioni dipendono da questa assegnazione di ruolo riuscita. Lo stesso vale se il Key Vault usa il criterio di accesso anziché RBAC.

Segui questo ordine nei modelli di codice per l'infrastruttura

  1. Crea la risorsa Foundry.
  2. Creare un progetto Foundry.
  3. Creare la connessione Azure Key Vault.
  4. Assegnare il ruolo RBAC appropriato nel Key Vault per la risorsa Foundry.
  5. (Facoltativo) Verificare che il ruolo RBAC entri in vigore.
  6. Creare qualsiasi altra connessione a livello di risorsa o progetto e impostare il campo per i dependsOn passaggi 3 e 4.

Eliminazione

Per la pulizia, se si automatizza l'eliminazione delle risorse usando i modelli, seguire i passaggi di creazione in ordine inverso:

  1. Eliminare tutte le connessioni a livello di risorsa o progetto Foundry.
  2. Eliminare la connessione Azure Key Vault.
  3. Eliminare tutti i progetti Foundry.
  4. Eliminare la risorsa Foundry.

Risoluzione dei problemi

Ritardi nell'assegnazione di ruoli RBAC

Dopo aver assegnato il ruolo Key Vault Secrets Officer, la propagazione delle autorizzazioni può richiedere fino a 30 minuti. Se si ricevono errori di autorizzazione immediatamente dopo l'assegnazione di ruolo, attendere e riprovare.

Connessione non visualizzata

Se la connessione Key Vault non viene visualizzata in risorse Connesse:

  1. Verificare che la distribuzione sia stata completata correttamente.
  2. Aggiornare la pagina del portale.
  3. Verificare che non esistano altre connessioni a livello di risorsa o progetto. Il servizio blocca Key Vault creazione di connessioni quando esistono altre connessioni.

Errori di distribuzione

Se la distribuzione fallisce:

  • Verifica di avere il ruolo di Collaboratore o Proprietario nel gruppo di risorse.
  • Verificare che il nome del Key Vault sia corretto e che il Key Vault esista nella tua sottoscrizione.
  • Verificare che il nome della risorsa Foundry corrisponda esattamente.

Passaggi successivi

  • Last updated on