Secrets dans Unity Catalog

info

Aperçu

Cette fonctionnalité est en aperçu public.

Cette page décrit comment créer, lire, gouverner et gérer les secrets dans Unity Catalog. Un secret Unity Catalog est un objet sécurisable qui stocke des informations sensibles, telles qu'un mot de passe, un jeton ou une clé API. Vos Notebooks et Jobs peuvent référencer le secret sans exposer la valeur dans le code.

Les secrets Unity Catalog utilisent l'espace de noms à trois niveaux (catalog.schema.secret) et sont disponibles dans tous les workspaces attachés à un métastore. Les privilèges Unity Catalog les régissent. Cela vous permet d'appliquer le même modèle d'accès et d'audit que vous utilisez pour d'autres assets de données à vos secrets.

remarque

Les secrets d'Unity Catalog sont distincts des secrets Databricks au niveau du Workspace, qui sont organisés en Secret Scope. Utilisez les secrets d'Unity Catalog lorsque vous souhaitez gouverner les secrets avec les privilèges Unity Catalog et les référencer avec l'espace de noms à trois niveaux.

Fonctionnement des secrets Unity Catalog

Un secret Unity Catalog est un objet sécurisable sous un schéma, avec le nom complet catalog.schema.secret. Comme les autres objets sécurisables Unity Catalog, les secrets prennent en charge l'héritage des privilèges du catalogue et du schéma. Pour plus d’informations sur les objets sécurisables et l’héritage, consultez la référence des objets sécurisables d'Unity Catalog.

Vous pouvez utiliser un secret Unity Catalog des manières suivantes :

• Récupérez la valeur dans le code. Avec l'accès READ SECRET, les utilisateurs peuvent récupérer une valeur secrète à partir de Notebooks et de Jobs en utilisant dbutils ou l'API REST de Unity Catalog. Ils peuvent ensuite l'utiliser pour s'authentifier auprès de systèmes externes ou pour chiffrer et déchiffrer des données.
• **Référencer la valeur à partir des objets Unity Catalog.** Les objets Unity Catalog, tels que les connexions Unity Catalog, peuvent faire référence à un secret par son nom afin qu'une intégration puisse utiliser le secret sans accorder aux utilisateurs l'accès à la valeur. Selon l'objet, la référence à un secret nécessite REFERENCE SECRET ou READ SECRET.

Databricks stocke les valeurs secrètes de Unity Catalog de manière chiffrée et applique la rédaction de secrets pour réduire l'exposition accidentelle dans les sorties et les logs. Pour faire pivoter un secret, mettez à jour périodiquement sa valeur dans l'interface utilisateur ou avec l'API REST de Unity Catalog.

Privilèges pour les secrets de Unity Catalog

Les privilèges suivants régissent les secrets. Vous pouvez les accorder au niveau du catalogue, du schéma ou du secret individuel, et ils suivent l'héritage des privilèges d'Unity Catalog.

Privilège	Description
CREATE SECRET	Permet à un utilisateur de créer un secret dans un schéma. Accordé au niveau du catalogue ou du schéma.
READ SECRET	Permet à un utilisateur de récupérer une valeur secrète.
WRITE SECRET	Permet à un utilisateur de mettre à jour une valeur secrète.
REFERENCE SECRET	Permet à un utilisateur de référencer un secret, par exemple à partir d'une connexion Unity Catalog, sans avoir accès à la valeur.

Privilège	Description
CREATE SECRET	Permet à un utilisateur de créer un secret dans un schéma. Accordé au niveau du catalogue ou du schéma.
READ SECRET	Permet à un utilisateur de récupérer une valeur secrète.
WRITE SECRET	Permet à un utilisateur de mettre à jour une valeur secrète.
REFERENCE SECRET	Permet à un utilisateur de référencer un secret, par exemple à partir d'une connexion Unity Catalog, sans avoir accès à la valeur.

Pour créer un secret dans un schéma, un utilisateur doit disposer de l'autorisation USE CATALOG et soit être propriétaire du schéma, soit disposer des autorisations CREATE SECRET et USE SCHEMA sur le schéma. Pour savoir comment accorder des privilèges, consultez Gérer les privilèges dans Unity Catalog.

Avant de commencer

Pour utiliser les secrets d'Unity Catalog, vous devez remplir les conditions suivantes :

