Aller au contenu principal
Dernière mise à jour le

Tutoriel : Délimiter l'accès d'un agent d'IA avec RBAC

Utilisez le contrôle d'accès basé sur les rôles (RBAC) pour limiter l'accès d'un agent IA aux données et aux ressources dont il a besoin pour une tâche spécifique. Fournissez à l'agent un jeton OAuth limité à un rôle. Les requêtes effectuées avec ce jeton utilisent les autorisations du rôle au lieu des autorisations plus larges de l'utilisateur authentifié ou du Service Principal Databricks.

Scénario​

Un agent d'assistance IA a besoin des résumés et du statut des tickets, mais pas des coordonnées des clients contenant des informations personnellement identifiables (PII). Son service principal d'authentification Databricks dispose d'un accès plus large et peut lire les deux datasets.

Dans cet exemple, le schéma support.tickets contient des résumés de tickets et leur statut sans les informations personnellement identifiables des clients. Les coordonnées des clients sont stockées séparément dans support.customers.contact_details.

Vous créez role-support-agent, lui accordez un accès en lecture à support.tickets et accordez au Service Principal Databricks l'autorisation Assume sur celui-ci. Avec un jeton limité à ce rôle, l'agent peut lire les tickets de support mais ne peut pas accéder aux coordonnées du client.

Le rôle peut hériter des privilèges de données des groupes parents, et des octrois de catalogue ou de schéma peuvent s'appliquer à toutes les tables situées en dessous. Pour cet exemple, vérifiez que ces octrois ne donnent pas au rôle l'accès à la table de contact client. Voir Héritage des privilèges. La modification des octrois partagés affecte les autres utilisateurs et rôles, utilisez donc un workspace de test plutôt que de supprimer l'accès des autres utilisateurs.

Ce didacticiel est destiné aux agents personnalisés, auto-hébergés ou tiers qui acceptent un jeton d'accès OAuth que vous fournissez. Pour les agents déployés sur Databricks Apps, utilisez l'autorisation d'application ou d'utilisateur intégrée. Consultez Authentification pour les agents.

Prérequis​

  • Un Workspace avec Unity Catalog activé avec le RBAC activé. Voir Activer le RBAC.
  • Autorisations d'administrateur de compte ou d'administrateur de workspace pour créer le rôle, accorder l'autorisation Assume et l'affecter au workspace. Voir Qui peut gérer les groupes ?.
  • Propriété du, ou MANAGE sur, le catalogue support.
  • Permissions d'administrateur du workspace ou Peut gérer sur le SQL warehouse utilisé dans l'exemple.
  • Tables existantes support.tickets.open_cases et support.customers.contact_details. Utilisez des données de test fictives et substituez vos propres noms si nécessaire.
  • Un Service Principal Databricks attribué au Workspace, avec un accès Databricks SQL, l'autorisation Can use sur le warehouse et l'autorisation de query les deux tables. Il nécessite un secret OAuth qui autorise le scope sql pour l'authentification machine à machine (M2M). Consultez Étape 1 : Créer un secret OAuth.
  • curl dans un environnement de confiance où vous pouvez demander et tester des jetons.
  • Un lecteur d’audit ayant accès à system.access.audit pour vérifier l’activité de l’agent sous le rôle. Voir Vérifier l’attribution d’audit.

Étape 1 : créez le rôle​

Pour ce tutoriel, créez un groupe de comptes vide pour servir de rôle.

  1. En tant qu'administrateur de compte, Connexion à la console de compte.
  2. Dans la barre latérale, cliquez sur Gestion des utilisateurs .
  3. Dans le Groupes tab, cliquez sur Ajouter un groupe .
  4. Saisissez role-support-agent. Ne pas ajouter de membres.
  5. Cliquez sur Confirmer .
  6. Attribuez le groupe au workspace avec l’accès Databricks SQL . Consultez Attribuer un groupe à un workspace.

Le droit d’accès Databricks SQL donne accès aux fonctionnalités Databricks SQL, notamment aux tableaux de bord, aux query et aux SQL warehouses. L’exemple utilise des query SQL. Si votre agent a également besoin de fonctionnalités de base du workspace telles que des notebooks, des jobs, des modèles ou des pipelines, accordez l’accès au Workspace. Voir Droits d’accès. Vous configurez les privilèges de données et les permissions de warehouse à l’étape 2.

Dans cet exemple, vous accordez l'autorisation Assume séparément au lieu d'ajouter le Service Principal Databricks en tant que membre. L'appartenance ajoute également les permissions du groupe à la propre identité du Service Principal Databricks.

Étape 2 : Accorder au rôle l'accès aux tickets de support​

