Tutorial: Limita l'accesso di un agente AI con RBAC

Utilizzare il controllo di accesso basato sui ruoli (RBAC) per limitare l'accesso di un agente AI ai dati e alle risorse di cui ha bisogno per un compito specifico. Fornisci all'agente un token OAuth limitato a un ruolo. Le richieste effettuate con quel token utilizzano i permessi del ruolo invece dei permessi più ampi dell'utente o dell'entità servizio che si autentica.

Scenario

Un agente di supporto AI ha bisogno di riassunti dei ticket e stato, ma non di dettagli di contatto del cliente contenenti informazioni personali identificabili (PII). La sua entità servizio di autenticazione ha un accesso più ampio e può leggere entrambi i dataset.

In questo esempio, lo support.tickets schema contiene riassunti dei ticket e stato senza dati personali del cliente. I dati di contatto dei clienti sono memorizzati separatamente in support.customers.contact_details.

Tu crei role-support-agent, gli concedi accesso in lettura a support.tickets, e concedi all'entità servizio l'autorizzazione Assume su di esso. Con un token limitato a quel ruolo, l'agente può leggere i ticket di supporto ma non può accedere ai dati di contatto dei clienti.

Il ruolo può ereditare privilegi di dati dai gruppi genitori e le autorizzazioni di catalogo o schema possono applicarsi a tutte le tabelle sottostanti. Per questo esempio, verifica che quelle autorizzazioni non diano al ruolo accesso alla tabella dei contatti clienti. Vedere Ereditarietà dei privilegi. Modificare i grant condivisi influisce su altri utenti e ruoli, quindi usa uno spazio di lavoro di test invece di rimuovere l'accesso agli altri utenti.

Questo tutorial è per agenti personalizzati, auto-ospitati o di terze parti che accettano un token di accesso OAuth che fornisci tu. Per gli agenti distribuiti sulle app Databricks, usa l'app integrata o l'autorizzazione utente. Vedere Autenticazione per gli agenti.

Prerequisites

• Un workspace abilitato a Unity Catalog con RBAC abilitato. Vedere Abilita RBAC.
• Permessi di amministratore account o di amministratore dello spazio di lavoro per creare il ruolo, concedere il permesso Assume e assegnarlo allo spazio di lavoro. Vedere Chi può gestire i gruppi?.
• Proprietà di, o MANAGE in, il catalogo support.
• autorizzazioni di amministratore del workspace o autorizzazione "Può gestire" per il SQL warehouse usato nell'esempio.
• Tabelle esistenti support.tickets.open_cases e support.customers.contact_details. Usa dati di test fittizi e sostituisci i tuoi nomi se necessario.
• Un service principal assegnato allo spazio di lavoro, con accesso SQL Databricks, può essere utilizzato nel warehouse e permette di interrogare entrambe le tabelle. Serve un segreto OAuth che consenta l'ambito sql per l'autenticazione machine-to-machine (M2M). Vedere Passaggio 1: Creare un segreto OAuth.
• curl In un ambiente affidabile dove puoi richiedere e testare i token.
• Un lettore di audit con accesso a system.access.audit per verificare l'attività dell'agente nell'ambito del ruolo. Vedi Verifica attribuzione dell'audit.

Usa un Azure Databricks managed service principal per questo esempio OAuth M2M. Le entità servizio gestite di Microsoft Entra ID utilizzano una configurazione di autenticazione diversa. Consulta Autorizzare l'accesso del principale del servizio ad Azure Databricks con OAuth.

Passaggio 1: Creare il ruolo

Per questo tutorial, crea un gruppo di accesso vuoto che funga da ruolo.

Console dell'account

1. Accedere alla console dell'account come amministratore dell'account.
2. Nella barra laterale, fare clic su Gestione utenti.
3. Nella scheda Gruppi fare clic su Aggiungi gruppo.
4. Inserisci role-support-agent. Non aggiungere membri.
5. Cliccare Conferma.
6. Assegna il gruppo allo spazio di lavoro con accesso SQL di Databricks. Vedere Assegnare un gruppo a un'area di lavoro.

Impostazioni dell’amministratore dell’area di lavoro

1. Come amministratore dello spazio di lavoro, accedi allo spazio di test.
2. Fare clic sul nome utente nella barra superiore e selezionare Impostazioni.
3. Fare clic sulla scheda Identità e accesso .
4. Accanto a Gruppi, fare clic su Gestisci.
5. Clicca su Aggiungi gruppo, poi Aggiungi nuovo.
6. Inserisci role-support-agent e seleziona accesso SQL a Databricks.
7. Fare clic su Aggiungi. Non aggiungere membri.

