Secrets dans Unity Catalog

Important

Cette fonctionnalité est disponible en préversion publique.

Cette page explique comment créer, lire, régir et gérer des secrets dans le catalogue Unity. Un secret de catalogue Unity est un objet sécurisable qui stocke des éléments sensibles, tels qu’un mot de passe, un jeton ou une clé API. Vos blocs-notes et travaux peuvent référencer le secret sans exposer la valeur dans le code.

Les secrets du catalogue Unity utilisent l’espace de noms à trois niveaux (catalog.schema.secret) et sont disponibles dans les espaces de travail attachés à un metastore. Les privilèges du catalogue Unity les régissent. Cela vous permet d’appliquer le même modèle d’accès et l’audit que vous utilisez pour d’autres ressources de données à vos secrets.

Note

Les secrets de Unity Catalog sont distincts des secrets Azure Databricks propres à l’espace de travail, qui sont organisés en portées de secrets. Utilisez les secrets du catalogue Unity lorsque vous souhaitez régir les secrets avec des privilèges de catalogue Unity et les référencer avec l’espace de noms à trois niveaux.

Fonctionnement des secrets dans Unity Catalog

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

Vous pouvez utiliser un secret de catalogue Unity de la manière suivante :

• Récupérez la valeur en code. Avec l’accès READ SECRET, les utilisateurs peuvent récupérer une valeur secrète depuis des notebooks et des tâches à l’aide de dbutils ou de l’API REST d’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.
• Faites référence à la valeur des objets du catalogue Unity. Les objets catalogue Unity, tels que les connexions de catalogue Unity, peuvent référencer un secret par nom afin qu’une intégration puisse utiliser le secret sans accorder aux utilisateurs l’accès à la valeur. Selon l’objet, le référencement d’un secret nécessite soit REFERENCE SECRET .READ SECRET

Azure Databricks stocke les valeurs secrètes de Unity Catalog sous forme chiffrée et applique le masquage des secrets pour réduire leur exposition accidentelle dans les sorties et les journaux. Pour faire pivoter un secret, mettez régulièrement à jour sa valeur dans l’interface utilisateur ou avec l’API REST du catalogue Unity.

Privilèges pour les secrets du catalogue Unity

Les privilèges suivants régissent les secrets. Vous pouvez les accorder au niveau du catalogue, du schéma ou pour un secret individuel, et ces autorisations 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 de catalogue Unity, sans accéder à la valeur.

Pour créer un secret dans un schéma, un utilisateur doit disposer d’autorisations et posséder USE CATALOG le schéma ou avoir CREATE SECRET et USE SCHEMA sur le schéma. Pour savoir comment accorder des privilèges, consultez Gérer les privilèges dans le catalogue Unity.

Avant de commencer

Pour utiliser les secrets du catalogue Unity, vous devez répondre aux exigences suivantes :

• L’espace de travail doit être activé pour le catalogue Unity. Pour une introduction, consultez Qu’est-ce que le catalogue Unity ?.
• Vous devez accéder aux secrets depuis des ressources de calcul compatibles avec Unity Catalog. Azure Databricks recommande l’une des options suivantes :
  • Tâches et notebooks serverless avec la version 4 de l’environnement ou une version ultérieure.
  • Calcul classique en mode d’accès standard exécutant Databricks Runtime 17.3 LTS ou version ultérieure.
• Pour récupérer des secrets avec dbutils, le calcul doit exécuter Databricks Runtime 17.3 LTS ou version ultérieure, ou l’environnement serverless version 4 ou ultérieure.

Créer un secret

La création d’un secret nécessite que vous disposiez de l’autorisation USE CATALOG et que vous soyez propriétaire du schéma, ou que vous disposiez des autorisations CREATE SECRET et USE SCHEMA sur le schéma. Consultez Privilèges pour les secrets du catalogue Unity.

Explorateur de catalogues

1. Dans votre espace de travail Azure Databricks, cliquez sur Catalogue pour ouvrir l’Explorateur de catalogues.
2. Accédez au schéma dans lequel vous souhaitez créer le secret.
3. Cliquez sur Créer un > secret.
4. Entrez un nom et une valeur. Si vous le souhaitez, ajoutez un commentaire et une date d’expiration. Si un secret expire, l’Explorateur de catalogues affiche un avertissement.
5. Cliquez sur Créer.

API REST

Exécutez la commande cURL suivante en utilisant le point de terminaison /api/2.1/unity-catalog/secrets :

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 la valeur d’un secret, vous devez avoir READ SECRET sur le secret ou sur un catalogue parent ou un schéma parent.

Utilitaire secrets (dbutils.secrets)

Azure Databricks recommande d’utiliser dbutils pour lire les secrets, car cela permet le masquage des secrets. Cette option nécessite Databricks Runtime 17.3 LTS ou version ultérieure, ou l’environnement serverless version 4 ou ultérieure.

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

