Configurare le chiavi gestite dai clienti tra diversi tenant

Questo articolo descrive uno scenario tra tenant in cui un provider di servizi ospita Azure AI Search nel proprio tenant e abilita la crittografia con chiavi gestite dal cliente (CMK) utilizzando un'applicazione Microsoft Entra multi-tenant.

In questa configurazione, il cliente usa Azure Key Vault nel proprio tenant per gestire la chiave di crittografia. Il provider di servizi non ha accesso a questa chiave.

Prerequisiti

• Tenant A: un tenant e le autorizzazioni necessarie per creare il servizio Azure AI Search e gli oggetti associati (indici, elenchi sinonimi, indicizzatori, origini dati, vettori, set di competenze). Il supporto per le chiavi gestite dal cliente richiede un piano tariffario Basic o superiore.

• Configurare il servizio di ricerca per l'accesso basato sui ruoli (consigliato per la sicurezza avanzata, non obbligatorio).

• Tenant B: Un tenant del cliente separato con un Azure Key Vault e le autorizzazioni necessarie per tale tenant:

  • Collaboratore di Key Vault: Questo ruolo è necessario se è necessario creare un nuovo key vault.
  • Autorizzazione per registrare applicazioni in Microsoft Entra ID: per installare l'app multi-tenant configurata dal provider di servizi per CMK cross-tenant, è necessario disporre dell'autorizzazione per creare registrazioni delle applicazioni in Microsoft Entra ID. Questo richiede in genere il ruolo Sviluppatore di applicazioni o un ruolo amministrativo superiore, ad esempio Amministratore applicazioni o Amministratore globale.
  • Key Vault Crypto Officer: questo ruolo è necessario per aggiungere una nuova chiave al key vault.
  • Servizio di crittografia Key Vault - Utente: Questo ruolo deve essere assegnato al soggetto di servizio creato per l'applicazione multitenant installata, al fine di consentire al soggetto di servizio di accedere alla chiave gestita dal cliente nel Key Vault. Per eseguire questa operazione, è necessario disporre dell'autorizzazione Amministratore accesso utenti . È possibile visualizzare il GUID dell'entità di servizio (noto anche come ID oggetto) in: Enterprise applications\<installed multitenant application>\Manage\Properties\Object ID.

• Il Azure Key Vault deve anche essere configurato per l'accesso basato sui ruoli.

• interfaccia della riga di comando di Azure per l'invio di richieste.

Scegliere un approccio di autenticazione

È possibile configurare un'applicazione multi-tenant Microsoft Entra per l'uso di chiavi gestite dal cliente in uno scenario tra tenant usando uno degli approcci seguenti:

1. Supporto per l'identità federata (anteprima, opzione consigliata): Configurare le credenziali di identità federata (FIC) di Microsoft Entra con un'identità gestita assegnata dall'utente (UAMI). Questo approccio utilizza token di identità gestiti e li scambia con token di accesso, eliminando la necessità di credenziali a lunga durata e allineandosi ai principi della federazione delle identità dei carichi di lavoro. Questo approccio richiede la proprietà di anteprima federatedIdentityClientId , introdotta nella versione 2026-05-01-previewdell'API .

2. Segreti client: configurare un segreto client usando la accessCredentials proprietà . Questo approccio è meno sicuro e richiede attività di gestione aggiuntive per eseguire la rotazione e proteggere il segreto.

Creare un'applicazione Microsoft Entra multi-tenant nel tenant A

Usare l'interfaccia della riga di comando di Azure per inviare richieste. Il tenant del provider di servizi che contiene Azure AI Search verrà definito tenant A.

1. Ottieni l'ID del tenant: az account show --query tenantId --output tsv

2. Assicurarsi di aver eseguito l'accesso al tenant A: az login --tenant \<tenant-A-id\>

3. Creare la registrazione dell'applicazione: az ad app create --display-name cross-tenant-auth --sign-in-audience AzureADMultipleOrgs

4. Salvare l'output dell'ID app di questo passaggio.

Usa il supporto per le identità federate (anteprima)

Per utilizzare l'identità federata a supporto di uno scenario CMK tra tenant:

1. Il fornitore di servizi configura il servizio di ricerca basato sull'intelligenza artificiale nel proprio tenant (Tenant A). Per indicazioni su come eseguire questa operazione, vedere Creare un servizio di ricerca (nel portale di Azure) o usare il comando az search service create comando in interfaccia della riga di comando di Azure.

2. Il fornitore di servizi crea una registrazione di un'app Microsoft Entra multi-tenant. Per indicazioni su come eseguire questa operazione, vedere Come registrare un'app in Microsoft Entra ID oppure usare il comando interfaccia della riga di comando di Azure: az ad app create. Registrare l'ID applicazione (client) dopo aver completato la registrazione dell'app.

3. Il provider di servizi configura un'identità gestita assegnata dall'utente. Per indicazioni su come eseguire questa operazione, vedere Gestire le identità gestite assegnate dall'utente tramite il portale di Azure o Gestire le identità gestite assegnate dall'utente usando il interfaccia della riga di comando di Azure.

4. Il provider di servizi configura le identità gestite assegnate dall'utente come credenziali di identità federate nell'app. Per indicazioni su come eseguire questa operazione, vedere Configurare un'app per considerare attendibile un provider di identità esterno.

5. Dopo che il fornitore di servizi condivide l'ID dell'app multi-tenant, il cliente concede all'app del fornitore di servizi l'accesso al Key Vault nel proprio tenant (Tenant B). Per installare l'app nel Tenant B, è necessario creare un entità di servizio utilizzando l'ID dell'app multitenant. Per creare l'entità di servizio, creare un URL admin-consent e concedere il consenso a livello di tenant oppure utilizzare il comando az ad sp in interfaccia della riga di comando di Azure.

6. Se il cliente non ha già un insieme di credenziali delle chiavi da usare, vedere Avvio rapido : Creare un Azure Key Vault con il portale di Azure o Avvio rapido - Creare un Azure Key Vault con il interfaccia della riga di comando di Azure. Key Vault dovrà avere il modello di autorizzazioni impostato su "controllo degli accessi in base al ruolo di Azure (RBAC)", con l'autorizzazione concessa all'applicazione multitenant del provider di servizi tramite l'assegnazione del ruolo Key Vault Crypto Service Encryption User. Il cliente può quindi creare una chiave di crittografia. Per indicazioni su come eseguire questa operazione, vedi Concedere alle applicazioni l'autorizzazione per accedere a un insieme di credenziali delle chiavi di Azure usando RBAC di Azure.

Al termine di questi passaggi, il provider di servizi ha ora:

• Un ID di applicazione per un'applicazione multitenant installata nel tenant del cliente, alla quale è stato concesso l'accesso alla chiave gestita dal cliente.

• Identità gestita configurata come credenziale federata nell'applicazione multi-tenant.

• La posizione della chiave nell'insieme di credenziali delle chiavi del cliente.

Con questi tre parametri, il provider di servizi può ora creare oggetti Azure AI Search in Tenant A che possono essere crittografati con la chiave gestita dal cliente archiviata in Tenant B. Per indicazioni su come configurare chiavi gestite dal cliente in nuovi oggetti di ricerca, vedere Configurare le chiavi gestite dal cliente per Azure AI Search dati crittografati.

Verifica della configurazione CMK per l'identità federata tra tenant

Dopo aver configurato l'applicazione Microsoft Entra multi-tenant e connetterla al Key Vault del cliente, verificare la configurazione creando un oggetto test nel servizio di ricerca (tenant A). In questo esempio viene creato un indice per verificare che il servizio di ricerca possa accedere alla chiave gestita dal cliente usando l'autenticazione basata su identità federata.

1. Vedere Configurare le chiavi gestite dal cliente per Azure AI Search dati crittografati per indicazioni su come creare un servizio di ricerca e un nuovo oggetto indice con una chiave gestita dal cliente.

