Samouczek: Ogranicz zakres dostępu agenta AI za pomocą RBAC

Użyj kontroli dostępu opartej na rolach (RBAC), aby ograniczyć dostęp agenta AI do danych i zasobów potrzebnych do konkretnego zadania. Dostarcz agentowi token OAuth o zakresie uprawnień ograniczonym do roli. Żądania wykonane tym tokenem wykorzystują uprawnienia roli, a nie szersze uprawnienia uwierzytelniającego użytkownika lub podmiotu usługi.

Scenario

Agent wsparcia AI potrzebuje streszczeń zgłoszeń i statusu, ale nie danych kontaktowych klienta zawierających dane osobowe (PII). Jej uwierzytelniająca jednostka usługi ma szerszy dostęp i może odczytywać oba zbiory danych.

W tym przykładzie support.tickets schemat zawiera podsumowania zgłoszeń i status bez danych danych osobistych klientów. Dane kontaktowe klienta są przechowywane osobno w support.customers.contact_details.

Tworzysz role-support-agent, nadajesz mu uprawnienie do odczytu elementu support.tickets, a jednostce usługi przyznajesz uprawnienie Assume do niego. Mając token przypisany do tej roli, agent może czytać zgłoszenia wsparcia, ale nie ma dostępu do danych kontaktowych klienta.

Rola ta może dziedziczyć uprawnienia do danych od grup nadrzędnych, a granty katalogowe lub schematowe mogą dotyczyć wszystkich tabel poniżej nich. W tym przykładzie sprawdź, czy te granty nie dają roli dostępu do tabeli kontaktów z klientem. Zobacz Dziedziczenie uprawnień. Zmiana współdzielonych uprawnień wpływa na innych użytkowników i role, więc zamiast odbierać innym użytkownikom dostęp, korzystaj z testowej przestrzeni roboczej.

Ten samouczek jest przeznaczony dla niestandardowych, samodzielnie hostowanych lub zewnętrznych agentów, którzy akceptują token dostępu OAuth, który dostarczysz. W przypadku agentów wdrożonych w aplikacjach Databricks użyj wbudowanej aplikacji lub autoryzacji użytkownika. Zobacz Uwierzytelnianie agentów.

Prerequisites

• Przestrzeń robocza z włączonym Unity Catalog i włączonym RBAC. Zobacz Włączanie RBAC.
• Wymagane są uprawnienia administratora konta lub przestrzeni roboczej do utworzenia roli, przyznania uprawnień Assume i przypisania jej do przestrzeni roboczej. Zobacz Kto może zarządzać grupami?.
• Własność katalogu lub MANAGE w katalogu support.
• Uprawnienia administratora obszaru roboczego lub może zarządzać w magazynie SQL użytym w przykładzie.
• Istniejące tabele to support.tickets.open_cases oraz support.customers.contact_details. Używaj fikcyjnych danych testowych i w razie potrzeby podmieniaj w całym tekście swoje imiona i nazwiska.
• Do przestrzeni roboczej przypisana jest jednostka usługi z dostępem do Databricks SQL, może używać magazynu oraz ma uprawnienia do wykonywania zapytań do obu tabel. Potrzebuje sekretu OAuth, który pozwala na zakres sql dla uwierzytelniania maszyna-maszyna (M2M). Zobacz Krok 1: Utworzenie klucza tajnego OAuth.
• curl w zaufanym środowisku, gdzie możesz uzyskiwać i testować tokeny.
• Czytnik audytu z dostępem do system.access.audit, aby zweryfikować aktywność agenta w ramach roli. Zobacz Zweryfikuj atrybucję audytu.

Użyj zarządzanego service principal Azure Databricks dla tego przykładu OAuth M2M. Zarządzane jednostki usługi Microsoft Entra ID korzystają z innego systemu uwierzytelniania. Zobacz Autoryzowanie dostępu jednostki usługi do usługi Azure Databricks przy użyciu protokołu OAuth.

Krok 1. Tworzenie roli

W tym tutorialu stwórz pustą grupę kont, która posłuży jako rola.

