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.
• Fare riferimento al valore contenuto negli oggetti di Unity Catalog. Gli oggetti di Unity Catalog, come le connessioni di Unity Catalog, possono fare riferimento a un segreto tramite il relativo nome, in modo che un'integrazione possa utilizzare il segreto senza concedere agli utenti l'accesso al suo valore. A seconda dell'oggetto , per fare riferimento a un segreto è necessario REFERENCE SECRET o READ SECRET.

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"

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, andare 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

Le richieste di elenco usano page_size per controllare il numero di risultati:

curl -G \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  --data-urlencode "catalog_name=main" \
  --data-urlencode "schema_name=default" \
  "$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 Secrets 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.

Limitazioni

I segreti del catalogo Unity presentano le limitazioni seguenti:

• Nessun data warehouse SQL. I segreti del catalogo Unity non sono supportati in SQL Warehouse. Richiedono Databricks Runtime 17.3 LTS o versione successiva su cluster di calcolo abilitati per Unity Catalog oppure serverless.
• 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.