Konfigurowanie kluczy zarządzanych przez klienta w różnych dzierżawach

Note

Foundry IQ (Wyszukiwanie AI platformy Azure) udostępnia bezpośrednie interfejsy API indeksowania i zapytań, a także interfejsy API wyższego poziomu dla źródeł wiedzy i baz wiedzy do zarządzanego pobierania. Użyj portalu Azure, interfejsów API REST lub Azure SDKs, aby skonfigurować te możliwości lub połączyć agentów z bazami wiedzy w portalu Microsoft Foundry.

Jako niezależny dostawca oprogramowania (ISV) tworzący wielodostępne aplikacje SaaS, możesz zapewnić klientom zaufanie do ochrony danych za pomocą kontroli nad kluczami szyfrowania. Hostujesz usługę IQ (Wyszukiwanie AI platformy Azure) w dzierżawie Microsoft Entra, podczas gdy klient zarządza swoim kluczem w Azure Key Vault we własnej dzierżawie. Mogą one odwołać dostęp do klucza, aby zablokować dostęp do zaszyfrowanych danych. Użyj wielodostępnej aplikacji Microsoft Entra, aby włączyć szyfrowanie klucza zarządzanego przez klienta (CMK) w tych dzierżawach bez udzielania kont użytkowników bezpośredniego dostępu do klucza.

Wymagania wstępne

  • Dzierżawa A: dzierżawa i niezbędne uprawnienia do tworzenia usługi IQ usługi Foundry i skojarzonych obiektów (indeksy, listy synonimów, indeksatory, źródła danych, wektoryzatory, zestawy umiejętności). Obsługa kluczy zarządzanych przez klienta wymaga warstwy cenowej Podstawowa lub nowsza.

  • Skonfiguruj usługę IQ usługi Foundry pod kątem dostępu opartego na rolach (zalecane w przypadku zwiększonych zabezpieczeń, które nie są wymagane).

  • Dzierżawa B: Oddzielna dzierżawa klienta z Azure Key Vault i uprawnieniami niezbędnymi dla tej dzierżawy:

  • Azure Key Vault musi być również konfigurowany dla dostępu opartego na rolach.

  • Azure CLI do wysyłania żądań.

Wybieranie podejścia do uwierzytelniania

Możesz skonfigurować aplikację Microsoft Entra z obsługą wielu dzierżaw tak, aby używała kluczy zarządzanych przez klienta w scenariuszu międzydzierżawnym, stosując jedno z następujących podejść:

  1. Obsługa tożsamości federacyjnej (zalecane): Skonfiguruj poświadczenia tożsamości federacyjnej (FIC) w usłudze Microsoft Entra przy użyciu tożsamości zarządzanej przypisanej przez użytkownika (UAMI). To podejście wykorzystuje tokeny tożsamości zarządzanej i wymienia je na tokeny dostępu, eliminując potrzebę stosowania długotrwałych sekretów i zapewniając zgodność z zasadami federacji tożsamości obciążeń. Takie podejście wymaga właściwości 2026-10-01, która jest ogólnie dostępna, począwszy od wersji federatedIdentityClientId interfejsu API płaszczyzny danych.

  2. Klucze tajne klienta: Skonfiguruj klucz tajny klienta za pomocą właściwości accessCredentials. Takie podejście jest mniej bezpieczne i wymaga dodatkowego zarządzania w celu rotowania i ochrony sekretu.

Aby uzyskać informacje o konfiguracji zarządzanego modułu HSM Azure Key Vault, zobacz Konfigurowanie kluczy zarządzanych przez klienta dla zaszyfrowanych danych IQ usługi Foundry.

Tworzenie wielodostępnej aplikacji Firmy Microsoft Entra w dzierżawie A

Wysyłanie żądań przy użyciu interfejsu wiersza polecenia platformy Azure. Tenant dostawcy usług zawierający Foundry IQ będzie określany jako tenant A.

  1. Pobierz identyfikator dzierżawy: az account show --query tenantId --output tsv

  2. Upewnij się, że jesteś zalogowany(-a) do dzierżawy A: az login --tenant <tenant-A-id>

  3. Utwórz rejestrację aplikacji: az ad app create --display-name cross-tenant-auth --sign-in-audience AzureADMultipleOrgs

  4. Zapisz dane wyjściowe identyfikatora aplikacji z tego kroku.

Korzystanie z obsługi tożsamości federacyjnej

