Aller au contenu principal

Secrets dans Unity Catalog

Un secret Unity Catalog est un objet sécurisable qui stocke une information d’identification sensible, telle qu’un mot de passe, un jeton ou une clé API. Les secrets utilisent l’espace de noms à trois niveaux (catalog.schema.secret) et sont disponibles dans chaque workspace attaché au metastore.

Vous gérez les secrets avec les mêmes privilèges Unity Catalog que vos autres assets de données, jusqu’au secret individuel. Les utilisateurs peuvent parcourir un secret sans pouvoir le lire ou l’utiliser, vous pouvez chiffrer les valeurs des secrets avec votre propre clé, et les logs d’audit enregistrent chaque lecture ou modification.

Conditions requises​

Créer un secret​

Les secrets vivent dans des schémas. Créez des secrets dans un schéma auquel seuls les principaux qui en ont besoin peuvent accéder. Pour décider comment regrouper les secrets dans des schémas, consultez Regrouper les secrets par utilisateur.

Créer un secret géré par Databricks​

Pour créer un secret géré par Databricks, vous avez besoin de USE CATALOG sur le catalogue, et soit de la propriété du schéma, soit de CREATE SECRET et USE SCHEMA dessus.

Pour créer un schéma pour les secrets d’une application, exécutez la commande suivante :

SQL
CREATE SCHEMA IF NOT EXISTS main.orders_app;
  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 .

Accorder l’accès aux secrets​

Accordez le privilège correspondant à ce que chaque principal doit faire. Sauf avec BROWSE, chaque principal a également besoin de USE CATALOG et USE SCHEMA sur le catalogue et le schéma parent. Un privilège accordé sur un catalog ou un schema s’applique aux secrets qu’il contient, y compris aux secrets créés ultérieurement.

Pour permettre à un principal

Accorder

Lire la valeur dans un appel de notebook, de job ou d’API REST

READ SECRET

Découvrir des secrets spécifiques sans voir leurs valeurs

REFERENCE SECRET sur le secret ou le schema, lorsque BROWSE sur l’ensemble du catalog est trop large. Il ne donne pas d’accès en lecture et ne permet pas au principal d’utiliser la valeur.

Mettre à jour la valeur

WRITE SECRET. L’octroi de ce seul privilège ne donne pas d’accès en lecture au secret.

Créer des secrets dans un schéma

CREATE SECRET sur le schéma ou le catalogue

Accorder des privilèges sur les secrets à d’autres

Propriété, ou MANAGE sur le secret, le schéma ou le catalogue

Pour permettre à un principal

Accorder

Lire la valeur dans un appel de notebook, de job ou d’API REST

READ SECRET

Découvrir des secrets spécifiques sans voir leurs valeurs

REFERENCE SECRET sur le secret ou le schema, lorsque BROWSE sur l’ensemble du catalog est trop large. Il ne donne pas d’accès en lecture et ne permet pas au principal d’utiliser la valeur.

Mettre à jour la valeur

WRITE SECRET. L’octroi de ce seul privilège ne donne pas d’accès en lecture au secret.

Créer des secrets dans un schéma

CREATE SECRET sur le schéma ou le catalogue

Accorder des privilèges sur les secrets à d’autres

Propriété, ou MANAGE sur le secret, le schéma ou le catalogue

Pour accorder des privilèges, utilisez l’Explorateur de catalogues : ouvrez le secret ou le schéma, cliquez sur l’ Autorisations tab et cliquez sur Accorder . Pour accorder avec SQL, exécutez ce qui suit :

