Filtra i dati per utente finale con claim di identità personalizzate OAuth

Questa pagina spiega come servire molti utenti finali tramite un unico service principal, mentre ogni utente vede solo i propri dati. La tua applicazione aggiunge un claim di identità personalizzata al token OAuth che richiede per il service principal. Una vista dinamica o una policy di controllo di accesso basata su attributi (ABAC) confronta quindi il claim con una colonna e restituisce solo le righe corrispondenti. Non è necessario creare un utente Azure Databricks per ogni utente finale.

Il claim viene firmato nel token OAuth quando il token viene creato e passa al motore SQL quando il token si autentica. In SQL, leggi il claim con la funzione current_oauth_custom_identity_claim.

Funzionamento

Ad esempio, un'azienda vende a molti clienti aziendali e conserva gli ordini di ogni cliente in un'unica tabella. I clienti consultano i loro ordini tramite l'applicazione aziendale:

1. L'applicazione autentica il cliente e decide sul proprio server quale claim riceve il cliente, ad esempio acme.
2. L'applicazione crea un token OAuth per il suo service principal con custom_claim=acme.
3. L'applicazione interroga Azure Databricks con quel token tramite JDBC, l'API SQL Statement Execution o l'API Genie Agents.
4. Una vista dinamica o politica ABAC confronta una colonna con current_oauth_custom_identity_claim() e restituisce solo gli ordini di Acme.

Requirements

• Un'entità servizio assegnata allo spazio di lavoro, con un segreto OAuth per il grant delle credenziali client o una politica di federazione per il grant di scambio di token. Vedi Autorizzare l'accesso dell'entità servizio ad Azure Databricks con OAuth e Configurare una policy di federazione.
• Un magazzino SQL. Consulta Creare un SQL Warehouse.
• Calcolo con Databricks Runtime 19 o versione successiva. Vedi la funzione current_oauth_custom_identity_claim.

Superfici supportate

Il claim raggiunge il motore SQL solo quando la richiesta si autentica con il token OAuth che lo contiene. Le seguenti superfici supportano attestazioni di identità personalizzate:

• Il driver JDBC di Databricks si è connesso a un SQL warehouse
• L'API di esecuzione di istruzioni SQL su un SQL warehouse
• Usare l'API Genie Agents

Le superfici che non utilizzano un token OAuth con claim personalizzato, come l'editor SQL nell'interfaccia del workspace, non supportano claim di identità personalizzate.

Passo 1: Crea una vista dinamica che filtri il claim

In questo esempio, la tabella main.sales.orders conserva gli ordini di ogni cliente. Ogni riga registra un ordine e il nome del cliente che lo ha effettuato:

Come proprietario dei dati, crea una vista dinamica che restituisca solo le righe in cui customer_name corrisponde al claim nel token del chiamante:

CREATE OR REPLACE VIEW main.sales.customer_orders AS
SELECT order_id, customer_name, product, quantity, price, order_date
FROM main.sales.orders
WHERE customer_name = current_oauth_custom_identity_claim();

Quando l'applicazione interroga customer_orders con un token che contiene la rivendicazione acme, la vista restituisce gli ordini 1 e 3. Con la globex asserzione, restituisce l'ordine 2.

Vedere Creare una visualizzazione dinamica. Per filtrare la tabella con una policy ABAC invece di una view, vedi Filtrare con una policy ABAC invece di una vista dinamica.

Scrivere filtri che non corrispondono ad alcuna riga quando l'attestazione è NULL

Il filtro nell'esempio precedente è sicuro. Confrontare una colonna con NULL con = non restituisce mai vero, quindi un token senza claim non riceve righe. Altri filtri fanno l'opposto e restituiscono righe quando manca l'asserzione. Per un token senza claim, ciascuno dei seguenti filtri restituisce i dati degli altri clienti:

