Segreti nel catalogo unity

Questa pagina descrive come creare, leggere, gestire e gestire segreti in Unity Catalog. Un segreto del catalogo Unity è un oggetto a protezione diretta che archivia materiale sensibile, ad esempio una password, un token o una chiave API. I notebook e i job possono fare riferimento al segreto senza esporne il valore nel codice.

I segreti del catalogo unity usano lo spazio dei nomi a tre livelli (catalog.schema.secret) e sono disponibili nelle aree di lavoro collegate a un metastore. I privilegi di Unity Catalog li regolano. In questo modo è possibile applicare lo stesso modello di accesso e il controllo usati per altri asset di dati ai segreti.

Funzionamento dei segreti del catalogo Unity

Un secret di Unity Catalog è un oggetto proteggibile all'interno di uno schema, con il nome completo catalog.schema.secret. Analogamente ad altri oggetti a protezione diretta di Unity Catalog, i segreti supportano l'ereditarietà dei privilegi dal catalogo e dallo schema. Per altre informazioni sugli oggetti a protezione diretta e sull'ereditarietà, vedere Informazioni di riferimento sugli oggetti a protezione diretta di Unity Catalog.

È possibile usare un segreto del catalogo Unity nei modi seguenti:

• Recuperare il valore nel codice. Con l'accesso READ SECRET, gli utenti possono recuperare un valore segreto nei notebook e nei processi usando dbutils o l'API REST di Unity Catalog. Possono quindi usarlo per eseguire l'autenticazione con sistemi esterni o per crittografare e decrittografare i dati.
• Usa il valore in un UDF Python o Scala con ambito di sessione. Vedi gli UDF con ambito di sessione.
• Usa il valore in una UDF Python di Unity Catalog. Un UDF scalare o batch dichiara ogni segreto nella sua SECRETS clausola. Vedi Python UDF.
• Usa il valore in una UDF Scala di Unity Catalog. Una UDF scalare dichiara ogni segreto nella clausola SECRETS. Vedi Scala UDFs.

Per requisiti e comportamenti dei permessi tra i tipi di UDF, vedi requisiti e permessi UDF.

Gli UDF possono utilizzare segreti gestiti da Azure Databricks o segreti supportati da un gestore di segreti esterno. Vedi Segreti esterni nel Catalogo Unity.

Requisiti e permessi UDF

I requisiti e il comportamento dei permessi variano tra gli UDF con ambito sessione e quelli del Catalogo Unity.

UDF a livello di sessione

Un UDF Python con ambito di sessione recupera un segreto con databricks.secrets.get(), e un UDF Scala con ambito di sessione ne recupera uno con com.databricks.Secrets.get(). L'accesso segreto utilizza i permessi del chiamante.

I requisiti di calcolo per l'accesso segreto dipendono dal linguaggio UDF:

• Nel calcolo serverless, il notebook o la sessione di lavoro deve utilizzare l'ambiente versione 6 o superiore per Python e UDF Scala.
• Nel calcolo classico, le UDF Python con ambito limitato alla sessione richiedono Databricks Runtime 19 o versione successiva in modalità di accesso standard o dedicata.
• Nel calcolo classico, le UDF Scala con ambito di sessione richiedono Databrick runtime 19 o superiore con modalità di accesso standard.

UDF di Unity Catalog

Scalar e Batch Unity Catalog Python UDF e scalar Unity Catalog Scala dichiarano segreti nella SECRETS clausola e devono esplicitamente impostare environment_version a 6 o superiore. Sono supportati il calcolo serverless, gli SQL warehouse serverless e il calcolo classico che esegue Databricks Runtime 19 o versioni successive con modalità di accesso standard.

I warehouse SQL Pro supportano UDF Python scalari e batch di Unity Catalog che utilizzano i segreti. I UDF Scala di Unity Catalog che utilizzano segreti non sono supportati nei pro SQL warehouse.

Per creare o sostituire una UDF che dichiara un segreto, l'entità che esegue l'istruzione deve disporre di READ SECRET sul segreto e di USE CATALOG e USE SCHEMA sul catalogo e sullo schema padre. Durante l'esecuzione, l'UDF utilizza i permessi dell'attuale proprietario della funzione. I chiamanti necessitano dei consueti privilegi di funzione, inclusi EXECUTE, ma non hanno bisogno di accesso diretto ai segreti dichiarati. Se il proprietario della funzione perde il permesso di leggere un segreto dichiarato, l'UDF fallisce.

Usa UDF con segreti abilitati nelle maschere di colonna su calcolo dedicato