SQL
-- 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`;

Voir Gérer les privilèges dans Unity Catalog.

Lire un secret​

Pour lire une valeur secrète, vous devez être propriétaire du secret, ou disposer de READ SECRET sur le secret ou sur son schéma ou catalogue.

Databricks recommande dbutils, car cela masque la valeur dans la sortie de cellule et les logs. L’exemple suivant lit un nom d’utilisateur et un mot de passe de base de données pour configurer une lecture JDBC :

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

Consultez l'utilitaire Secrets (dbutils.secrets).

Lister, mettre à jour et supprimer les secrets​

Pour mettre à jour une valeur, vous devez disposer de WRITE SECRET sur le secret. Pour modifier son commentaire ou sa date d'expiration, ou pour le supprimer, vous devez être propriétaire du secret ou disposer de MANAGE sur celui-ci, son schéma ou son catalogue.

  1. Dans l'Explorateur de catalogue, accédez au schéma et cliquez sur Secrets dans le volet Vue d'ensemble pour répertorier ses secrets.
  2. Cliquez sur le secret que vous souhaitez modifier.
  3. Dans le coin supérieur droit, cliquez sur le menu kebab (points verticaux) et sélectionnez Modifier ou Supprimer .
  4. Pour modifier, saisissez une nouvelle valeur ou une nouvelle date d’expiration et cliquez sur Confirmer . Pour supprimer, saisissez le nom complet du secret et cliquez sur Supprimer .

Auditer l’accès aux secrets​

La table système system.access.audit enregistre les événements liés aux secrets. Les lectures apparaissent avec action_name = 'getSecret'. Pour afficher la liste des événements liés aux secrets des 7 derniers jours, exécutez la commande suivante :

SQL
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;

Voir Référence de table système de log d’audit.

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

Databricks chiffre default les valeurs secrètes avec des clés gérées par Databricks. Pour utiliser votre propre clé, configurez les paramètres de clé gérée par le client (CMK) sur le catalogue qui contient les secrets. Les valeurs secrètes sont stockées dans Unity Catalog, et non dans l’emplacement de stockage du catalogue. Cela fonctionne donc pour n’importe quel catalogue, y compris celui avec un emplacement de stockage externe. Pour connaître les prérequis et la configuration, consultez Clés gérées par le client pour Unity Catalog.

Utiliser des secrets dans les UDF​

Une UDF Python ou Scala dans Unity Catalog peut utiliser une valeur secrète sans donner aux appelants l’accès au secret. Déclarez le secret dans la clause SECRETS de l’UDF. L’UDF la lit avec les autorisations du propriétaire de la fonction :

  • Le propriétaire doit disposer de READ SECRET sur le secret pour créer ou remplacer l’UDF. Si le propriétaire perd READ SECRET, l’UDF échoue.
  • Les appelants n'ont besoin que de EXECUTE sur l'UDF et d'aucun privilège sur le secret.

La définition de l'UDF doit définir environment_version sur 6 ou supérieur. Sur le compute classique, utilisez Databricks Runtime 19 et versions supérieures en mode d'accès standard. Pour des exemples, consultez les UDF Python et les UDF Scala.

Les UDF étendues à la session, qui utilisent databricks.secrets.get() ou com.databricks.Secrets.get(), lisent les secrets avec les autorisations de l’appelant. Par conséquent, chaque appelant a besoin de READ SECRET. Voir Python UDFs et Scala UDFs.

Sur un compute en mode d'accès dédié, vous ne pouvez pas appeler directement ces UDF. Vous pouvez en appeler une à partir d’une fonction SQL Unity Catalog que vous utilisez comme masque de colonne de contrôle d’accès basé sur les attributs (ABAC), que Databricks applique sur le compute serverless. Consultez Versions de compute non prises en charge.

attention

Utilisez les valeurs secrètes uniquement dans l'UDF. Ne les renvoyez pas dans les résultats de l'UDF. La rédaction réduit l'exposition accidentelle dans les erreurs et les logs, mais elle n'empêche pas le code UDF de renvoyer un secret dans les résultats de la query.

Limitations​

  • Quotas : un schéma peut contenir jusqu’à 1 000 secrets et un metastore jusqu’à 10 000.
  • Aucune recherche globale ni schéma d'information : Les secrets n'apparaissent pas dans la recherche globale ou dans les tables du schéma d'information. Utilisez l'Explorateur de catalogues, dbutils ou l'API REST.
  • Portée de l’API OAuth : l’API des secrets Unity Catalog nécessite la portée de l’API OAuth unity-catalog. La portée secrets s’applique uniquement aux Secret Scope de Workspace.
  • Scripts d'initialisation : vous ne pouvez pas utiliser les secrets Unity Catalog dans les scripts d'initialisation globaux ou au niveau du cluster.
  • Développement à distance : les modes d’exécution Databricks Connect et JAR compilé ne peuvent pas lire les secrets du Unity Catalog, car dbutils.secrets nécessite un notebook ou un job basé sur Databricks Runtime.

Ressources supplémentaires​