Door de klant beheerde sleutels configureren voor verschillende tenants

In dit artikel wordt een scenario voor meerdere tenants beschreven waarbij een serviceprovider Azure AI Zoeken host in de eigen tenant en versleuteling met door de klant beheerde sleutels (CMK) inschakelt met behulp van een multitenant Microsoft Entra-toepassing.

In deze configuratie gebruikt de klant Azure Key Vault in hun eigen tenant om de versleutelingssleutel te beheren. De serviceprovider heeft geen toegang tot deze sleutel.

Vereiste voorwaarden

• Tenant A: Een tenant en de benodigde machtigingen voor het maken van de Azure AI Zoeken service en bijbehorende objecten (indexen, synoniemenlijsten, indexeerfuncties, gegevensbronnen, vectorizers, vaardighedensets). Voor ondersteuning voor door de klant beheerde sleutels (CMK) is een Basic-prijscategorie of hoger vereist.

• Configureer de zoekservice voor op rollen gebaseerde toegang (aanbevolen voor verbeterde beveiliging, niet vereist).

• Tenant B: Een afzonderlijke klanttenant met een Azure Key Vault en de benodigde machtigingen voor die tenant:

  • Key Vault Inzender: deze rol is vereist als u een nieuwe key vault moet maken.
  • Machtiging voor het registreren van toepassingen in Microsoft Entra ID: Als u de app met meerdere tenants wilt installeren die is geconfigureerd door de serviceprovider voor CMK voor meerdere tenants, moet u gemachtigd zijn om app-registraties te maken in Microsoft Entra ID. Hiervoor is doorgaans de rol Toepassingsontwikkelaar of een hogere beheerdersrol vereist, zoals Toepassingsbeheerder of Globale beheerder.
  • Key Vault Crypto Officer: Deze rol is vereist om een nieuwe sleutel toe te voegen aan de key vault.
  • Key Vault Crypto Service Encryption User: Deze rol moet worden toegewezen aan de service-principal die is aangemaakt voor de geïnstalleerde multitenant-applicatie, zodat de service-principal toegang krijgt tot de door de klant beheerde sleutel in de Key Vault. Hiervoor moet u beheerdersmachtigingen voor gebruikerstoegang hebben. U kunt de GUID van de service-principal (ook wel object-id genoemd) bekijken onder: Enterprise applications\<installed multitenant application>\Manage\Properties\Object ID.

• De Azure Key Vault moet ook worden geconfigureerd voor op rollen gebaseerde toegang.

• Azure CLI voor het verzenden van aanvragen.

Een verificatiemethode kiezen

U kunt een multitenant-Microsoft Entra-toepassing configureren voor het gebruik van door de klant beheerde sleutels in een scenario voor meerdere tenants met behulp van een van de volgende methoden:

1. Ondersteuning voor federatieve identiteiten (preview, aanbevolen): configureer Microsoft Entra federatieve identiteitsreferenties (FIC) met een door de gebruiker toegewezen beheerde identiteit (UAMI). Deze benadering maakt gebruik van tokens voor beheerde identiteiten en wisselt die in voor toegangstokens, waardoor er geen langdurige secrets meer nodig zijn en deze in lijn is met de principes van workload identity federation. Voor deze benadering is de preview-eigenschap federatedIdentityClientId vereist, die is geïntroduceerd in de API-versie 2026-05-01-preview.

2. Clientgeheimen: configureer een clientgeheim met behulp van de accessCredentials eigenschap. Deze aanpak is minder veilig en vereist extra beheer om het geheim regelmatig te vernieuwen en te beveiligen.

Een multi-tenant Microsoft Entra-toepassing maken in tenant A

Gebruik de Azure CLI om aanvragen te verzenden. De tenant van de serviceprovider die Azure AI Zoeken bevat, wordt tenant A genoemd.

1. Haal de tenant-id op: az account show --query tenantId --output tsv

2. Zorg ervoor dat u bent aangemeld bij tenant A: az login --tenant \<tenant-A-id\>

3. Maak de toepassingsregistratie: az ad app create --display-name cross-tenant-auth --sign-in-audience AzureADMultipleOrgs

4. Sla de uitvoer van de app-id van deze stap op.

Federatieve identiteitsondersteuning gebruiken (preview)

Federatieve identiteit gebruiken ter ondersteuning van een CMK-scenario voor meerdere tenants:

1. De dienstverlener configureert de AI Search-service in de eigen tenant (Tenant A). Zie Maak een zoekservice (in de Azure-portal) of gebruik de opdracht az search service create in Azure CLI voor meer informatie.

2. De serviceprovider maakt een multitenant Microsoft Entra app-registratie. Zie Hoe u een app registreert in Microsoft Entra ID of gebruik de opdracht Azure CLI: az ad app create voor meer informatie over hoe u dit doet. Noteer de toepassings-id (client) zodra u de app-registratie hebt voltooid.

3. De serviceprovider stelt een door de gebruiker toegewezen beheerde identiteit in. Zie Manage door de gebruiker toegewezen beheerde identiteiten met behulp van Azure portal of Manage door de gebruiker toegewezen beheerde identiteiten beheren met behulp van de Azure CLI voor meer informatie over hoe u dit doet.

4. De serviceprovider configureert de door de gebruiker toegewezen beheerde identiteiten als federatieve identiteitsreferentie in de app. Zie Een app configureren om een externe id-provider te vertrouwen voor hulp bij hoe u dit doet.

5. Zodra de serviceprovider de app-id voor meerdere tenants deelt, verleent de klant de app van de serviceprovider toegang tot de Key Vault in hun tenant (tenant B). Als u de app in Tenant B wilt installeren, moet er een service-principal worden gemaakt met de app-id voor meerdere tenants. Als u de service-principal wilt maken, maakt u een admin-consent URL en geeft u toestemming voor de hele tenant of gebruikt u de opdracht az ad sp in Azure CLI.

6. Als de klant nog geen sleutelkluis heeft om te gebruiken, raadpleegt u quickstart: een Azure Key Vault maken met de Azure-portal of quickstart: een Azure Key Vault maken met de Azure CLI. Voor de Key Vault moet het machtigingsmodel zijn ingesteld op "Azure role-based access control (RBAC)", waarbij aan de multitenant-toepassing van de serviceprovider toestemming wordt verleend door deze de rol Key Vault Crypto Service Encryption User toe te wijzen. De klant kan vervolgens een versleutelingssleutel maken. Zie Grant-machtiging voor toepassingen voor toegang tot een Azure sleutelkluis met behulp van Azure RBAC voor hulp hierover.

Zodra deze stappen zijn voltooid, heeft de serviceprovider het volgende:

• Een toepassings-id voor een toepassing met meerdere tenants die is geïnstalleerd in de tenant van de klant, die toegang heeft gekregen tot de door de klant beheerde sleutel.

• Een beheerde identiteit die is geconfigureerd als de federatieve aanmeldingsgegevens op de multitenant-toepassing.

• De locatie van de sleutel in de sleutelkluis van de klant.

Met deze drie parameters kan de serviceprovider nu Azure AI Zoeken objecten maken in Tenant A die kunnen worden versleuteld met de door de klant beheerde sleutel die is opgeslagen in Tenant B. Zie Door de klant beheerde sleutels configureren voor Azure AI Zoeken versleutelde gegevens voor hulp bij het configureren van door de klant beheerde sleutels voor nieuwe zoekobjecten.

De tenantoverschrijdende CMK-configuratie voor gefedereerde identiteit valideren

Nadat u de multitenant-Microsoft Entra-toepassing hebt geconfigureerd en deze hebt verbonden met de Key Vault van de klant, controleert u de installatie door een testobject te maken in uw zoekservice (tenant A). In dit voorbeeld wordt een index gemaakt om te bevestigen dat de zoekservice toegang heeft tot de door de klant beheerde sleutel met behulp van federatieve identiteitsverificatie.

1. Zie Door de klant beheerde sleutels configureren voor Azure AI Zoeken versleutelde gegevens voor hulp bij het maken van een zoekservice en een nieuw indexobject met een door de klant beheerde sleutel.