En tant que propriétaire du catalogue ou utilisateur ayant MANAGE sur support, exécutez :

SQL
GRANT USE CATALOG ON CATALOG support TO `role-support-agent`;
GRANT USE SCHEMA, SELECT ON SCHEMA support.tickets TO `role-support-agent`;

En tant qu’administrateur de workspace ou utilisateur disposant de l’autorisation Peut gérer sur le warehouse, accordez à l’utilisateur le rôle d’accès au warehouse :

  1. Dans la barre latérale du Workspace, cliquez sur SQL Warehouse .
  2. Cliquez sur le menu kebab Icône du menu kebab. en regard du warehouse, puis cliquez sur Autorisations .
  3. Ajoutez role-support-agent avec Peut utiliser .

La concession SELECT au niveau du schéma s’applique à toutes les tables et vues actuelles et futures dans support.tickets. Il n’accorde pas l’accès à support.customers ou à d’autres schémas. Pour limiter le rôle à une table, accordez SELECT sur cette table à la place. Voir Gérer les privilèges dans Unity Catalog.

Étape 3 : Accorder l’autorisation d’assumer le rôle​

Accordez au service principal Databricks l’autorisation Assume en utilisant l’une des méthodes suivantes :

  1. En tant qu'administrateur de compte, ouvrez la console de compte et cliquez sur Gestion des utilisateurs .
  2. Sur le Groupes tab, cliquez sur role-support-agent.
  3. Cliquez sur le Permissions tab, puis cliquez sur Accorder l’accès .
  4. Recherchez le Service Principal Databricks, sélectionnez Assumer , puis cliquez sur Enregistrer .

Étape 4 : demander un jeton avec portée de rôle​

Dans votre environnement de demande de jeton approuvé, définissez ces variables d’environnement :

  • DATABRICKS_HOST: l’URL du workspace, incluant https:// et sans barre oblique à la fin.
  • CLIENT_ID et CLIENT_SECRET: l'identifiant d'application du Service Principal Databricks et le secret OAuth.
  • ROLE_GROUP_ID: l’ID numérique de role-support-agent. Un administrateur de compte peut le trouver à la fin de l’URL du groupe dans la console de compte. Les administrateurs de compte, les administrateurs de workspace et les gestionnaires de groupe peuvent également récupérer le id du groupe à l’aide de l’ API de groupes de compte.
  • DATABRICKS_SQL_WAREHOUSE_ID: l'ID du warehouse accordé à l'étape 2. Il suit /sql/1.0/warehouses/ dans le chemin HTTP du warehouse. Voir Obtenir les détails de connexion pour une ressource de compute Databricks.

Demander un jeton au niveau du workspace avec le parameter assume_group et le scope OAuth sql. Le scope limite le jeton aux API SQL. Les privilèges de données du rôle déterminent les tables qu'il peut query. Voir Secrets OAuth à portée limitée.

Pour demander le jeton, exécutez :

Bash
curl --request POST \
  --url "$DATABRICKS_HOST/oidc/v1/token" \
  --user "$CLIENT_ID:$CLIENT_SECRET" \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'scope=sql' \
  --data-urlencode "assume_group=$ROLE_GROUP_ID"

Définissez DATABRICKS_TOKEN sur la valeur access_token à partir de la réponse. Utilisez la valeur expires_in pour déterminer quand demander un remplacement. Les demandes de jeton au niveau du compte ne prennent pas en charge assume_group. Voir Assumer un rôle.

Étape 5 : Vérifier l’accès du jeton​

Exécutez ces vérifications dans l’environnement approuvé avant de fournir le jeton à l’agent.

Tout d'abord, obtenez une ligne de base avec un jeton pour l'identité propre du Service Principal Databricks. Répétez la demande à l'étape 4 sans le parameter assume_group et définissez temporairement DATABRICKS_TOKEN sur ce jeton. Exécutez les deux queries de cette étape et vérifiez qu’ils aboutissent. Ensuite, rétablissez DATABRICKS_TOKEN sur le jeton à portée de rôle et répétez les vérifications.

Lire les tickets d’assistance​

Exécutez cette requête avec le jeton limité au rôle :

Bash
curl --request POST \
  --url "$DATABRICKS_HOST/api/2.0/sql/statements" \
  --header "Authorization: Bearer $DATABRICKS_TOKEN" \
  --header 'Content-Type: application/json' \
  --data "{
    \"warehouse_id\": \"$DATABRICKS_SQL_WAREHOUSE_ID\",
    \"statement\": \"SELECT * FROM support.tickets.open_cases LIMIT 10\",
    \"wait_timeout\": \"50s\"
  }"