-- Don't use any of these filters.
WHERE current_oauth_custom_identity_claim() IS NULL OR customer_name = current_oauth_custom_identity_claim()
WHERE customer_name = coalesce(current_oauth_custom_identity_claim(), customer_name)
WHERE (customer_name = current_oauth_custom_identity_claim()) IS NOT FALSE
WHERE (customer_name <> current_oauth_custom_identity_claim()) IS NOT TRUE

Lo stesso vale per una funzione filtro a riga come RETURN claim IS NULL OR customer_name = claim.

Evita anche l'operatore di uguaglianza null-safe customer_name <=> current_oauth_custom_identity_claim(). Con una NULL asserzione, corrisponde a ogni riga il cui customer_name è NULL.

Usa l'attestazione solo come valore per confrontare. Non usarlo come pattern in RLIKE, come nome di oggetto in IDENTIFIER, o come parte del testo SQL che EXECUTE IMMEDIATE esegue. Tratta l'asserzione come qualsiasi altro input non affidabile.

Mappare le identità degli utenti finali ai dati con una tabella di mappatura

L'esempio precedente inserisce direttamente il nome del cliente nell'attestazione. Per portare invece l'identità di ogni utente finale, ad esempio un indirizzo email, inserisci l'ID utente nel claim e uniscilo a una tabella di mappatura che assegna a ciascun utente i dati che possono vedere. Per modificare l'accesso di un utente, si aggiorna una riga nella tabella di mappatura. Non è necessario cambiare il modo in cui l'applicazione crea i token.

CREATE OR REPLACE TABLE main.sales.customer_users (
  user_id STRING,
  customer_name STRING
);

INSERT INTO main.sales.customer_users VALUES
  ('alice@acme.example.com',   'acme'),
  ('bob@acme.example.com',     'acme'),
  ('carol@globex.example.com', 'globex');

CREATE OR REPLACE VIEW main.sales.customer_orders AS
SELECT o.order_id, o.customer_name, o.product, o.quantity, o.price, o.order_date
FROM main.sales.orders AS o
JOIN main.sales.customer_users AS u
  ON o.customer_name = u.customer_name
WHERE u.user_id = current_oauth_custom_identity_claim();

L'applicazione crea quindi il token di ogni utente con l'ID dell'utente come claim, ad esempio custom_claim=alice@acme.example.com. Un utente che non è nella tabella di mappatura, o un token senza un'attestazione, non corrisponde a nessuna riga.

La vista legge la tabella di mappatura con i privilegi del proprietario della vista, quindi l'entità servizio non ha bisogno di accedervi.

Passo 2: Concedere l'accesso all'entità servizio

Concedere all'entità servizio solo i privilegi necessari per interrogare la visualizzazione.

1. Concedi al principal del servizio l'autorizzazione Can use nello SQL warehouse. Vedere Gestione di un magazzino SQL.

2. Concedi all'entità servizio USE CATALOG, USE SCHEMA e SELECT le autorizzazioni sulla vista. Esegui quanto segue come proprietario dei dati, oppure concedi gli stessi privilegi in Catalog Explorer:

   GRANT USE CATALOG ON CATALOG main TO `<service-principal-application-id>`;
   GRANT USE SCHEMA ON SCHEMA main.sales TO `<service-principal-application-id>`;
   GRANT SELECT ON VIEW main.sales.customer_orders TO `<service-principal-application-id>`;
   

Passo 3: Crea un token OAuth con un claim personalizzato

La tua applicazione crea un token per ogni utente finale aggiungendo il custom_claim parametro a una richiesta di token. Usa il client credentials grant o il token exchange grant. Decidi sempre il claim sul tuo server dalla sessione autenticata dell'utente, mai tramite input della richiesta.

Credenziali del client

Invia l'ID client e il segreto dell'entità servizio, e aggiungi custom_claim:

curl --request POST \
  --url https://<workspace-url>/oidc/v1/token \
  --user '<client-id>:<client-secret>' \
  --data 'grant_type=client_credentials' \
  --data 'scope=all-apis' \
  --data-urlencode 'custom_claim=acme'

