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
- Le workspace doit être activé pour Unity Catalog. Voir Qu'est-ce que Unity Catalog ?.
- Pour lire des secrets avec
dbutils, utilisez des notebooks serverless et des jobs sur la version d'environnement 4 et supérieures, ou un compute classique exécutant Databricks Runtime 17.3 LTS et versions supérieures. Databricks recommande le mode d'accès serverless ou standard. - Pour utiliser des secrets dans des UDF, consultez Utiliser des secrets dans des UDF.
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 :
CREATE SCHEMA IF NOT EXISTS main.orders_app;
- Catalog Explorer
- REST API
- Dans votre Workspace Databricks, cliquez sur Catalogue pour ouvrir l'Explorateur de catalogues.
- Accédez au schéma où vous souhaitez créer le secret.
- Cliquez sur Créer > Secret .
- 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.
- Cliquez sur Créer .
Pour créer un secret, exécutez la commande suivante :
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"
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 |
|
Découvrir des secrets spécifiques sans voir leurs valeurs |
|
Mettre à jour la valeur |
|
Créer des secrets dans un schéma |
|
Accorder des privilèges sur les secrets à d’autres | Propriété, ou |
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 :
-- 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.
- Secrets utility (dbutils.secrets)
- REST API
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 :
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).
L’API REST Unity Catalog ne masque pas les valeurs renvoyées. Les logs d’audit continuent d’enregistrer chaque lecture. Databricks recommande d'utiliser dbutils à la place.
Pour renvoyer la valeur, définissez include_value=true et lisez le champ effective_value dans la réponse :
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"
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.
- Catalog Explorer
- Secrets utility (dbutils.secrets)
- REST API
- 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.
- Cliquez sur le secret que vous souhaitez modifier.
- Dans le coin supérieur droit, cliquez sur le menu kebab (points verticaux) et sélectionnez Modifier ou Supprimer .
- 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 .
Pour lister les secrets auxquels vous pouvez accéder dans un schéma, exécutez la commande suivante :
all_secrets = dbutils.secrets.list(catalog="main", schema="orders_app")
Pour répertorier les secrets, exécutez la commande suivante. Si d'autres résultats sont disponibles, transmettez le next_page_token de la réponse en tant que 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"
Pour mettre à jour une valeur, exécutez ce qui suit. Seuls les champs présents à la fois dans update_mask et dans le corps de la requête sont modifiés :
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=*"
Pour supprimer un secret, exécutez la commande suivante :
curl -X DELETE \
-H "Authorization: Bearer $DATABRICKS_TOKEN" \
"$DATABRICKS_HOST/api/2.1/unity-catalog/secrets/main.orders_app.db_password"
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 :
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 SECRETsur le secret pour créer ou remplacer l’UDF. Si le propriétaire perdREAD SECRET, l’UDF échoue. - Les appelants n'ont besoin que de
EXECUTEsur 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.
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,
dbutilsou 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éesecretss’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.secretsnécessite un notebook ou un job basé sur Databricks Runtime.
Ressources supplémentaires
-
- Meilleures pratiques pour les secrets de Unity Catalog
- Organisez les secrets par environnement, application ou équipe, et laissez les workloads utiliser des secrets sans les lire.
-
- Gestion des secrets
- Comparez les secrets Unity Catalog avec les Secret Scope du Workspace et voyez où vous pouvez utiliser chacun d’eux.