Non puoi richiamare direttamente su un compute con modalità di accesso dedicato una UDF Python o Scala di Unity Catalog che usa la clausola SECRETS. Tuttavia, puoi creare una funzione SQL di Unity Catalog che chiami la UDF abilitata all’uso dei segreti e utilizzare la funzione SQL come maschera di colonna per il controllo degli accessi basato su attributi (ABAC). Quando una query viene eseguita su compute dedicato, Azure Databricks delega l'applicazione delle maschere di colonna al compute serverless. Questa eccezione si applica solo durante l'applicazione della maschera di colonna; non consente l'invocazione diretta dell'UDF con accesso ai segreti sul compute dedicato. Vedi Versioni di calcolo non supportate.

Azure Databricks archivia in forma crittografata i valori dei segreti di Unity Catalog e applica l'oscuramento dei segreti per ridurre l'esposizione accidentale negli output e nei log. Per ruotare un segreto, aggiornarne periodicamente il valore nell'interfaccia utente o con l'API REST del catalogo Unity.

Privilegi per i segreti del catalogo Unity

I privilegi seguenti regolano i segreti. È possibile concederle a livello di catalogo, schema o di singolo segreto e sono soggette all'ereditarietà dei privilegi di Unity Catalog.

Per creare un segreto in uno schema, un utente deve avere l'autorizzazione USE CATALOG ed essere proprietario dello schema oppure disporre delle autorizzazioni CREATE SECRET e USE SCHEMA per lo schema. Per informazioni su come concedere privilegi, vedere Gestire i privilegi in Unity Catalog.

Prima di iniziare

Per usare i segreti del catalogo Unity, è necessario soddisfare i requisiti seguenti:

• L'area di lavoro deve essere abilitata per Unity Catalog. Per un'introduzione, vedere Che cos'è il catalogo unity?.
• È necessario accedere ai segreti da risorse di calcolo abilitate per Unity Catalog. Azure Databricks consiglia una delle opzioni seguenti:
  • Processi e notebook serverless che utilizzano la versione 4 o successiva dell'ambiente.
  • Calcolo classico in modalità di accesso standard che esegue Databricks Runtime 17.3 LTS o versione successiva.
• Per recuperare i segreti con dbutils, la risorsa di calcolo deve usare Databricks Runtime 17.3 LTS o versione successiva, oppure un ambiente serverless versione 4 o successiva.

Creare un segreto

La creazione di un segreto richiede l'autorizzazione USE CATALOG e che tu sia proprietario dello schema oppure disponga di CREATE SECRET e USE SCHEMA per lo schema. Consulta Privilegi per i segreti di Unity Catalog.

Esploratore di cataloghi

1. Nell'area di lavoro Azure Databricks fare clic su Catalogo per aprire Esplora cataloghi.
2. Passare allo schema in cui si vuole creare il segreto.
3. Fare clic su Crea > segreto.
4. Immettere un nome e un valore. Facoltativamente, aggiungere un commento e una data di scadenza. Se un segreto scade, Esplora cataloghi visualizza un avviso.
5. Clicca su Crea.

REST API

Eseguire il comando cURL seguente usando l'endpoint /api/2.1/unity-catalog/secrets :

curl -X POST \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "catalog_name": "main",
    "schema_name": "default",
    "name": "example_secret",
    "value": "your_secret_value",
    "comment": "your secret description"
  }' \
  "$DATABRICKS_HOST/api/2.1/unity-catalog/secrets"

Leggere un segreto

Per leggere il valore di un segreto, devi disporre di READ SECRET per il segreto oppure per un catalogo o uno schema padre.

Utilità dei segreti (dbutils.secrets)

Azure Databricks consiglia di usare dbutils per leggere i segreti, perché applica l'oscuramento dei segreti. Questa opzione richiede Databricks Runtime 17.3 LTS o versione successiva o un ambiente serverless versione 4 o successiva.

# Read a specific secret
my_secret = dbutils.secrets.get(catalog="main", schema="default", key="example_secret")

Per altre informazioni, vedere Utilità segreti (dbutils.secrets)..

REST API

Per restituire il valore, impostare include_value=true e leggere il effective_value campo nella risposta:

curl -G \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  --data-urlencode "include_value=true" \
  "$DATABRICKS_HOST/api/2.1/unity-catalog/secrets/main.default.example_secret"

Usa un segreto nel tuo codice

Dopo aver letto un segreto del Catalogo Unity con dbutils.secrets.get, passa il valore restituito al codice applicativo. dbutils oscura il valore nell'output della cella e nei log, così puoi usarlo senza rivelarlo.

Il seguente esempio utilizza un segreto come token portatore per chiamare un'API esterna:

import requests

api_key = dbutils.secrets.get(catalog="main", schema="default", key="service_api_key")

response = requests.get(
    "https://api.example.com/v1/resource",
    headers={"Authorization": f"Bearer {api_key}"},
)
response.raise_for_status()