Konsola konta

1. Jako administrator konta zaloguj się do konsoli konta.
2. Na pasku bocznym kliknij pozycję Zarządzanie użytkownikami.
3. Na karcie Grupy kliknij pozycję Dodaj grupę.
4. Wprowadź wartość role-support-agent. Nie dodawaj członków.
5. Kliknij przycisk Potwierdź.
6. Przypisz grupę do workspace z dostępem SQL Databricks. Zobacz Przypisywanie grupy do obszaru roboczego.

Ustawienia administratora obszaru roboczego

1. Jako administrator przestrzeni roboczej zaloguj się do testowej przestrzeni roboczej.
2. Kliknij swoją nazwę użytkownika na górnym pasku i wybierz pozycję Ustawienia.
3. Kliknij kartę Tożsamość i dostęp .
4. Obok pozycji Grupy kliknij pozycję Zarządzaj.
5. Kliknij Dodaj grupę, a następnie Dodaj nowe.
6. Wprowadź role-support-agent i wybierz dostęp SQL Databricks.
7. Kliknij przycisk Dodaj. Nie dodawaj członków.

To również przypisuje grupę do przestrzeni roboczej i przyznaje Ci uprawnienie Zarządzanie do niej.

Uprawnienia dostępu SQL Databricks dają dostęp do funkcji SQL Databricks, w tym pulpitów, zapytań i magazynów SQL. Przykład wykorzystuje zapytania SQL. Jeśli Twój agent potrzebuje także kluczowych funkcji workspace, takich jak notatniki, zadania, modele czy pipeline, przyznaj dostęp do Workspace. Zobacz Uprawnienia dostępu. Konfigurujesz uprawnienia danych i uprawnienia magazynu w kroku 2.

W tym przykładzie przyznajesz uprawnienie Assume osobno, zamiast dodawać jednostkę usługi jako członka. Członkostwo dodaje również uprawnienia grupy do własnej tożsamości podmiotu usługi.

Krok 2: Przyznaj roli dostęp do zgłoszeń wsparcia

Jako właściciel katalogu lub użytkownik z MANAGE na support, wykonaj:

GRANT USE CATALOG ON CATALOG support TO `role-support-agent`;
GRANT USE SCHEMA, SELECT ON SCHEMA support.tickets TO `role-support-agent`;

Jako administrator przestrzeni roboczej lub użytkownik z możliwością zarządzania magazynem przyznaj roli dostęp do magazynu:

1. W pasku bocznym przestrzeni roboczej kliknij SQL Warehouses.
2. Kliknij obok magazynu, a następnie kliknij Uprawnienia.
3. Dodaj role-support-agent z opcją Można użyć.

Grant na poziomie SELECT schematu dotyczy wszystkich obecnych i przyszłych tabel oraz widoków w support.tickets. Nie przyznaje dostępu do support.customers ani do innych schematów. Aby ograniczyć rolę do jednej tabeli, zamiast tego nadaj SELECT dla tej tabeli. Zobacz Zarządzanie uprawnieniami w Unity Catalog.

Krok 3: Udziel zgody na przyjęcie tej roli

Udziel podmiotowi głównemu usługi uprawnienia Assume za pomocą dowolnej z metod:

Konsola konta

1. Jako administrator konta otwórz konsolę konta i kliknij Zarządzanie użytkownikami.
2. Na zakładce Grupy kliknij role-support-agent.
3. Kliknij kartę Uprawnienia, a następnie kliknij Przyznaj dostęp.
4. Wyszukaj i wybierz jednostkę usługi, wybierz Przejmij i kliknij Zapisz.

Ustawienia administratora obszaru roboczego

1. Jako administrator przestrzeni roboczej z uprawnieniami do zarządzania rolą, otwórz Ustawienia>Tożsamość i dostęp w testowej przestrzeni roboczej.
2. Obok Grupy kliknij Zarządzaj, a następnie wybierz role-support-agent.
3. Kliknij Uprawnienia, a następnie Udziel dostępu.
4. Wyszukaj i wybierz jednostkę usługi, wybierz Przyjmij i kliknij Zapisz.