La query réussit car le rôle peut lire support.tickets. Vérifiez que le status.state de la réponse est SUCCEEDED. Si c’est PENDING ou RUNNING, utilisez le statement_id renvoyé pour récupérer le résultat avec le même jeton :

Bash
curl --request GET \
  --url "$DATABRICKS_HOST/api/2.0/sql/statements/<statement-id>" \
  --header "Authorization: Bearer $DATABRICKS_TOKEN"

Voir API d’exécution d’instructions : exécuter SQL sur des warehouse pour le statut des instructions et la gestion des résultats.

Vérifiez que l'accès aux PII des clients est refusé​

En utilisant le même jeton limité au rôle et le même warehouse, exécutez :

Bash
curl --request POST \
  --url "$DATABRICKS_HOST/api/2.0/sql/statements" \
  --header "Authorization: Bearer $DATABRICKS_TOKEN" \
  --header 'Content-Type: application/json' \
  --data "{
    \"warehouse_id\": \"$DATABRICKS_SQL_WAREHOUSE_ID\",
    \"statement\": \"SELECT 1 FROM support.customers.contact_details LIMIT 1\",
    \"wait_timeout\": \"50s\"
  }"

Si l'instruction est toujours en cours d'exécution, récupérez le résultat comme décrit dans la section précédente. La query échoue avec une erreur de permission dans status.error, bien qu'elle réussisse avec le propre jeton du Service Principal Databricks. Une réponse HTTP de réussite seule ne signifie pas que la query a réussi. Une table manquante, un jeton expiré ou une erreur de warehouse n'établissent pas que les privilèges de données du rôle sont correctement configurés.

Vérifier l’attribution d’audit​

Utilisez un lecteur d’audit avec l’accès décrit dans Vérifier l’attribution d’audit. Inspectez les évènements de query de test dans system.access.audit: identity_metadata.run_as identifie le rôle d'autorisation, run_as_display_name contient role-support-agent et run_by identifie le Service Principal Databricks qui a initié la demande. Les données d’audit sont mises à jour tout au long de la journée ; il est donc possible qu’un évènement récent n’apparaisse pas immédiatement. Consultez Référence des métadonnées d’identité.

Étape 6 : Configurer l'agent​

Configurez le client Databricks de l'agent avec l'URL du workspace et le jeton délimité par rôle vérifié. Ne fournissez que ce jeton à l'agent, pas le secret OAuth du Service Principal Databricks ou son jeton non délimité. Le jeton délimité par rôle limite les requêtes effectuées avec ce jeton. Il ne supprime pas les autorisations du Service Principal Databricks dans d'autres sessions.

Pour un agent qui utilise le SDK Databricks pour Python, définissez DATABRICKS_HOST et DATABRICKS_TOKEN dans l’environnement de l’agent, puis initialisez le client :

Python
from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

Le SDK lit le jeton à partir de l'environnement à l'aide de l'authentification unifiée. La fourniture d'un jeton d'accès ne donne pas au SDK les informations d'identification dont il a besoin pour demander un nouveau jeton. Pour un agent de longue durée, demandez à un composant approuvé de demander et de fournir un jeton de remplacement limité au rôle avant que le jeton n'expire.

Optionnel : utiliser l’identité d’un développeur​

Pour les tests locaux avec authentification utilisateur à machine (U2M), accordez à un développeur participant l'autorisation Assume sur role-support-agent comme à l'étape 3. Le développeur installe le Databricks CLI comme décrit dans Installer ou mettre à jour le Databricks CLI, puis s'authentifie avec sa propre connexion et un profil distinct :

Bash
databricks auth login --host <workspace-url> --profile support-agent

Le développeur sélectionne role-support-agent sous Autoriser en tant que... dans le navigateur et clique sur Continuer , puis récupère le jeton pour ce profil :

Bash
databricks auth token --profile support-agent

Le développeur utilise le access_token renvoyé comme DATABRICKS_TOKEN pour les vérifications de query délimitées par les rôles à l’étape 5. Les événements d’audit pour ces demandes identifient le développeur comme étant run_by. Le jeton renvoyé par le CLI Databricks expire. Le développeur récupère un nouveau jeton en cas de besoin. Voir API (jetons d’accès OAuth).

Nettoyer​

Pour un test temporaire, supprimez la configuration de jeton de l'agent et révoquez l'octroi de l'autorisation Assume créée pour le test une fois que vous avez terminé. Avant de supprimer le rôle, vérifiez s'il possède des assets ou s'il est utilisé par d'autres charges de travail.

Étapes suivantes​

Sur cette page