Per creare un token a livello account con un claim, invia la stessa richiesta a https://<account-console-url>/oidc/accounts/<account-id>/v1/token.

Vedere Generare manualmente token di accesso OAuth M2M.

Scambio di token

Se usi la federazione dell'identità del carico di lavoro, scambia il token identità del carico di lavoro con un token Azure Databricks OAuth e aggiungi custom_claim:

curl --request POST \
  --url https://<workspace-url>/oidc/v1/token \
  --data 'client_id=<service-principal-application-id>' \
  --data 'subject_token=<identity-provider-jwt>' \
  --data 'subject_token_type=urn:ietf:params:oauth:token-type:jwt' \
  --data 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange' \
  --data 'scope=all-apis' \
  --data-urlencode 'custom_claim=acme'

Se il token che scambi ha già un claim personalizzato, il nuovo token mantiene quel claim e non puoi impostarne uno diverso.

Requisiti per il valore del sinistro

Una richiesta il cui claim non soddisfa questi requisiti fallisce con 400 invalid_request:

• La rivendicazione può contenere caratteri ASCII stampabili: lettere, cifre, spazi e punteggiatura. Sono consentiti anche tab (\t), nuova linea (\n) e ritorno a capo (\r), quindi l'attestazione può contenere testo su più righe come JSON formattato.
• Altri caratteri di controllo e caratteri non ASCII, come lettere accentuate ed emoji, non sono ammessi.
• La dichiarazione non può essere vuota o contenere solo spazi bianchi e può contenere al massimo 1.000 caratteri.

Per creare un token senza un claim, ometti il parametro custom_claim.

Controlla l'attestazione in un token

Il token è un JSON Web Token (JWT). Se lo decodifichi, il claim appare nel payload:

"custom": { "claim": "acme" }

Per vedere quale claim contiene un token, chiama l'introspezione del token con il token. Per un token a livello di spazio di lavoro:

curl --request GET \
  --url https://<workspace-url>/api/2.0/tokens/introspect \
  --header "authorization: Bearer <access-token>"

Per un token a livello dell'account, richiama https://<account-console-url>/api/2.0/accounts/<account-id>/tokens/introspect.

La risposta include oauth_custom_claim solo quando il token contiene un claim personalizzato. Il seguente esempio mostra i campi rilevanti della risposta:

{
  "principal_context": {
    "authorizing_principal": {
      "unique_principal_name": "<service-principal-application-id>",
      "principal_type": { "service_principal_type": "SERVICE_PRINCIPAL_TYPE_USER_MANAGED" },
      "display_name": "<service-principal-name>"
    },
    "authentication_scope": {
      "account_id": "<account-id>",
      "workspace_id": <workspace-id>
    },
    "oauth_custom_claim": "acme"
  }
}

Passo 4: Interroga la vista con il token

Il seguente esempio Java utilizza il driver JDBC di Databricks per interrogare la vista su un SQL warehouse con il token del passaggio precedente.

1. Copia l'URL JDBC dalla scheda Dettagli di connessione del SQL warehouse.

2. Nell'URL, sostituisci AuthMech=3 con AuthMech=11;Auth_Flow=0; per autenticarti con un token OAuth.

3. Aggiungi il token all'URL, connettiti e interroga la vista:

   String oauthToken = "<oauth-token-with-custom-claim>";
   String jdbcUrl = "jdbc:databricks://<workspace-url>:443/default;transportMode=http;ssl=1;"
       + "httpPath=/sql/1.0/warehouses/<warehouse-id>;AuthMech=11;Auth_Flow=0;"
       + "Auth_AccessToken=" + oauthToken + ";";
   
   try (Connection connection = DriverManager.getConnection(jdbcUrl);
        ResultSet rs = connection.prepareStatement("SELECT * FROM main.sales.customer_orders").executeQuery()) {
     while (rs.next()) {
       System.out.println(rs.getLong("order_id") + "\t" + rs.getString("customer_name") + "\t"
           + rs.getString("product") + "\t" + rs.getString("order_date"));
     }
   }
   