2. Zodra het indexobject is gemaakt, moet u het volgende invullen:

   • keyVaultUri: het URI-adres van de klant.
   • keyVaultKeyName: De sleutelnaam van de klant.
   • keyVaultKeyVersion: De sleutelversie van de klant.
   • userAssignedIdentity: De <subscription-id> en <resource-group> van uw tenant, en de <identity-name> is de naam van de door de gebruiker toegewezen beheerde identiteit.
   • federatedIdentityClientId: Deze eigenschapswaarde, <application-client-id>is de multitenant-toepassings-id (client-id).

   {
     "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. Controleer de index door een GET aanvraag te verzenden: GET https://<search-service>.search.windows.net/indexes/cross-tenant-cmk-test?api-version=2026-08-01-preview

Als de aanvraag slaagt, werkt de CMK-configuratie voor meerdere tenants correct.

Als het maken van een index mislukt met een sleuteltoegangsfout, controleert u of:

• De door de gebruiker toegewezen beheerde identiteit is correct geconfigureerd
• De federatieve identiteitsreferentie is ingesteld op de app
• Het Key Vault toegangsbeleid of RBAC-roltoewijzingen zijn correct

Een clientgeheim gebruiken (als federatieve identiteit geen optie is)

Als federatieve identiteit geen optie is, kunt u een clientgeheim toevoegen aan de multitenant-toepassing ter ondersteuning van een CMK-scenario voor meerdere tenants:

1. Voer de volgende opdracht uit om het clientgeheim toe te voegen aan de toepassing met meerdere tenants in tenant A:

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

2. Sla de wachtwoorduitvoer uit deze stap op. De wachtwoorduitvoer is een vereiste invoer voor het instellen van CMK in Azure AI Zoeken.

3. Als u wilt opgeven wanneer het clientgeheim verloopt, kunt u een einddatumparameter voor deze opdracht opgeven.

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

   De einddatumparameter accepteert een datum in ISO 8601-indeling. Voorbeeld: az ad app credential reset --id <multitenant-app-id> --end-date 2026-12-31.

Een service-principal maken in tenant B voor de multitenant-toepassing

We verwijzen naar de tenant met Azure Key Vault als tenant B. Maak in tenant B een service-principal voor de multitenant-toepassing in tenant A.

1. Meld u aan bij tenant B:

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

2. Maak de service-principal met behulp van de uitvoer van de app-id voor meerdere tenants uit de eerste stap:

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

   Deze service-principal is een exemplaar van de multitenant-toepassing in tenant A. Rollen die zijn toegewezen aan deze service-principal in tenant B, worden ook toegewezen aan de toepassing met meerdere tenants in tenant A.

3. Controleer de koppeling tussen tenant A en B door de appOwnerOrganizationId te controleren in de volgende opdracht:

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

   Met deze opdracht worden de details van de service-principal in JSON weergegeven. Zoek het veld appOwnerOrganizationId in de uitvoer om te bevestigen dat deze overeenkomt met de id van tenant A.

4. Sla de object-id van de service-principal (uit het "id" veld) uit deze stap op. De object-id is een vereiste invoer voor het instellen van CMK in Azure AI Zoeken.

5. Haal de resource-id voor Azure Key Vault op:

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

6. Wijs de rol Key Vault Crypto Service Encryption User toe op de sleutelkluis in tenant B aan de nieuwe service-principal.

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

   Een voorbeeld van deze toewijzing kan er als volgt uitzien:

   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

De clientgeheim-CMK-configuratie voor meerdere tenants valideren

Nadat u de multitenant-Microsoft Entra-toepassing hebt geconfigureerd en deze hebt verbonden met de Key Vault van de klant, controleert u de installatie door een testobject te maken in uw zoekservice (tenant A). In dit voorbeeld wordt een index gemaakt om te bevestigen dat de zoekservice toegang heeft tot de door de klant beheerde sleutel met behulp van het clientgeheim.

1. Zie Door de klant beheerde sleutels configureren voor Azure AI Zoeken versleutelde gegevens voor hulp bij het maken van een zoekservice en een nieuw indexobject met een door de klant beheerde sleutel.

2. U kunt de Azure-portal gebruiken om een index toe te voegen en deze JSON op te geven, of een REST-client gebruiken om een Create Index-aanvraag te verzenden. Zodra het indexobject is gemaakt, moet u het volgende invullen:

   • keyVaultUri: het URI-adres van de klant.
   • keyVaultKeyName: De sleutelnaam van de klant.
   • keyVaultKeyVersion: De sleutelversie van de klant.
   • accessCredentials: Het applicationId is iets als 00001111-aaaa-2222-bbbb-3333cccc4444, en de applicationSecret is de waarde die u zojuist hebt gemaakt.

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

Controleer of de index succesvol is aangemaakt.

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

Zie voor meer informatie over hoe u sleutels kunt roteren of beheren klantbeheerde sleutels configureren voor gegevensversleuteling.