API REST

Avertissement

Les valeurs secrètes récupérées avec l’API REST de Unity Catalog ne sont pas soumises au masquage des secrets, bien que l’accès soit toujours consigné dans les journaux d’audit. Azure Databricks recommande dbutils à la place.

Pour renvoyer la valeur, définissez include_value=true et lisez le effective_value champ 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.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 d’un secret individuel afin de contrôler l’accès. L’héritage des privilèges s’applique. Pour en savoir plus sur l’octroi et la révocation de privilèges, consultez Gérer les privilèges dans le catalogue Unity.

Accorder la possibilité de créer des secrets

Explorateur de catalogues

1. Dans l’Explorateur de catalogues, accédez au schéma.

2. Cliquez sur l’onglet Autorisations .

3. Cliquez sur Accorder.

4. Sélectionnez les principaux auxquels accorder l’accès, puis sélectionnez CREATE SECRET.

   Si un principal n’a pas USE SCHEMA, un avertissement vous invite à le lui accorder. USE SCHEMA est également nécessaire pour créer des secrets dans le schéma.

5. Cliquez sur Confirmer.

SQL

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

API REST

Exécutez la commande cURL suivante en utilisant le point de terminaison /api/2.1/unity-catalog/permissions/schema/{schema_name} :

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

Explorateur de catalogues

1. Dans l’Explorateur de catalogues, accédez au secret et cliquez dessus.
2. Cliquez sur l’onglet Autorisations .
3. Cliquez sur Accorder.
4. Sélectionnez les principaux et les privilèges à accorder, puis cliquez sur Confirmer.

SQL

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

API REST

Exécutez la commande cURL suivante en utilisant le point de terminaison /api/2.1/unity-catalog/permissions/secret/{catalog.schema.secret} :

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

Répertorier, mettre à jour et supprimer des secrets

Lister les secrets

Explorateur de catalogues

1. Dans l’Explorateur de catalogues, accédez au schéma.
2. Dans le volet Vue d’ensemble , cliquez sur Secrets pour afficher tous les secrets dans le schéma.

Utilitaire secrets (dbutils.secrets)

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

API REST

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

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 avoir WRITE SECRET sur le secret.

Explorateur de catalogues

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. Entrez une nouvelle valeur ou une date d’expiration, puis cliquez sur Confirmer.

API REST

Les demandes de mise à jour nécessitent le update_mask paramètre. Seuls les champs inclus dans les deux update_mask et le corps de la demande sont mis à jour :

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

Explorateur de catalogues

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 que vous souhaitez 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.

API REST

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 Unity Catalog

La system.access.audit table système enregistre les événements liés aux secrets du catalogue Unity. Par exemple, pour afficher tous les événements secrets d’un utilisateur à une date spécifique, exécutez la requête suivante :

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 journaux d’audit, consultez la référence de la table système des journaux d’audit.

Chiffrer les valeurs de secret avec des clés gérées par le client

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

Limitations

Les secrets du catalogue Unity présentent les limitations suivantes :

• Aucun entrepôt SQL. Les secrets du catalogue Unity ne sont pas pris en charge sur les entrepôts SQL. Ils nécessitent Databricks Runtime 17.3 LTS ou une version ultérieure sur des ressources de calcul avec Unity Catalog activé, ou en mode serverless.
• Aucune découverte globale. Les secrets du catalogue Unity n’apparaissent pas dans la recherche globale.
• Aucune prise en charge des autorisations BROWSE. BROWSE sur un catalogue ne s’applique pas aux secrets du catalogue Unity. Pour rendre un secret visible, accorder READ SECRET ou REFERENCE SECRET sur le secret concerné ou sur son schéma.
• Aucun script init. Vous ne pouvez pas utiliser les secrets du catalogue Unity dans les scripts d’init global ou de cluster. Azure Databricks recommande d’utiliser des fonctionnalités dédiées au lieu de scripts init si possible.
• Aucun schéma d’informations. Les tables de schéma d’informations pour les secrets ne sont pas encore disponibles. Utilisez l’Explorateur de catalogues ou l’API REST pour la découverte.
• dbutils étendue du runtime. dbutils la récupération est prise en charge sur les blocs-notes et travaux soutenus par Databricks Runtime. Les contextes non-Databricks Runtime, tels que le développement à distance ou les modes d’exécution JAR compilés, ne sont pas pris en charge.
• Étendue de l’API OAuth. L’API des secrets de Unity Catalog n’est accessible qu’avec la portée d’API OAuth unity-catalog. Utilisez l’étendue de l’API secrets uniquement pour les secrets Azure Databricks au niveau de l’espace de travail.
• Limites de quota. Jusqu’à 100 secrets par schéma et 1 000 par metastore.