Il seguente esempio recupera un valore segreto e lo passa a dbutils.credentials.getServiceCredentialsProvider per configurare una sessione di boto3 per l'SDK AWS. Un nome di credenziale di servizio non è di per sé sensibile, quindi questo esempio ne memorizza uno in segreto solo per illustrare l'encatenamento di un valore segreto recuperato in un'altra chiamata SDK. Per maggiori informazioni sulle credenziali del servizio, vedi Usa le credenziali del servizio del Catalogo Unity per connetterti a servizi cloud esterni.

import boto3

credential_name = dbutils.secrets.get(catalog="main", schema="default", key="service_credential_name")

boto3_session = boto3.Session(
    botocore_session=dbutils.credentials.getServiceCredentialsProvider(credential_name),
    region_name="your-aws-region",
)
sm = boto3_session.client("secretsmanager")

Gestire le autorizzazioni per i segreti

Concedere CREATE SECRET a livello di catalogo o schema per controllare chi può creare segreti. Concedi READ SECRET, WRITE SECRET o REFERENCE SECRET a livello di catalogo, schema o singolo segreto per controllare l'accesso. Si applica l'ereditarietà dei privilegi. Per altre informazioni sulla concessione e la revoca dei privilegi, vedere Gestire i privilegi in Unity Catalog.

Concedere la possibilità di creare segreti

Esploratore di cataloghi

1. In Esplora cataloghi passare allo schema.

2. Fare clic sulla scheda Permessi.

3. Fare clic su "Concedi".

4. Selezionare le entità a cui concedere l'accesso e quindi selezionare CREA SEGRETO.

   Se un'entità non dispone USE SCHEMAdi , viene visualizzato un avviso che richiede di concederlo. USE SCHEMA è necessario anche per creare segreti nello schema.

5. Cliccare Conferma.

SQL

GRANT CREATE SECRET, USE SCHEMA ON SCHEMA main.default TO `user@example.com`;

REST API

Eseguire il comando cURL seguente usando l'endpoint /api/2.1/unity-catalog/permissions/schema/{schema_name} :

curl -X PATCH \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "changes": [{
      "principal": "user@example.com",
      "add": ["CREATE_SECRET", "READ_SECRET", "REFERENCE_SECRET", "WRITE_SECRET"]
    }]
  }' \
  "$DATABRICKS_HOST/api/2.1/unity-catalog/permissions/schema/{schema_name}"

Concedere l'accesso a un segreto

Esploratore di cataloghi

1. In Catalog Explorer, vai al segreto e fai clic su di esso.
2. Fare clic sulla scheda Permessi.
3. Fare clic su "Concedi".
4. Selezionare le entità e i privilegi da concedere, quindi fare clic su Conferma.

SQL

GRANT READ SECRET ON SECRET main.default.example_secret TO `user@example.com`;

REST API

Eseguire il comando cURL seguente usando l'endpoint /api/2.1/unity-catalog/permissions/secret/{catalog.schema.secret} :

curl -X PATCH \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "changes": [{
      "principal": "user@example.com",
      "add": ["READ_SECRET", "REFERENCE_SECRET", "WRITE_SECRET"]
    }]
  }' \
  "$DATABRICKS_HOST/api/2.1/unity-catalog/permissions/secret/{catalog.schema.secret}"

Elencare, aggiornare ed eliminare segreti

Elenco dei segreti

Esploratore di cataloghi

1. In Esplora cataloghi passare allo schema.
2. Nel riquadro Panoramica fare clic su Segreti per visualizzare tutti i segreti nello schema.

Utilità dei segreti (dbutils.secrets)

# List all secrets in a schema
all_secrets = dbutils.secrets.list(catalog="main", schema="default")

REST API

Usare page_size per controllare il numero di risultati per pagina. Se sono disponibili altri risultati, la risposta include un next_page_token:

curl -G \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  --data-urlencode "catalog_name=main" \
  --data-urlencode "schema_name=default" \
  --data-urlencode "page_size=100" \
  "$DATABRICKS_HOST/api/2.1/unity-catalog/secrets"

Per recuperare la pagina successiva, passa il next_page_token valore della risposta precedente come page_token parametro:

curl -G \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  --data-urlencode "catalog_name=main" \
  --data-urlencode "schema_name=default" \
  --data-urlencode "page_token=<next_page_token>" \
  "$DATABRICKS_HOST/api/2.1/unity-catalog/secrets"

Aggiornare un segreto

Per aggiornare il valore di un segreto, è necessario disporre di WRITE SECRET sul segreto.

Esploratore di cataloghi

1. In Catalog Explorer, vai allo schema e fai clic su Segreti nel riquadro Panoramica.
2. Fare clic sul segreto da aggiornare.
3. Nell'angolo in alto a destra fare clic sul menu kebab (puntini verticali) e selezionare Modifica.
4. Immettere un nuovo valore o una data di scadenza, quindi fare clic su Conferma.

REST API