Questo assegna anche il gruppo allo spazio di lavoro e ti concede l'autorizzazione Gestisci su di esso.

Il diritto di accesso SQL di Databricks concede l'accesso alle funzionalità SQL di Databricks, inclusi dashboard, query e warehouse SQL. L'esempio utilizza query SQL. Se il tuo agente ha bisogno anche di funzionalità chiave dello spazio di lavoro come notebook, job, modelli o pipeline, concedi l'accesso allo spazio di lavoro. Vedere Diritti di accesso. Configura i privilegi dei dati e i permessi del warehouse nel Passo 2.

In questo esempio, concedi il permesso Assume separatamente invece di aggiungere il service principal come membro. L'appartenenza aggiunge anche i permessi del gruppo all'identità stessa dell'entità servizio.

Passo 2: Concedere al ruolo l'accesso ai ticket di supporto

Come proprietario del catalogo o utente con MANAGE su support, esegui:

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

Come amministratore di workspace o utente con l'autorizzazione 'Può gestire' per il warehouse, concedi al ruolo l'accesso al warehouse:

1. Nella barra laterale dello spazio di lavoro, clicca su SQL Warehouses.
2. Clicca nel menu Kebab accanto al magazzino, poi clicca su Permessi.
3. Aggiungi role-support-agent con Utilizzabile.

La concessione a livello SELECT di schema si applica a tutte le tabelle e viste attuali e future in support.tickets. Non concede l'accesso a support.customers o ad altri schemi. Per limitare il ruolo a una sola tabella, concedi SELECT su quella tabella invece. Consulta Gestione dei privilegi in Unity Catalog.

Passo 3: Concedere l'autorizzazione ad assumere un ruolo

Concedere al service principal l'autorizzazione Assume utilizzando uno dei due metodi:

Console dell'account

1. Come amministratore account, apri la console account e clicca su Gestione utenti.
2. Nella scheda Gruppi , clicca role-support-agentsu .
3. Clicca sulla scheda Permessi, poi fai clic su Concedi accesso.
4. Cerca e seleziona il service principal, seleziona Assume e clicca su Salva.

Impostazioni dell’amministratore dell’area di lavoro

1. Come amministratore dello spazio di lavoro con il permesso di Gestione sul ruolo, apri Impostazioni>Identità e accesso dallo spazio di test.
2. Accanto a Gruppi, clicca su Gestisci, poi seleziona role-support-agent.
3. Clicca su Permessi, poi Concedi accesso.
4. Cerca e seleziona l'entità servizio, seleziona Assumi identità e clicca su Salva.

Passo 4: Richiedi un token con ambito di ruolo

Nel tuo ambiente di richiesta token affidabile, imposta queste variabili di ambiente:

• DATABRICKS_HOST: l'URL dello spazio di lavoro, inclusa https:// e senza uno slash finale.
• CLIENT_ID e CLIENT_SECRET: l'ID dell'applicazione del principale del servizio e il segreto OAuth.
• ROLE_GROUP_ID: l'ID numerico di role-support-agent. Un amministratore dell'account può trovarlo alla fine dell'URL del gruppo nella console dell'account. Gli amministratori di account, gli amministratori di spazi di lavoro e i group manager possono anche recuperare del gruppo id utilizzando l'API Account Groups.
• DATABRICKS_SQL_WAREHOUSE_ID: l'ID del magazzino assegnato nel Passo 2. Segue /sql/1.0/warehouses/ nel percorso HTTP del warehouse. Vedi Ottieni i dettagli di connessione per una risorsa di calcolo di Azure Databricks.

Richiedi un token a livello di workspace con il assume_group parametro e l'ambito sql OAuth. Lo scope limita il token alle API SQL. I privilegi dati del ruolo determinano quali tabelle può interrogare. Vedi segreti OAuth con ambito definito.

Per richiedere il token, esegui:

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"

Imposta DATABRICKS_TOKEN sul valore access_token della risposta. Usa il expires_in valore per determinare quando richiedere una sostituzione. Le richieste di token a livello di account non supportano assume_group. Vedi Assumere un ruolo.

Passo 5: Verifica l'accesso del token