• Le Workspace doit être activé pour Unity Catalog. Pour une introduction, consultez Qu'est-ce que Unity Catalog ?.

• Vous devez accéder aux secrets à partir d’un compute compatible Unity Catalog. Databricks recommande l'une des options suivantes :

  • Jobs et notebooks Serverless utilisant la version 4 ou ultérieure de l'environnement.
  • Compute classique en mode d'accès standard exécutant Databricks Runtime 17.3 LTS ou version supérieure.

• Pour récupérer des secrets avec dbutils, le compute doit exécuter Databricks Runtime 17.3 LTS ou une version ultérieure, ou l'environnement serverless version 4 ou une version ultérieure.

Créer un secret

La création d'un secret nécessite que vous ayez la permission USE CATALOG et que vous soyez propriétaire du schéma ou que vous ayez CREATE SECRET et USE SCHEMA sur le schéma. Voir les Privilèges pour les secrets Unity Catalog.

Catalog Explorer

1. Dans votre Workspace Databricks, cliquez sur Catalogue pour ouvrir l'Explorateur de catalogues.
2. Accédez au schéma où vous souhaitez créer le secret.
3. Cliquez sur Créer > Secret .
4. Saisissez un nom et une valeur . Facultativement, ajoutez un commentaire et une date d'expiration . Si un secret expire, l'Explorateur de catalogue affiche un avertissement.
5. Cliquez sur Créer .

REST API

Exécutez la commande cURL suivante à l'aide de l'Endpoint /api/2.1/unity-catalog/secrets :

Bash

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"

Lire un secret

Pour lire une valeur secrète, vous devez disposer de READ SECRET sur le secret ou sur un catalogue ou un schéma parent.

Secrets utility (dbutils.secrets)

Databricks recommande dbutils pour lire les secrets, car il applique la rédaction des secrets. Cette option nécessite Databricks Runtime 17.3 LTS ou une version ultérieure, ou la version 4 ou ultérieure de l’environnement Serverless.

Python

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

Pour plus d'informations, consultez l'utilitaire Secrets (dbutils.secrets).

REST API

attention

Les valeurs secrètes récupérées avec l'API REST de Unity Catalog ne sont pas soumises à la rédaction des secrets, bien que l'accès soit toujours enregistré dans les logs d'audit. Databricks recommande dbutils plutôt.

Pour renvoyer la valeur, définissez include_value=true et lisez le champ effective_value dans la réponse :

Bash

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

Gérer les autorisations sur les secrets

Accordez CREATE SECRET au niveau du catalogue ou du schéma pour contrôler qui peut créer des secrets. Accordez READ SECRET, WRITE SECRET, ou REFERENCE SECRET au niveau du catalogue, du schéma ou du secret individuel pour contrôler l'accès. L'héritage des privilèges s'applique. Pour en savoir plus sur l'octroi et la révocation des privilèges, consultez Gérer les privilèges dans Unity Catalog.

Accorder la possibilité de créer des secrets

Catalog Explorer

1. Dans l'explorateur de catalogue, accédez au schéma.

2. Cliquez sur l'onglet tab .

3. Cliquez sur Accorder .

4. Sélectionnez les principaux auxquels accorder l'accès, puis sélectionnez **CRÉER UN SECRET**.

   Si un principal ne dispose pas de USE SCHEMA, un avertissement vous invite à l'accorder. USE SCHEMA est également nécessaire pour créer des secrets dans le schéma.

5. Cliquez sur Confirmer .

SQL

SQL

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

REST API

Exécutez la commande cURL suivante à l'aide de l'Endpoint /api/2.1/unity-catalog/permissions/schema/{schema_name} :

Bash

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}"

Accorder l'accès à un secret

Catalog Explorer

1. Dans l'Explorateur de catalogue, rendez-vous dans le secret et cliquez dessus.
2. Cliquez sur l'onglet tab .
3. Cliquez sur Accorder .
4. Sélectionnez les principaux et les privilèges à accorder, puis cliquez sur **Confirmer**.

SQL

SQL

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

REST API

Exécutez la commande cURL suivante à l'aide de l'Endpoint /api/2.1/unity-catalog/permissions/secret/{catalog.schema.secret} :

Bash

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}"

