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.
Les secrets Unity Catalog peuvent être gérés par Databricks ou pris en charge par AWS Secrets Manager. Voir Secrets AWS Secrets Manager dans Unity Catalog.
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.
Un schéma contient des secrets gérés par Databricks ou des secrets pris en charge par AWS Secrets Manager, pas les deux. Vous choisissez donc où les valeurs sont stockées lors de la configuration du schéma. Pour un schéma pris en charge par AWS Secrets Manager, voir Créer un secret dans un schéma pris en charge par AWS Secrets Manager.
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"
Créer un secret dans un schéma pris en charge par AWS Secrets Manager
Un administrateur prend en charge un schéma avec AWS Secrets Manager une fois. Après cela, vous créez, mettez à jour et faites pivoter ses secrets dans AWS Secrets Manager, et ils apparaissent dans le schéma du Unity Catalog. Pour prendre en charge un schéma, consultez Secrets AWS Secrets Manager dans Unity Catalog.
- Créez le secret dans AWS Secrets Manager, dans la région AWS que la connexion du schéma utilise. Si la connexion a un filtre de balise, ajoutez la balise correspondante.
- Lire le secret par nom. Consultez Lire un secret.
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.
Pour un schéma pris en charge par AWS Secrets Manager, mettez à jour et supprimez des secrets dans AWS Secrets Manager. Les suppressions sont reportées dans Unity Catalog.
- 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"
Étiqueter les secrets
Les secrets du Unity Catalog prennent en charge les balises clé-valeur, par exemple pour classer les secrets ou enregistrer l’équipe propriétaire ou le centre de coûts. Voir Appliquer des balises aux objets sécurisables du Unity Catalog.
Pour ajouter ou supprimer des balises sur un secret, vous devez posséder le secret ou disposer de tous les privilèges suivants :
APPLY TAGen secretUSE SCHEMAsur le schéma parent du secretUSE CATALOGdans le catalogue parent du secret
Pour attribuer un tag gouverné, vous avez également besoin de l'autorisation ASSIGN sur le tag gouverné. Voir Gérer les autorisations sur les tags gouvernés.
Pour ajouter ou supprimer une balise avec SQL, exécutez ce qui suit :
SET TAG ON SECRET main.orders_app.db_password cost_center = hr;
UNSET TAG ON SECRET main.orders_app.db_password cost_center;
Pour afficher les balises sur un secret, utilisez l'une des méthodes suivantes :
- Catalog Explorer
- REST API
- CLI
- Dans l'Explorateur de catalogues, accédez au schéma et cliquez sur **Secrets** dans le volet **Vue d'ensemble**.
- Cliquez sur le secret. Ses tags apparaissent sous Tags dans le tab Vue d'ensemble .
Pour lister les tags sur un secret, exécutez ce qui suit. Si d'autres résultats sont disponibles, transmettez le next_page_token de la réponse en tant que page_token:
curl \
-H "Authorization: Bearer $DATABRICKS_TOKEN" \
"$DATABRICKS_HOST/api/2.1/unity-catalog/entity-tag-assignments/secrets/main.orders_app.db_password/tags"
Pour répertorier les tags d'un secret, exécutez la commande suivante :
databricks entity-tag-assignments list secrets main.orders_app.db_password
Les tags de secret n'apparaissent pas dans la sortie de DESCRIBE SECRET, dans la réponse de l'API qui récupère un secret, dans les tables du schéma d'information ou dans la recherche du Workspace.
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.
Les valeurs de secret externes restent dans votre gestionnaire de secrets cloud, qui les chiffre avec ses propres clés. Les paramètres CMK sur le catalogue ne s’y appliquent pas.
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.