Aby używać tożsamości federacyjnej na potrzeby scenariusza CMK między dzierżawcami:

  1. Dostawca usług konfiguruje usługę Foundry IQ w swojej dzierżawie (dzierżawie A). Aby uzyskać wskazówki dotyczące tego, jak to zrobić, zobacz Create a Foundry IQ service (w portalu Azure) lub użyj polecenia az search service create w Azure CLI.

  2. Dostawca usług używa wielodostępnej rejestracji aplikacji Microsoft Entra utworzonej w dzierżawie A. Zanotuj jej identyfikator aplikacji (klienta).

  3. Dostawca usług konfiguruje tożsamość zarządzaną przypisaną przez użytkownika i przypisuje ją do usługi Foundry IQ. Aby uzyskać wskazówki dotyczące tego, jak to zrobić, zobacz Tworzenie tożsamości zarządzanej przypisanej przez użytkownika.

  4. Dostawca usług konfiguruje w aplikacji tożsamość zarządzaną przypisaną przez użytkownika jako poświadczenie tożsamości federacyjnej. Wskazówki dotyczące tej procedury można znaleźć w artykule Konfigurowanie aplikacji tak, aby ufała tożsamości zarządzanej.

  5. Gdy dostawca usług udostępni identyfikator aplikacji wielodostępnej, klient nadaje aplikacji dostawcy usług dostęp do usługi Key Vault w swojej dzierżawie (dzierżawa B). Aby zainstalować aplikację w dzierżawie B, należy utworzyć nazwę główną usługi przy użyciu identyfikatora aplikacji wielodzierżawnej. Aby utworzyć jednostkę usługi, skonstruuj admin-consent URL i udziel zgody dla całej dzierżawy lub użyj polecenia az ad sp w Azure CLI.

  6. Jeśli klient nie ma jeszcze magazynu kluczy do użycia, zobacz Szybki start — tworzenie Azure Key Vault przy użyciu portalu Azure lub przewodnika Szybki start — tworzenie Azure Key Vault przy użyciu Azure CLI. Magazyn kluczy będzie wymagać ustawienia modelu uprawnień na „Kontrola dostępu oparta na rolach platformy Azure (RBAC)” oraz przyznania uprawnień wielodostępnej aplikacji dostawcy usług przez przypisanie jej roli Key Vault Crypto Service Encryption User. Klient może następnie utworzyć klucz szyfrowania. Aby uzyskać wskazówki, jak to zrobić, zobacz Przyznawanie aplikacjom uprawnień dostępu do usługi Azure Key Vault przy użyciu kontroli dostępu opartej na rolach platformy Azure (Azure RBAC).

Po wykonaniu tych kroków dostawca usług ma teraz następujące elementy:

  • Identyfikator aplikacji dla aplikacji wielodostępnej zainstalowanej w dzierżawie klienta, której udzielono dostępu do klucza zarządzanego przez klienta.

  • Tożsamość zarządzana skonfigurowana jako poświadczenie federacyjne w aplikacji wielodzierżawnej.

  • Lokalizacja klucza w sejfie kluczy klienta.

Dzięki tym trzem parametrom dostawca usług może teraz utworzyć obiekty IQ usługi Foundry w dzierżawie A , które mogą być szyfrowane przy użyciu klucza zarządzanego przez klienta przechowywanego w dzierżawie B. Aby uzyskać wskazówki dotyczące konfigurowania kluczy zarządzanych przez klienta na nowych obiektach wyszukiwania, zobacz Konfigurowanie kluczy zarządzanych przez klienta dla zaszyfrowanych danych usługi Foundry IQ.

Zweryfikuj konfigurację klucza zarządzanego przez klienta (CMK) dla federacyjnej tożsamości między dzierżawami

