Aller au contenu principal
Dernière mise à jour le

Secrets dans Unity Catalog

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.
  • Use the value in a session-scoped Python or Scala UDF. Voir Session-scoped UDFs.
  • Utilisez la valeur dans une UDF Python Unity Catalog. Une UDF scalaire ou par batch déclare chaque secret dans sa clause SECRETS. Consultez Python UDFs.
  • Utilisez la valeur dans une UDF Scala Unity Catalog. Une UDF scalaire déclare chaque secret dans sa clause SECRETS. Voir UDF Scala.

Pour connaître les exigences et le comportement des autorisations selon les types d’UDF, consultez Exigences et autorisations des UDF.

Exigences et autorisations des UDF​

Les exigences et le comportement des autorisations diffèrent entre les UDF à portée de session et les UDF Unity Catalog.

Session-scoped UDFs​

Une UDF Python à portée de session récupère un secret avec databricks.secrets.get(), et une UDF Scala à portée de session en récupère un avec com.databricks.Secrets.get(). L'accès aux secrets utilise les autorisations de l'appelant.

Les exigences de compute pour l’accès aux secrets dépendent du langage des UDF :

  • Sur le compute Serverless, la session de notebook ou de job doit utiliser la version d'environnement 6 ou supérieure pour les UDF Python et Scala.
  • On classic compute, session-scoped Python UDFs require Databricks Runtime 19 or above in standard or dedicated access mode.
  • Sur le compute classique, les UDF Scala à portée de session nécessitent Databricks Runtime 19 ou une version ultérieure avec le mode d'accès standard.

UDF Unity Catalog​

Les UDF Python Scalar et Batch Unity Catalog ainsi que les UDF Scala Unity Catalog scalaires déclarent des secrets dans la clause SECRETS et doivent définir explicitement environment_version sur 6 ou une version ultérieure. Elles prennent en charge le compute serverless, les SQL warehouses serverless et le compute classique exécutant Databricks Runtime 19 ou une version ultérieure avec le mode d’accès standard.

Pro SQL warehouses support scalar and Batch Unity Catalog Python UDFs that use secrets. Unity Catalog Scala UDFs that use secrets are not supported on pro SQL warehouses.

Pour créer ou remplacer une UDF qui déclare un secret, le principal exécutant l'instruction doit disposer de READ SECRET sur le secret, ainsi que de USE CATALOG et de USE SCHEMA sur son catalogue et son schéma parents. À l'exécution, l'UDF utilise les autorisations du propriétaire actuel de la fonction. Les appelants ont besoin des privilèges de fonction habituels, y compris EXECUTE, mais n'ont pas besoin d'un accès direct aux secrets déclarés. Si le propriétaire de la fonction perd l'autorisation de lire un secret déclaré, l'UDF échoue.

Use secret-enabled UDFs in column masks on dedicated compute​

Vous ne pouvez pas appeler directement une UDF Python ou Scala de Unity Catalog qui utilise la clause SECRETS sur un compute en mode dédié. Cependant, vous pouvez créer une fonction SQL Unity Catalog qui appelle l'UDF activée par le secret et utiliser la fonction SQL comme masque de colonne de contrôle d'accès basé sur les attributs (ABAC). Lorsqu'une query s'exécute sur un compute dédié, Databricks délâge l'application du masque de colonne au compute serverless. Cette exception s'applique uniquement lors de l'application du masque de colonne ; elle ne permet pas l'appel direct de l'UDF activée par le secret sur le compute dédié. Consultez la page Versions de compute non prises en charge.

attention

Utilisez des valeurs secrètes uniquement au sein de l’implémentation de l’UDF. Ne renvoyez pas de valeurs secrètes et ne les incluez pas dans les résultats d’UDF. Le masquage des secrets contribue à réduire l’exposition accidentelle dans les erreurs et les logs, mais il n’empêche pas le code UDF d’exposer du matériel secret dans les résultats de query.

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 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 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 :

  • 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.

  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 .

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.

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).

Utiliser un secret dans votre code​

Après avoir lu un secret Unity Catalog avec dbutils.secrets.get, transmettez la valeur renvoyée au code de votre application. dbutils occulte la valeur dans la sortie de cellule et les Logs, afin que vous puissiez l’utiliser sans l’exposer.

L’exemple suivant utilise un secret comme jeton Bearer pour appeler une API externe :

Python
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()

L'exemple suivant récupère une valeur secrète et la transmet à dbutils.credentials.getServiceCredentialsProvider pour configurer une session boto3 pour l'AWS SDK. Un nom d'identifiant de service n'est pas sensible en soi ; cet exemple en stocke donc un dans un secret uniquement pour illustrer l'enchaînement d'une valeur secrète récupérée dans un autre appel SDK. Pour plus d'information sur les identifiants de service, voir Utiliser les identifiants de service Unity Catalog pour se connecter à des services cloud externes.

Python
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")

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​

  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 .

Accorder l'accès à un secret​

  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**.

Lister, mettre à jour et supprimer les secrets​

Lister les secrets​

  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.

Mettre à jour un secret​

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

  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 .

Supprimer un secret​

  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 .

É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 :

  • Accès direct limité depuis les SQL warehouses. Vous ne pouvez pas récupérer les secrets d’Unity Catalog directement à partir des SQL Warehouses. Les UDF Python Unity Catalog scalaires et batch peuvent accéder aux secrets déclarés dans leurs clauses SECRETS sur les SQL Warehouse pro et Serverless. Les UDF Scala Unity Catalog scalaires ne peuvent accéder aux secrets déclarés que sur les SQL Warehouse Serverless.
  • Aucune invocation directe d'UDF SECRETS sur un compute dédié. Vous ne pouvez pas invoquer directement des UDF Python scalaires ou Batch Unity Catalog, ni des UDF Scala Unity Catalog scalaires qui utilisent la clause SECRETS sur un compute en mode d'accès dédié. Pour l'exception du masquage de colonne, consultez Utiliser des UDF activées pour les secrets dans les masques de colonne sur un compute dédié.
  • 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.
Sur cette page