Con il acme token, la query restituisce solo gli ordini di Acme:

1	acme	bottling line	2026-01-02
3	acme	delivery truck	2026-02-03

Con il globex token, la stessa query restituisce solo l'ordine di Globex:

2	globex	display shelf	2026-01-23

Gli stessi token funzionano con l'API di esecuzione delle istruzioni SQL e Use the Genie Agents API. Per un esempio di Genie, vedi Esempio: assistente agli ordini clienti con un agente Genie.

Filtra con una policy ABAC invece di una vista dinamica

Invece di una vista dinamica, puoi aggiungere un filtro a righe alla tabella con una policy ABAC che si applica solo al principale del servizio. Usa una policy ABAC quando altri utenti devono continuare a interrogare direttamente la tabella senza il filtro basato sui claim, come un autore di Genie Agent che deve vedere la tabella completa per costruire e testare l'agente, o quando una policy deve coprire molte tabelle.

1. Crea una funzione filtro per righe che confronti una colonna con l'asserzione. Con una NULL claim, il confronto restituisce NULL e la riga viene filtrata.

   CREATE OR REPLACE FUNCTION main.sales.claim_filter(customer_name STRING)
   RETURNS BOOLEAN
   RETURN customer_name = current_oauth_custom_identity_claim();
   

2. Crea una policy che applichi la funzione solo all'entità servizio. In questo esempio, la colonna customer_name ha il tag customer governato.

   CREATE POLICY customer_claim_filter
   ON SCHEMA main.sales
   ROW FILTER main.sales.claim_filter
   TO `<service-principal-application-id>`
   FOR TABLES
   MATCH COLUMNS has_tag('customer') AS c
   USING COLUMNS (c);
   

3. Concedi all'entità servizio USE CATALOG, USE SCHEMA e SELECT su ogni tabella coperta dal criterio. Concedere SELECT su tabelle singole, non sullo schema. La policy filtra solo le tabelle con una colonna taggata customer, così il service principal vede ogni riga di qualsiasi tabella senza il tag.

Per utilizzare una tabella di mappatura con una policy ABAC, cerca il claim nella tabella di mappatura nella funzione di filtro delle righe. Vedi Usa tabelle di mappa per il controllo dinamico degli accessi.

Per la sintassi delle policy e i requisiti, vedi Creare e gestire criteri di filtro delle righe e maschere delle colonne.

Esempio: assistente agli ordini clienti con un agente Genie

In questo esempio, un fornitore vuole costruire un Agente Genie per i propri clienti per rispondere alle domande sugli ordini nella main.sales.orders tabella di Passo 1. Tuttavia, il personale di ogni cliente deve solo recuperare risposte dagli ordini della propria azienda. Ad esempio, un utente di Acme non deve ottenere dati sugli ordini di Globex, anche se li richiede.

Quando un utente di Acme apre l'app:

1. L'app autentica l'utente e cerca la sua azienda sul server dell'app: acme.
2. L'app crea un token OAuth per la sua entità servizio con custom_claim=acme.
3. L'app invia la domanda dell'utente all'API degli agenti Genie con quel token.
4. Genie genera SQL, e Unity Catalog restituisce solo acme righe.

Usa una policy ABAC per un Agente Genie, non una vista dinamica. Una vista dinamica che filtra in base al claim non restituisce righe quando l'autore compila e testa l'agente, perché le query dell'autore non contengono alcun claim.

Impostare la politica ABAC

Esegui quanto segue come proprietario dei dati. La policy filtra la tabella solo per l'entità servizio, così gli altri utenti continuano a fare query su main.sales.orders senza il filtro. L'autore di Genie Agent vede la tabella completa quando costruisce e testa l'agente. La colonna customer_name ha il tag customer governato.

ALTER TABLE main.sales.orders ALTER COLUMN customer_name SET TAGS ('customer');