Lister, mettre à jour et supprimer les secrets

Lister les secrets

Catalog Explorer

1. Dans l'explorateur de catalogue, accédez au schéma.
2. Dans le volet Aperçu , cliquez sur Secrets pour afficher tous les secrets du schéma.

Secrets utility (dbutils.secrets)

Python

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

REST API

Les requêtes de liste utilisent page_size pour contrôler le nombre de résultats :

Bash

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"

Mettre à jour un secret

Pour mettre à jour une valeur secrète, vous devez disposer de WRITE SECRET sur le secret.

Catalog Explorer

1. Dans l'Explorateur de catalogues, accédez au schéma et cliquez sur **Secrets** dans le volet **Vue d'ensemble**.
2. Cliquez sur le secret pour le mettre à jour.
3. Dans le coin supérieur droit, cliquez sur le menu kebab (points verticaux) et sélectionnez Modifier .
4. Saisissez une nouvelle valeur ou date d'expiration, puis cliquez sur Confirmer .

REST API

Les demandes de mise à jour nécessitent le update_mask parameter. Seuls les champs inclus dans update_mask et le corps de la requête sont mis à jour :

Bash

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=*"

Supprimer un secret

Catalog Explorer

1. Dans l'Explorateur de catalogues, accédez au schéma et cliquez sur **Secrets** dans le volet **Vue d'ensemble**.
2. Cliquez sur le secret à supprimer.
3. Dans le coin supérieur droit, cliquez sur le menu kebab (points verticaux) et sélectionnez Supprimer .
4. Entrez le nom complet du secret, puis cliquez sur Supprimer .

REST API

Bash

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

Événements d'audit pour les secrets de Unity Catalog

La table système system.access.audit enregistre les événements liés aux secrets d'Unity Catalog. Par exemple, pour voir tous les événements secrets pour un utilisateur à une date spécifique, exécutez la query suivante :

SQL

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%";

Pour plus d’informations sur les Logs d’audit, consultez la référence de la table système du journal d’audit.

Chiffrer les valeurs secrètes avec des clés gérées par le client

By default, Databricks chiffre les valeurs secrètes avec des clés gérées par Databricks. Vous pouvez plutôt utiliser des clés gérées par le client (CMK). Si vous activez la fonctionnalité de catalogue géré chiffré par CMK et associez une configuration CMK à votre compte, Databricks utilise la CMK pour chiffrer les valeurs secrètes. Pour plus d’informations, consultez Clés gérées par le client pour Unity Catalog.

Limitations

Les secrets Unity Catalog présentent les limitations suivantes :

• Aucun SQL Warehouse. Les secrets Unity Catalog ne sont pas pris en charge sur les SQL Warehouse. Ils nécessitent Databricks Runtime 17,3 LTS ou une version ultérieure sur un compute compatible Unity Catalog, ou serverless.
• Pas de découverte globale. Les secrets d'Unity Catalog n'apparaissent pas dans la recherche globale.
• Autorisation de navigation non prise en charge. BROWSE sur un catalogue ne s'applique pas aux secrets d'Unity Catalog. Pour rendre un secret détectable, accordez READ SECRET ou REFERENCE SECRET sur le secret individuel ou son schéma.
• Aucun script d'initialisation. Vous ne pouvez pas utiliser les secrets Unity Catalog dans les scripts d'initialisation globaux ou de cluster. Databricks recommande d'utiliser des fonctionnalités dédiées plutôt que des scripts d'initialisation lorsque cela est possible.
• Aucun schéma d'information. Les tables d'informations de schéma pour les secrets ne sont pas encore disponibles. Utilisez Catalog Explorer ou l'API REST pour la découverte.
• Portée du runtimedbutils. La récupération dbutils est prise en charge sur les notebooks et Jobs basés sur Databricks Runtime. Les contextes hors Databricks Runtime, tels que le développement à distance ou les modes d'exécution JAR compilés, ne sont pas pris en charge.
• Champ d'application de l'API OAuth. L'API des secrets d'Unity Catalog est accessible uniquement avec le champ d'application de l'API OAuth unity-catalog. Utilisez le secrets API scope uniquement pour les secrets Databricks au niveau du Workspace.
• **Limites de quota.** Jusqu'à 100 secrets par schéma et 1 000 par métastore.