Le richieste di aggiornamento richiedono il update_mask parametro . Vengono aggiornati solo i campi inclusi sia nel update_mask corpo della richiesta:

curl -X PATCH \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"value": "new_secret_value"}' \
  "$DATABRICKS_HOST/api/2.1/unity-catalog/secrets/main.default.example_secret?update_mask=*"

Elimina un segreto

Esploratore di cataloghi

1. In Catalog Explorer, vai allo schema e fai clic su Segreti nel riquadro Panoramica.
2. Fare clic sul segreto da eliminare.
3. Nell'angolo in alto a destra fare clic sul menu kebab (puntini verticali) e selezionare Elimina.
4. Immettere il nome completo del segreto, quindi fare clic su Elimina.

REST API

curl -X DELETE \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  "$DATABRICKS_HOST/api/2.1/unity-catalog/secrets/main.default.example_secret"

Eventi di audit per i segreti di Unity Catalog

La tabella di sistema system.access.audit registra gli eventi relativi ai segreti di Unity Catalog. Ad esempio, per visualizzare tutti gli eventi segreti per un utente in una data specifica, eseguire la query seguente:

SELECT * FROM system.access.audit
WHERE
  user_identity.email = "user@example.com"
  AND event_date = "2026-02-20"
  AND service_name = "unityCatalog"
  AND action_name LIKE "%Secret%";

Per ulteriori informazioni sui log di audit, consulta Riferimento della tabella di sistema dei log di audit.

Crittografare i valori dei segreti con chiavi gestite dal cliente

Per impostazione predefinita, Azure Databricks crittografa i valori dei segreti con chiavi gestite da Databricks. È invece possibile usare chiavi gestite dal cliente (CMK). Se si abilita la funzionalità del catalogo gestito crittografato da CMK e si collega una configurazione cmk all'account, Azure Databricks usa la chiave cmk per crittografare i valori dei segreti. Per altre informazioni, vedere Chiavi gestite dal cliente per il catalogo unity.

Archiviare i segreti con un gestore esterno dei segreti

Invece di Azure Databricks che memorizzi valori segreti, puoi supportare uno schema con un gestore segreto esterno così i valori rimangono nel cloud secret manager pur rimanendo governabili in Unity Catalog. AWS Secrets Manager su AWS e Azure Key Vault su Azure sono supportati. Per sapere come funzionano i segreti esterni, vedi Segreti esterni nel Catalogo Unity. Per supportare uno schema con un gestore di segreti esterno, vedi Configura segreti esterni nel Catalogo Unity.

Limitazioni

I segreti del catalogo Unity presentano le limitazioni seguenti:

• Accesso diretto limitato dai warehouse SQL. Non puoi recuperare i segreti del Catalogo Unity direttamente dai SQL warehouse. Le UDF Python scalari e batch di Unity Catalog possono accedere ai segreti dichiarati nelle clausole SECRETS nei data warehouse SQL Pro e serverless. Le UDF scalari Scala di Unity Catalog possono accedere ai segreti dichiarati solo nei warehouse SQL serverless.
• Nessuna invocazione diretta di UDF SECRETS in ambiente di calcolo dedicato. Non puoi richiamare direttamente le UDF Python scalari o batch di Unity Catalog né le UDF Scala scalari di Unity Catalog che usano la clausola SECRETS nel calcolo con modalità di accesso dedicato. Per l'eccezione della maschera di colonna, vedi Usare UDF abilitate ai segreti nelle maschere di colonna nel calcolo dedicato.
• Nessuna individuazione globale. I segreti del catalogo Unity non vengono visualizzati nella ricerca globale.
• Nessun supporto per l'autorizzazione BROWSE. BROWSE su un catalogo non si applica ai segreti di Unity Catalog. Per rendere individuabile un segreto, concedere READ SECRET o REFERENCE SECRET sul singolo segreto o il relativo schema.
• Nessuno script di init. Non è possibile usare segreti del catalogo Unity negli script init globali o cluster. Azure Databricks consiglia di usare funzionalità dedicate anziché script init, dove possibile.
• Nessun schema informativo. Le tabelle dello schema delle informazioni per i segreti non sono ancora disponibili. Usare Esplora cataloghi o l'API REST per l'individuazione.
• dbutils ambito di runtime. dbutils il recupero è supportato nei notebook e nei processi supportati da Databricks Runtime. I contesti di runtime non Databricks, ad esempio le modalità di esecuzione JAR compilate o di sviluppo remoto, non sono supportati.
• Ambito dell'API OAuth. L'API dei segreti del catalogo Unity è accessibile solo con l'ambito dell'API unity-catalog OAuth. Usare l'ambito API secrets solo per i segreti di Azure Databricks a livello di workspace.
• Limiti di quota. Fino a 100 segreti per schema e 1.000 per metastore.