Esegui questi controlli nell'ambiente affidabile prima di fornire il token all'agente.

Per prima cosa, stabilisci una baseline con un token per l'identità dell'entità servizio. Ripeti la richiesta nello Step 4 senza il parametro assume_group e imposta temporaneamente DATABRICKS_TOKEN su quel token. Esegui entrambe le query in questo passaggio e verifica che abbiano successo. Poi reimposta DATABRICKS_TOKEN sul token con ambito di ruolo e ripeti i controlli.

Leggi i ticket di supporto

Esegui questa richiesta con il token con ambito di ruolo:

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

La query ha successo perché il ruolo può leggere support.tickets. Controlla che la risposta status.state sia SUCCEEDED. Se è PENDING o RUNNING, usa il statement_id restituito per recuperare il risultato con lo stesso token:

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

Vedi API di esecuzione delle istruzioni: Esegui SQL su warehouse per lo stato delle istruzioni e la gestione dei risultati.

Controlla che l'accesso alle PII dei clienti sia negato

Utilizzando lo stesso token e warehouse con scopo di ruolo, esegui:

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

Se l'istruzione è ancora in corso, recupera il risultato come descritto nella sezione precedente. La query fallisce con un errore di permesso in status.error, anche se riesce con il token del principale del servizio. Una risposta di successo HTTP da sola non significa che la query abbia avuto successo. Una tabella mancante, un token scaduto o un errore di warehouse non dimostrano che i privilegi sui dati del ruolo siano configurati correttamente.

Controlla l'attribuzione dell'audit

Utilizza un lettore di audit con l'accesso descritto in Verifica attribuzione di audit. Ispezionare gli eventi di query di test in system.access.audit: identity_metadata.run_as identifica il ruolo autorizzante, run_as_display_name contiene role-support-agent, e run_by identifica il service principal che ha avviato la richiesta. I dati di audit vengono aggiornati durante la giornata, quindi un evento recente potrebbe non apparire immediatamente. Vedi il riferimento sui metadati dell'identità.

Passo 6: Configura l'agente

Configura il client Azure Databricks dell'agente con l'URL dello spazio di lavoro e il token verificato con ambito di ruolo. Fornisci solo quel token all'agente, non il segreto OAuth dell'entità servizio o il suo token senza ambito. Il token con ambito di ruolo limita le richieste effettuate con quel token. Non rimuove i permessi del service principal in altre sessioni.

Per un agente che utilizza l'SDK Databricks per Python, imposta DATABRICKS_HOST e DATABRICKS_TOKEN nell'ambiente dell'agente, poi inizializza il client:

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

L'SDK legge il token dall'ambiente utilizzando l'autenticazione unificata. Fornire un token di accesso non fornisce all'SDK le credenziali necessarie per richiedere un nuovo token. Per un agente di lunga durata, organizza che un componente affidabile richieda e fornisca un token sostitutivo con ambito di ruolo prima che il token scada.

Opzionale: Usa l'identità di uno sviluppatore

Per i test locali con autenticazione utente-macchina (U2M), concedere a uno sviluppatore partecipante il permesso Assume su role-support-agent come nel Passo 3. Lo sviluppatore installa la CLI Databricks come descritto in Installa o aggiorna la CLI Databricks, poi si autentica usando il proprio login e un profilo separato:

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

Lo sviluppatore seleziona role-support-agent sotto Autorizza come.. nel browser e clicca su Continua, quindi recupera il token per quel profilo:

databricks auth token --profile support-agent

Lo sviluppatore utilizza l'elemento restituito access_token come DATABRICKS_TOKEN per i controlli di query con ambito di ruolo nello Step 5. Gli eventi di audit per queste richieste identificano lo sviluppatore come run_by. Il token restituito dalla CLI Databricks scade. Lo sviluppatore recupera un token nuovo quando necessario. Vedi API (token di accesso OAuth).

Pulizia

Per un test temporaneo, rimuovi la configurazione del token dell'agente e revoca l'autorizzazione per il permesso Assume creata per il test al termine. Prima di eliminare il ruolo, verifica se possiede asset o se è utilizzato da altri carichi di lavoro.

Passaggi successivi

Risorsa	Description
Limitazioni del controllo degli accessi in base al ruolo	Controlla quali caratteristiche non sono supportate o si comportano diversamente quando si interpreta un ruolo.
Cambiare i ruoli RBAC	Usa altri metodi supportati per assumere il ruolo.