Krok 4: Poproś o token o zakresie roli

W zaufanym środowisku żądań tokenów ustaw następujące zmienne:

• DATABRICKS_HOST: adres URL obszaru roboczego, włącznie z https:// i bez ukośnika końcowego.
• CLIENT_ID oraz CLIENT_SECRET: identyfikator aplikacji nazwy głównej usługi oraz klucz tajny OAuth.
• ROLE_GROUP_ID: numeryczne ID elementu role-support-agent. Administrator konta może znaleźć go na końcu adresu URL grupy w konsoli konta. Administratorzy kont, administratorzy przestrzeni roboczych oraz menedżerowie grup również mogą pobierać id grupy za pomocą API Account Groups.
• DATABRICKS_SQL_WAREHOUSE_ID: identyfikator magazynu przyznany w kroku 2. Znajduje się po /sql/1.0/warehouses/ w ścieżce HTTP magazynu. Zobacz Jak uzyskać szczegóły połączenia dla zasobu obliczeniowego Azure Databricks.

Zażądaj tokenu na poziomie przestrzeni roboczej z parametrem assume_group i zakresem OAuth sql. Zakres uprawnień ogranicza token do interfejsów API SQL. Uprawnienia do danych tej roli decydują, które tabele może odpytywać. Zobacz tajemnice Scoped OAuth.

Aby uzyskać token, wykonaj:

curl --request POST \
  --url "$DATABRICKS_HOST/oidc/v1/token" \
  --user "$CLIENT_ID:$CLIENT_SECRET" \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'scope=sql' \
  --data-urlencode "assume_group=$ROLE_GROUP_ID"

Ustaw DATABRICKS_TOKEN na wartość access_token z odpowiedzi. Użyj wartości expires_in, aby określić, kiedy poprosić o wymianę. Żądania tokenów na poziomie konta nie obsługują assume_group. Zobacz Przełączanie ról.

Krok 5: Zweryfikuj dostęp do tokena

Wykonaj te kontrole w zaufanym środowisku przed przekazaniem tokena agentowi.

Najpierw ustal punkt odniesienia za pomocą tokenu dla tożsamości własnej podmiotu usługi. Powtórz żądanie w kroku 4 bez parametru assume_group i tymczasowo ustaw DATABRICKS_TOKEN na ten token. Uruchom oba zapytania w tym etapie i sprawdź, czy się powiodły. Następnie ustaw DATABRICKS_TOKEN z powrotem na token ograniczony do roli i powtórz sprawdzenia.

Wyświetl zgłoszenia pomocy technicznej

Wykonaj to żądanie za pomocą tokena o zakresie ograniczonym do roli:

curl --request POST \
  --url "$DATABRICKS_HOST/api/2.0/sql/statements" \
  --header "Authorization: Bearer $DATABRICKS_TOKEN" \
  --header 'Content-Type: application/json' \
  --data "{
    \"warehouse_id\": \"$DATABRICKS_SQL_WAREHOUSE_ID\",
    \"statement\": \"SELECT * FROM support.tickets.open_cases LIMIT 10\",
    \"wait_timeout\": \"50s\"
  }"

Zapytanie odnosi sukces, ponieważ rola może odczytać support.tickets. Sprawdź, czy status.state odpowiedzi to SUCCEEDED. Jeśli jest to PENDING lub RUNNING, użyj zwróconego statement_id, aby uzyskać wynik za pomocą tego samego tokenu:

curl --request GET \
  --url "$DATABRICKS_HOST/api/2.0/sql/statements/<statement-id>" \
  --header "Authorization: Bearer $DATABRICKS_TOKEN"

Zobacz API wykonywania instrukcji: Uruchamianie SQL w warehouse’ach dla statusu instrukcji i obsługi wyników.

Sprawdź, czy dostęp do danych osobistych klientów jest zabroniony

Używając tego samego tokena i magazynu ograniczonego do roli, uruchom:

curl --request POST \
  --url "$DATABRICKS_HOST/api/2.0/sql/statements" \
  --header "Authorization: Bearer $DATABRICKS_TOKEN" \
  --header 'Content-Type: application/json' \
  --data "{
    \"warehouse_id\": \"$DATABRICKS_SQL_WAREHOUSE_ID\",
    \"statement\": \"SELECT 1 FROM support.customers.contact_details LIMIT 1\",
    \"wait_timeout\": \"50s\"
  }"

Jeśli instrukcja nadal działa, pobierz wynik opisany w poprzedniej sekcji. Zapytanie kończy się niepowodzeniem z błędem uprawnień w status.error, choć udaje się z tokenem własnej jednostki usługi. Sama odpowiedź sukcesu HTTP nie oznacza, że zapytanie zakończyło się sukcesem. Brakująca tabela, wygasły token lub błąd hurtowni danych nie potwierdzają, że uprawnienia danych roli są poprawnie skonfigurowane.

Sprawdź atrybucję audytu

Użyj czytnika audytu z dostępem opisanym w Weryfikowanie atrybucji inspekcji. Sprawdź zdarzenia zapytania testowego w system.access.audit: identity_metadata.run_as identyfikuje rolę autoryzującą, run_as_display_name zawiera role-support-agent, oraz run_by identyfikuje jednostkę usługi, która zainicjowała żądanie. Dane audytowe są aktualizowane w ciągu dnia, więc ostatnie zdarzenie może nie pojawić się od razu. Zobacz odniesienie do metadanych tożsamości.

Krok 6: Konfiguruj agenta

Skonfiguruj klienta Azure Databricks agenta z adresem URL obszaru roboczego oraz zweryfikowanym tokenem ograniczonym do roli. Dostarcz agentowi tylko ten token, a nie sekret OAuth jednostki usługi ani jej token bez zakresu. Token w skali roli ogranicza żądania wykonywane tym tokenem. Nie usuwa uprawnień jednostki usługi w innych sesjach.

Dla agenta korzystającego z SDK Databricks dla Pythona, w środowisku agenta ustaw DATABRICKS_HOST i DATABRICKS_TOKEN, a następnie zainicjalizuj klienta:

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

SDK odczytuje token ze środowiska za pomocą ujednoliconego uwierzytelniania. Dostarczenie tokena dostępu nie daje SDK odpowiednich poświadczeń do żądania nowego tokena. Dla agenta działającego długo należy zorganizować, aby zaufany komponent zażądał i dostarczył zastępczy token ograniczony do roli, zanim token wygaśnie.

Opcjonalnie: Użyj tożsamości dewelopera

Do lokalnych testów z uwierzytelnianiem użytkownik-maszyna (U2M) udziel uczestniczącemu deweloperowi uprawnienia Assume dla role-support-agent, jak w kroku 3. Programista instaluje interfejs CLI Databricks zgodnie z opisem w Instalowanie lub aktualizowanie interfejsu CLI Databricks, a następnie uwierzytelnia się za pomocą własnego logowania i osobnego profilu:

databricks auth login --host <workspace-url> --profile support-agent

Programista wybiera role-support-agent pod Autoryzuj jako... w przeglądarce i klika Kontynuuj, a następnie pobiera token dla tego profilu:

databricks auth token --profile support-agent

Programista używa zwróconego access_token jako DATABRICKS_TOKEN do sprawdzania zapytań ograniczonych do roli w kroku 5. Zdarzenia audytowe dla tych żądań identyfikują dewelopera jako dewelopera run_by. Token zwrócony przez Databricks CLI wygasa. Deweloper zdobywa nowy token, gdy jest potrzebny. Zobacz API (tokeny dostępu OAuth).

Czyszczenie

W przypadku tymczasowego testu usuń konfigurację tokenu agenta i cofnij przyznanie uprawnienia Assume utworzonego dla testu po jego zakończeniu. Przed usunięciem roli sprawdź, czy jest ona właścicielem zasobów lub czy jest używana przez inne obciążenia robocze.

Następne kroki