Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
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.
Crea 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
- Nell'area di lavoro Azure Databricks fare clic su Catalogo per aprire Esplora cataloghi.
- Passare allo schema in cui si vuole creare il segreto.
- Fare clic su Crea > segreto.
- Immettere un nome e un valore. Facoltativamente, aggiungere un commento e una data di scadenza. Se un segreto scade, Esplora cataloghi visualizza un avviso.
- 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 uno schema supportato da 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.
- Crea il segreto nell'Azure Key Vault associato allo schema.
- 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 su di tutto il 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 sul 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 raccomanda dbutils, perché oscura il valore nell'output delle celle e nei log. 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
- In Catalog Explorer, vai allo schema e clicca su Secrets nel pannello Overview per elencarne i segreti.
- Clicca sul secret che vuoi cambiare.
- Nell'angolo in alto a destra, clicca sul menu kebab (punti verticali) e seleziona Modifica o Elimina.
- 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"
Aggiungere tag ai segreti
I segreti del Catalogo Unity supportano tag chiave-valore, ad esempio per classificare segreti o registrare il team proprietario o il centro costi. Vedi Applicare tag agli oggetti proteggibili del catalogo Unity.
Per aggiungere o rimuovere tag su un segreto, devi possedere il segreto o avere tutti i seguenti privilegi:
-
APPLY TAGSul segreto -
USE SCHEMAsullo schema genitore del segreto -
USE CATALOGnel catalogo padre del segreto
Per assegnare un tag governato, è necessario anche il ASSIGN permesso sul tag governato. Vedere Gestire le autorizzazioni per i tag regolamentati.
Per aggiungere o rimuovere un tag con SQL, esegui quanto segue:
SET TAG ON SECRET main.orders_app.db_password cost_center = hr;
UNSET TAG ON SECRET main.orders_app.db_password cost_center;
Per visualizzare i tag di un segreto, usa una delle seguenti opzioni:
Esploratore di cataloghi
- In Catalog Explorer, vai allo schema e fai clic su Segreti nel riquadro Panoramica.
- Fai clic sul secret. I suoi tag appaiono sotto Tag nella scheda Panoramica .
REST API
Per elencare i tag su un segreto, esegui il comando seguente. Se sono disponibili altri risultati, passa la next_page_token della risposta come page_token:
curl \
-H "Authorization: Bearer $DATABRICKS_TOKEN" \
"$DATABRICKS_HOST/api/2.1/unity-catalog/entity-tag-assignments/secrets/main.orders_app.db_password/tags"
CLI
Per elencare i tag su un segreto, esegui quanto segue:
databricks entity-tag-assignments list secrets main.orders_app.db_password
I tag segreti non compaiono nell'output di DESCRIBE SECRET, nella risposta dell'API che ottiene un segreto, nelle tabelle degli schemi informativi o nella ricerca dell'area di lavoro.
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 .
Cripta 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.
Usare i segreti 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 SECRETsul segreto per creare o sostituire l'UDF. Se il proprietario perdeREAD SECRET, l'UDF fallisce. - Le funzioni chiamanti devono solo
EXECUTEsull'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 a ambito di sessione, che utilizzano databricks.secrets.get() o com.databricks.Secrets.get(), leggono segreti con i permessi del chiamante, quindi ogni chiamante ha bisogno READ SECRETdi . Vedi UDF Python e UDF Scala.
Nel calcolo in modalità di accesso 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
- Limiti: Uno schema può contenere fino a 1.000 segreti e un metastore fino a 10.000.
-
Nessuna ricerca globale o schema informativo: I segreti non compaiono nelle tabelle di ricerca globale o di schema informativo. Usa Catalog Explorer,
dbutilso l'API REST. -
Ambito API OAuth: L'API dei segreti del Catalogo Unity richiede l'ambito API
unity-catalogOAuth. L'ambitosecretssi applica solo ai secret scope del workspace. - Script di init: Non puoi usare i segreti del Catalogo Unity in script di init globali o a ambito cluster.
-
Sviluppo remoto: le modalità di esecuzione di Databricks Connect e di JAR compilati non possono leggere i segreti del Catalogo Unity perché
dbutils.secretsrichiede un notebook o un job supportato da Databricks Runtime.
Risorse aggiuntive
| Resource | Description |
|---|---|
| Best practice 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. |