Segreti nel catalogo unity

Un segreto del Catalogo Unity è un oggetto proteggibile che memorizza una credenziale sensibile, come una password, un token o una chiave API. I segreti utilizzano il namespace a tre livelli (catalog.schema.secret) e sono disponibili in ogni workspace collegato al metastore.

Governi i segreti con gli stessi privilegi del Catalogo Unity degli altri tuoi asset dati, fino al singolo segreto. Gli utenti possono visualizzare un segreto senza poterlo leggere o usare, puoi cifrare i valori segreti con la tua chiave e i log di audit registrano ogni lettura o modifica.

I segreti di Unity Catalog possono essere gestiti da Azure Databricks o archiviati in Azure Key Vault. Vedi Azure Key Vault secrets nel Catalogo Unity.

Requirements

• L'area di lavoro deve essere abilitata per Unity Catalog. Consulta Che cos'è il Catalogo Unity?.
• Per leggere i segreti con dbutils, usa notebook serverless e job sull'ambiente versione 4 e superiore, oppure il compute classico che esegue Databricks Runtime 17.3 LTS e versioni successive. Azure Databricks consiglia serverless o modalità di accesso standard.
• Per usare i segreti nelle UDF, vedi Usa i segreti nelle UDF.

Creare un segreto

I segreti risiedono negli schema. Crea segreti in uno schema a cui possono accedere solo le entità che ne hanno bisogno. Per decidere come raggruppare i segreti in schemi, vedi Raggruppare i segreti in base a chi ne ha bisogno.

Uno schema contiene segreti gestiti da Azure Databricks o segreti archiviati in Azure Key Vault, non entrambi, quindi scegli tu dove i valori vengono memorizzati quando configuri lo schema. Per uno schema supportato da Azure Key Vault, vedi Crea un segreto in uno schema supportato da Azure Key Vault.

Creare un segreto gestito da Azure Databricks

Per creare un segreto gestito da Azure Databricks, devi disporre di USE CATALOG sul catalogo e avere o la proprietà dello schema o CREATE SECRET e USE SCHEMA su di esso.

Per creare uno schema per i segreti di un'applicazione, esegui quanto segue:

CREATE SCHEMA IF NOT EXISTS main.orders_app;

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

Per creare un segreto, esegui quanto segue:

curl -X POST \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "catalog_name": "main",
    "schema_name": "orders_app",
    "name": "db_password",
    "value": "your_secret_value",
    "comment": "Password for the orders database"
  }' \
  "$DATABRICKS_HOST/api/2.1/unity-catalog/secrets"

Crea un segreto in un insieme di credenziali basato su Azure Key Vault

Un amministratore esegue il backup di uno schema con Azure Key Vault una volta. Dopodiché crei, aggiorni e ruoti i relativi segreti in Azure Key Vault, che appaiono nello schema in Unity Catalog. Per eseguire il backup di uno schema, consulta Azure Key Vault secrets in Unity Catalog.

1. Crea il segreto nell'Azure Key Vault associato allo schema.
2. Leggi il segreto in base al nome. Vedi Leggi un segreto.

Concedere accesso ai segreti

Concedere il privilegio che corrisponda a ciò che ogni entità deve fare. Tranne che con BROWSE, ogni principal necessita anche di USE CATALOG e USE SCHEMA sul catalogo e schema genitore. Un privilegio concesso su un catalogo o schema si applica ai secret in esso contenuti, inclusi quelli creati successivamente.

Per lasciare un principale	Grant
Leggi il valore in un notebook, un job o una chiamata API REST	READ SECRET
Scopri segreti specifici senza vedere i loro valori	REFERENCE SECRET sul segreto o sullo schema, quando BROWSE sull'intero catalogo è troppo ampio. Non dà accesso in lettura né permette all'entità principale di usare il valore.
Aggiorna il valore	WRITE SECRET. Concedere solo questo privilegio non dà accesso per lettura al secret.
Creare secret in uno schema	CREATE SECRET sullo schema o sul catalogo
Concedere privilegi sui secret ad altri	Titolarità, o MANAGE sul segreto, sullo schema o sul catalogo

Per concedere privilegi, usa Catalog Explorer: apri il segreto o lo schema, clicca sulla scheda Permessi e clicca su Concedi. Per concedere con SQL, esegui quanto segue:

-- Let a job's service principal read every secret in a schema
GRANT USE CATALOG ON CATALOG main TO `etl-service-principal`;
GRANT USE SCHEMA, READ SECRET ON SCHEMA main.orders_app TO `etl-service-principal`;

-- Let the application's developers create secrets in its schema
GRANT USE SCHEMA, CREATE SECRET ON SCHEMA main.orders_app TO `orders-developers`;

Consulta Gestione dei privilegi in Unity Catalog.

Leggere un segreto

Per leggere un valore segreto, è necessario possedere il segreto o disporre dell'autorizzazione READ SECRET sul segreto oppure sul relativo schema o catalogo.

Utilità dei segreti (dbutils.secrets)

Azure Databricks consiglia dbutils, perché oscura il valore nell'output e nei log delle celle. Il seguente esempio usa un nome utente e una password del database per configurare una lettura JDBC:

username = dbutils.secrets.get(catalog="main", schema="orders_app", key="db_username")
password = dbutils.secrets.get(catalog="main", schema="orders_app", key="db_password")

df = (spark.read
  .format("jdbc")
  .option("url", "<jdbc-url>")
  .option("dbtable", "<table-name>")
  .option("user", username)
  .option("password", password)
  .load()
)

Vedi Secrets utility (dbutils.secrets).

REST API

Avvertimento

L'API REST di Unity Catalog non oscura i valori restituiti. I log di audit registrano ancora ogni lettura. Azure Databricks consiglia dbutils invece.

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.orders_app.db_password"