2. Dopo aver creato l'oggetto index, è necessario compilare quanto segue:

   • keyVaultUri: indirizzo URI del cliente.
   • keyVaultKeyName: nome della chiave del cliente.
   • keyVaultKeyVersion: versione della chiave fornita dal cliente.
   • userAssignedIdentity: I tag <subscription-id> e <resource-group> provengono dal tuo tenant, mentre <identity-name> è il nome dell'identità gestita assegnato dall'utente.
   • federatedIdentityClientId: Questo valore della proprietà, <application-client-id>, sarà l'ID dell'applicazione multi-tenant (client).

   {
     "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. Verificare l'indice inviando una GET richiesta: GET https://<search-service>.search.windows.net/indexes/cross-tenant-cmk-test?api-version=2026-08-01-preview

Se la richiesta ha esito positivo, la configurazione CMK tra tenant funziona correttamente.

Se la creazione dell'indice non riesce a causa di un errore di accesso alla chiave, verificare che:

• L'identità gestita assegnata dall'utente è configurata correttamente
• La credenziale dell'identità federata è impostata nell'app
• Il criterio di accesso di Key Vault o le assegnazioni di ruolo RBAC sono corrette

Usare un segreto del client (se l'identità federata non è un'opzione)

Se l'identità federata non è un'opzione praticabile, è possibile aggiungere un segreto client all'applicazione multitenant per supportare uno scenario CMK tra tenant:

1. Per aggiungere il segreto del client all'applicazione multitenant nel tenant A, eseguire il comando seguente:

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

2. Conservare il risultato della password derivato da questo passaggio. L'output della password è un input obbligatorio per la configurazione della chiave gestita dal client in Azure AI Search.

3. Per specificare quando scade il segreto client, è possibile specificare un parametro di data di fine per questo comando.

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

   Il parametro end-date accetta una data in formato ISO 8601. Ad esempio: az ad app credential reset --id <multitenant-app-id> --end-date 2026-12-31.

Creare un'entità servizio nel tenant B per l'applicazione multi-tenant

Il tenant contenente Azure Key Vault viene definito tenant B. Nel tenant B creare un'entità servizio per l'applicazione multi-tenant nel tenant A.

1. Accedere al tenant B:

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

2. Creare l'entità del servizio utilizzando l'output dell'ID dell'app multi-tenant del primo passaggio:

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

   Il principale servizio è un'istanza dell'applicazione multi-tenant nel tenant A. I ruoli assegnati a questo principale servizio nel tenant B vengono assegnati anche all'applicazione multi-tenant nel tenant A.

3. Verificare il collegamento tra il tenant A e B esaminando "appOwnerOrganizationId" nel comando seguente:

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

   Questo comando visualizza i dettagli dell'entità servizio in JSON. Cercare il campo "appOwnerOrganizationId" nell'output per verificare che corrisponda all'ID del tenant A.

4. Salvare l'ID oggetto dell'entità servizio (del campo "id") di questo passaggio. L'ID oggetto è un input obbligatorio per la configurazione di CMK in Ricerca di intelligenza artificiale di Azure.

5. Ottieni l'ID risorsa di Azure Key Vault:

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

6. Assegnare il ruolo Utente Crittografia del servizio Crypto dell'insieme di credenziali delle chiavi nel tenant B alla nuova entità servizio.

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

   Un esempio di questa assegnazione potrebbe essere simile al seguente:

   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

Verifica la configurazione del segreto client per le chiavi CMK condivise tra tenant

Dopo aver configurato l'applicazione Microsoft Entra multi-tenant e connetterla al Key Vault del cliente, verificare la configurazione creando un oggetto test nel servizio di ricerca (tenant A). In questo esempio viene creato un indice per verificare che il servizio di ricerca possa accedere alla chiave gestita dal cliente usando il segreto client.

1. Vedere Configurare le chiavi gestite dal cliente per Azure AI Search dati crittografati per indicazioni su come creare un servizio di ricerca e un nuovo oggetto indice con una chiave gestita dal cliente.

2. È possibile usare il portale di Azure per aggiungere un indice e fornire questo codice JSON oppure usare un client REST per inviare una richiesta /. Dopo aver creato l'oggetto index, è necessario compilare quanto segue:

   • keyVaultUri: indirizzo URI del cliente.
   • keyVaultKeyName: nome della chiave del cliente.
   • keyVaultKeyVersion: versione della chiave fornita dal cliente.
   • accessCredentials: Il applicationId è qualcosa come 00001111-aaaa-2222-bbbb-3333cccc4444, e il applicationSecret è il valore che hai appena creato.

{
  "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>"
    }
  }
}

Verificare che l'indice sia stato creato correttamente:

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

Per altre informazioni su come ruotare o gestire le chiavi, vedere Configurare chiavi gestite dal cliente per la crittografia dei dati.