Po skonfigurowaniu wielodzierżawnej aplikacji Microsoft Entra i połączeniu jej z Key Vault klienta sprawdź konfigurację, tworząc obiekt testowy w usłudze Foundry IQ (dzierżawa A). W tym przykładzie utworzono indeks w celu potwierdzenia, że usługa IQ rozwiązania Foundry może uzyskać dostęp do klucza zarządzanego przez klienta przy użyciu uwierzytelniania tożsamości federacyjnej.

  1. Aby uzyskać wskazówki dotyczące tworzenia usługi Foundry IQ i nowego obiektu indeksu z kluczem zarządzanym przez klienta, zobacz Konfigurowanie kluczy zarządzanych przez klienta dla zaszyfrowanych danych Foundry IQ.

  2. Przed utworzeniem indeksu wypełnij następujące wartości w konfiguracji encryptionKey :

    • keyVaultUri: adres URI od klienta.
    • keyVaultKeyName: nazwa klucza od klienta.
    • keyVaultKeyVersion: wersja klucza od klienta.
    • userAssignedIdentity: <subscription-id> i <resource-group> z dzierżawy, a <identity-name> to nazwa tożsamości zarządzanej przypisanej przez użytkownika.
    • federatedIdentityClientId: ta wartość właściwości, <application-client-id>, będzie identyfikatorem aplikacji wielodostępnej (klienta).
    {
      "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. Sprawdź indeks, wysyłając GET żądanie: GET https://<search-service>.search.windows.net/indexes/cross-tenant-cmk-test?api-version=2026-10-01

Jeśli żądanie zakończy się pomyślnie, sprawdź, czy encryptionKey zawiera oczekiwany klucz oraz konfigurację tożsamości. Ta kontrola potwierdza zapisaną konfigurację, a nie, że indeksowanie dokumentów i zapytania działają.

Jeśli tworzenie indeksu zakończy się niepowodzeniem z powodu błędu dostępu klucza, sprawdź, czy:

  • Tożsamość zarządzana przypisana przez użytkownika jest poprawnie skonfigurowana
  • Poświadczenie tożsamości federacyjnej jest ustawione w aplikacji
  • Zasady dostępu Key Vault lub przypisania ról RBAC są poprawne

Użyj klucza tajnego klienta (jeśli użycie tożsamości federacyjnej nie jest możliwe)

Jeśli tożsamość federacyjna nie wchodzi w grę, możesz dodać klucz tajny klienta do aplikacji wielodzierżawowej, aby obsługiwać scenariusz CMK między dzierżawami:

  1. Aby dodać klucz tajny klienta do aplikacji wielodostępnej w dzierżawie A, uruchom następujące polecenie:

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

    Parametr --append zachowuje istniejące poświadczenia.

  2. Zapisz dane wyjściowe hasła z tego kroku. Wynik wyjściowy hasła jest wymaganym elementem wejściowym do konfigurowania CMK w usłudze Foundry IQ.

  3. W polu --end-date określ przyszłą datę w formacie ISO 8601, dozwoloną przez zasady dzierżawy. Nie uruchamiaj ponownie polecenia resetowania poświadczeń po zapisaniu hasła.

Tworzenie jednostki usługi w dzierżawie B dla aplikacji wielodostępnej

Odwołujemy się do dzierżawy zawierającej usługę Azure Key Vault jako dzierżawę B. W dzierżawie B utwórz jednostkę usługi dla aplikacji wielodostępnej w dzierżawie A.

  1. Zaloguj się do klienta B:

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

  2. Utwórz główny element usługi, korzystając z wyniku identyfikatora aplikacji wielodostępnej uzyskanego w pierwszym kroku.

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

    Jednostka usługi reprezentuje aplikację w dzierżawie B. Po przypisaniu roli Key Vault autoryzujesz jednostkę usługi do używania klucza w dzierżawie B.

  3. Zweryfikuj połączenie między najemcą A i B, analizując „appOwnerOrganizationId” w następującej komendzie:

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

    To polecenie wyświetla szczegóły głównej usługi w formacie JSON. Wyszukaj pole "appOwnerOrganizationId" w danych wyjściowych, aby potwierdzić, że pasuje do identyfikatora dzierżawy A.

  4. Zapisz identyfikator obiektu jednostki usługi (z "id" pola) z tego kroku. Identyfikator obiektu jest wymaganym wejściem do skonfigurowania klucza zarządzanego przez klienta w usłudze Foundry IQ.

  5. Pobierz identyfikator zasobu dla usługi Azure Key Vault:

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

  6. Przypisz rolę użytkownika szyfrowania usługi Kryptograficznej usługi Key Vault w magazynie kluczy w dzierżawie B do nowej jednostki usługi.

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

    Przykład tego zadania może wyglądać w sposób następujący.

    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

Zweryfikuj konfigurację CMK między dzierżawami dla klucza tajnego klienta

Po skonfigurowaniu wielodzierżawnej aplikacji Microsoft Entra i połączeniu jej z Key Vault klienta sprawdź konfigurację, tworząc obiekt testowy w usłudze Foundry IQ (dzierżawa A). W tym przykładzie utworzono indeks w celu potwierdzenia, że usługa IQ rozwiązania Foundry może uzyskać dostęp do klucza zarządzanego przez klienta przy użyciu klucza tajnego klienta.

  1. Aby uzyskać wskazówki dotyczące tworzenia usługi Foundry IQ i nowego obiektu indeksu z kluczem zarządzanym przez klienta, zobacz Konfigurowanie kluczy zarządzanych przez klienta dla zaszyfrowanych danych Foundry IQ.

  2. Użyj klienta REST, aby wysłać Create Index żądanie. Przed utworzeniem indeksu wypełnij następujące pola:

    • keyVaultUri: adres URI od klienta.
    • keyVaultKeyName: nazwa klucza od klienta.
    • keyVaultKeyVersion: wersja klucza od klienta.
    • accessCredentials: applicationId to coś takiego jak 00001111-aaaa-2222-bbbb-3333cccc4444, a applicationSecret to wartość, którą właśnie utworzono.
{
  "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>"
    }
  }
}

Sprawdź, czy indeks został utworzony pomyślnie:

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

Odpowiedź nie zwraca wartości applicationSecret.

Aby uzyskać więcej informacji na temat obracania kluczy lub zarządzania nimi, zobacz Konfigurowanie kluczy zarządzanych przez klienta na potrzeby szyfrowania danych.