Elencare, aggiornare ed eliminare segreti

Per aggiornare un valore, devi WRITE SECRET sul segreto. Per cambiare il commento o la data di scadenza, o per eliminarlo, serve la proprietà del segreto o MANAGE sul segreto, sul suo schema o sul suo catalogo.

Per uno schema supportato da Azure Key Vault, aggiorna ed elimina gli elementi Secret in Azure Key Vault. Le cancellazioni si propagano a Unity Catalog.

Esploratore di cataloghi

1. In Catalog Explorer, vai allo schema e clicca su Secrets nel pannello Overview per elencarne i segreti.
2. Clicca sul secret che vuoi cambiare.
3. Nell'angolo in alto a destra, clicca sul menu kebab (punti verticali) e seleziona Modifica o Elimina.
4. Per modificare, inserisci un nuovo valore o data di scadenza e clicca su Conferma. Per eliminare, inserisci il nome completo del segreto e clicca su Elimina.

Utilità dei segreti (dbutils.secrets)

Per elencare i segreti a cui puoi accedere in uno schema, esegui quanto segue:

all_secrets = dbutils.secrets.list(catalog="main", schema="orders_app")

REST API

Per elencare i segreti, esegui quanto segue. Se sono disponibili altri risultati, passa la next_page_token della risposta come page_token:

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

Per aggiornare un valore, esegui quanto segue. Solo i campi presenti sia in update_mask sia nel corpo della richiesta cambiano:

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.orders_app.db_password?update_mask=*"

Per eliminare un segreto, esegui quanto segue:

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

Verifica dell'accesso ai secret

La system.access.audit tabella di sistema registra eventi segreti. Le reads appaiono con action_name = 'getSecret'. Per elencare gli ultimi 7 giorni di eventi segreti, esegui quanto segue:

SELECT event_time, user_identity.email, action_name, request_params
FROM system.access.audit
WHERE service_name = 'unityCatalog'
  AND action_name LIKE '%Secret%'
  AND event_date >= current_date() - INTERVAL 7 DAYS
ORDER BY event_time DESC;

Consultare la tabella di sistema del registro di controllo .

Cifra i valori segreti con chiavi gestite dal cliente

Azure Databricks cifra i valori segreti con chiavi gestite da Azure Databricks per impostazione predefinita. Per usare la tua chiave, configura le impostazioni CMK nel catalogo che contiene i segreti. I valori segreti sono memorizzati nel Catalogo Unity, non nella posizione di archiviazione del catalogo, quindi questo funziona per qualsiasi catalogo, incluso uno con una posizione di archiviazione esterna. Per requisiti e configurazione, vedi Chiavi gestite dal cliente per Unity Catalog.

I valori segreti esterni rimangono nel tuo cloud secret manager, che li cripta con le proprie chiavi. Le impostazioni CMK nel catalogo non si applicano a loro.

Usa i secret nelle UDF

Un Unity Catalog Python o Scala UDF può utilizzare un valore segreto senza dare ai chiamanti l'accesso al segreto. Dichiarare il segreto nella clausola dell'UDF SECRETS . L'UDF lo legge con i permessi del proprietario della funzione:

• Il proprietario deve disporre di READ SECRET sul segreto per creare o sostituire l'UDF. Se il proprietario perde READ SECRET, l'UDF fallisce.
• Le funzioni chiamanti devono solo EXECUTE sull'UDF e non avere alcun privilegio sul segreto.

La definizione UDF deve impostare environment_version su 6 o versione successiva. In classic compute, usa Databricks Runtime 19 e versioni successive in modalità di accesso standard. Per esempi, vedi Python UDF e Scala UDF.

UDF con ambito di sessione, che usano databricks.secrets.get() o com.databricks.Secrets.get(), leggono segreti con i permessi del chiamante, quindi ogni chiamante ha bisogno di READ SECRET. Vedi UDF Python e UDF Scala.

In modalità di calcolo dedicato, non puoi chiamare direttamente questi UDF. Puoi chiamarne uno da una funzione SQL di Unity Catalog che usi come maschera di colonna per il controllo degli accessi basato su attributi (ABAC), che Azure Databricks applica sul compute serverless. Vedi Versioni di calcolo non supportate.

Avvertimento

Usa i valori segreti solo all'interno dell'UDF. Non restituirli nei risultati UDF. L'oscuramento riduce l'esposizione accidentale in errori e log, ma non impedisce al codice UDF di restituire un segreto nei risultati della query.

Limitazioni

• Quote di utilizzo: Uno schema può contenere fino a 1.000 segreti e un metastore fino a 10.000.
• Nessuna ricerca globale o information schema: i segreti non compaiono nelle tabelle di ricerca globale o in information schema. Usa Catalog Explorer, dbutilso l'API REST.
• Ambito API OAuth: L'API dei segreti del Catalogo Unity richiede l'ambito OAuth unity-catalog API. L'ambito secrets si applica solo ai secret scope del workspace.
• Script Init: Non puoi usare i segreti del Catalogo Unity in script init globali o con scopo cluster.
• Sviluppo remoto: le modalità di esecuzione Databricks Connect e JAR compilati non possono leggere i segreti di Unity Catalog, perché dbutils.secrets richiede un notebook o un processo basato su Databricks Runtime.

Risorse aggiuntive

Resource	Description
Migliori pratiche per i segreti di Unity Catalog	Organizza i secret per ambiente, applicazione o team, e lascia che i carichi di lavoro utilizzino i secret senza leggerli.
Gestione dei segreti	Confronta i secret di Unity Catalog con gli scope dei secret dello spazio di lavoro e vedi dove puoi usare ciascuno.