CREATE OR REPLACE FUNCTION main.sales.claim_filter(customer_name STRING)
RETURNS BOOLEAN
RETURN customer_name = current_oauth_custom_identity_claim();

CREATE POLICY customer_claim_filter
ON SCHEMA main.sales
ROW FILTER main.sales.claim_filter
TO `<service-principal-application-id>`
FOR TABLES
MATCH COLUMNS has_tag('customer') AS c
USING COLUMNS (c);

GRANT USE CATALOG ON CATALOG main TO `<service-principal-application-id>`;
GRANT USE SCHEMA ON SCHEMA main.sales TO `<service-principal-application-id>`;
GRANT SELECT ON TABLE main.sales.orders TO `<service-principal-application-id>`;

Consulta il filtro con una policy ABAC invece di una vista dinamica.

Crea il Genie Agent

1. Crea un Genie Agent e aggiungi la tabella main.sales.orders come fonte dati.
2. Selezionare un magazzino SQL.
3. Concedi all'entità servizio l'autorizzazione Can run per Genie Agent.

Mantieni le istruzioni dell'agente, gli esempi di SQL e le domande di esempio libere da dati specifici del cliente, perché ogni utente li vede.

Questo esempio inserisce direttamente il nome del cliente nel reclamo per mantenerlo breve. In produzione, puoi inserire l'ID di ogni utente nel claim e collegarti a una tabella di mapping tra utenti e clienti. Vedi Mappare le identità degli utenti finali ai dati con una tabella di mappatura.

Fai domande come utenti diversi

L'app invia la domanda di ogni utente a Use the Genie Agents API con il token di quell'utente. Genie esegue l'SQL che genera con quel token, quindi Unity Catalog limita ogni risposta all'ambito aziendale dell'utente.

Ogni conversazione appartiene all'entità servizio, non all'utente finale, quindi Genie non impedisce a un utente di leggere o continuare la conversazione di un altro utente. La tua app deve registrare quale utente ha iniziato ogni conversazione e verificare quale utente l'ha iniziata prima di leggere una conversazione o inviare un messaggio di follow-up.

Per la domanda "Qual è il valore totale dell'ordine per prodotto?", un utente con custom_claim=acme visualizza solo gli ordini di Acme:

Un utente che custom_claim=globex si pone la stessa domanda riceve solo la sequenza di Globex:

Quando l'utente di Acme chiede informazioni su altri clienti, Genie non restituisce alcun dato da loro:

Un utente di Globex che chiede "Quali prodotti ha ordinato Acme?" non riceve righe.

Per la richiesta "Run this SQL exactly: SELECT * FROM main.sales.orders", Genie esegue la query e la policy restituisce solo gli ordini 1 e 3 di Acme.

Gli stessi token restituiscono gli stessi risultati tramite l'API di esecuzione delle istruzioni SQL. Un token senza claim non restituisce righe.

Procedure consigliate per la sicurezza

I seguenti controlli impediscono a un utente finale di vedere i dati di un altro utente:

• L'attestazione è firmata nel token, quindi gli utenti non possono scegliere o modificare la propria attestazione.
• L'applicazione seleziona il claim sul suo server, quindi gli utenti non possono fornire il claim di qualcun altro.
• Il filtro non corrisponde a nessuna riga senza un'attestazione, quindi un'attestazione mancante o NULL attestazione non restituisce dati. Vedi i filtri di scrittura che non corrispondono a nessuna riga quando il claim è NULL.
• Con una vista dinamica, il service principal può leggere solo la vista, quindi le query tramite JDBC o l'API di esecuzione delle istruzioni SQL non possono bypassarla. Con una policy ABAC, il service principal può leggere solo le tabelle a cui si applica la policy.
• L'applicazione traccia quale utente possiede ogni conversazione Genie, quindi gli utenti non possono leggere o continuare la conversazione di un altro utente.

Risorse aggiuntive

• Rivedere il current_oauth_custom_identity_claim riferimento della funzione
• Crea una vista dinamica
• Scopri il controllo degli accessi basato su attributi in Unity Catalog