Tutoriel : Définissez l’accès d’un agent 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 ressources dont il a besoin pour une tâche spécifique. Fournir à l’agent un jeton OAuth limité à un rôle. Les requêtes faites avec ce jeton utilisent les permissions du rôle plutôt que les permissions plus larges de l’utilisateur authentifiant ou du principal du service.

Scenario

Un agent de support IA a besoin de résumés de tickets et de statut, mais pas des coordonnées client contenant des informations personnelles identifiables (PII). Son principal de service d’authentification dispose d’un accès plus large et peut lire les deux ensembles de données.

Dans cet exemple, le support.tickets schéma contient des résumés de tickets et un statut sans informations personnelles clients. Les coordonnées 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 principal de service l’autorisation Assume dessus. Avec un jeton adapté à ce rôle, l’agent peut lire les tickets de support mais ne peut pas accéder aux coordonnées clients.

Le rôle peut hériter des privilèges de données des groupes parents, et les autorisations de catalogue ou de schéma peuvent s’appliquer à toutes les tables qu’ils contiennent. Pour cet exemple, vérifiez que ces autorisations ne donnent pas au rôle l’accès à la table de contact client. Consultez l’héritage des privilèges. Modifier les autorisations partagées affecte les autres utilisateurs et rôles, donc utilisez un espace de travail de test au lieu de supprimer l’accès des autres utilisateurs.

Ce tutoriel s’adresse 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’application intégrée ou l’autorisation utilisateur. Consultez Authentification pour les agents.

Prerequisites

• Un espace de travail avec Unity Catalog activé et RBAC activé. Voir Activer le RBAC.
• Des permissions d’administrateur de compte ou d’administrateur d’espace de travail pour créer le rôle, accorder l’autorisation Assume, puis l’assigner à l’espace de travail. Voir Qui peut gérer des groupes ?.
• Propriété du catalogue support, ou MANAGE sur celui-ci.
• Autorisations d’administrateur de l’espace de travail ou l’autorisation Peut gérer sur l’entrepôt SQL utilisé dans l’exemple.
• Tables existantes support.tickets.open_cases et support.customers.contact_details. Utilisez des données fictives pour les tests et remplacez vos propres noms si nécessaire.
• Un principal de service assigné à l’espace de travail, avec accès SQL Databricks, peut utiliser l’entrepôt et permet d’interroger les deux tables. Il nécessite un secret OAuth qui autorise le scope sql pour l’authentification machine-à-machine (M2M). Consultez l’étape 1 : Créer un secret OAuth.
• curl Dans un environnement de confiance où l’on peut demander et tester des tokens.
• Un lecteur d’audit avec accès à system.access.audit pour vérifier l’activité de l’agent dans le cadre de ce rôle. Voir Vérifier l’attribution de l’audit.

Utilisez un principal de service managé Azure Databricks pour cet exemple OAuth M2M. Les principaux de service managés Microsoft Entra ID utilisent une configuration d’authentification différente. Consultez Autoriser l'accès principal de service pour Azure Databricks avec OAuth.

Étape 1 : Créer le rôle

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

Console de compte

1. En tant qu’administrateur de compte, connectez-vous à la console de compte.
2. Dans la barre latérale, cliquez sur Gestion des utilisateurs.
3. Dans l’onglet Groupes, cliquez sur Ajouter un groupe.
4. Appuyez sur role-support-agent. N’ajoutez pas de membres.
5. Cliquez sur Confirmer.
6. Assignez le groupe à l’espace de travail avec l’accès SQL de Databricks. Voir Affecter un groupe à un espace de travail.

Paramètres d’administrateur de l’espace de travail

1. En tant qu’administrateur d’espace de travail, connectez-vous à l’espace de test.
2. Cliquez sur votre nom d’utilisateur dans la barre supérieure, puis sélectionnez Paramètres.
3. Cliquez sur l’onglet Identité et accès .
4. À côté de Groupes, cliquez sur Gérer.
5. Cliquez sur Ajouter un groupe, puis sur Nouveau groupe.
6. Saisissez role-support-agent et sélectionnez Accès SQL Databricks.
7. Cliquez sur Ajouter. N’ajoutez pas de membres.

Cela assigne également le groupe à l’espace de travail et vous accorde l’autorisation Gérer sur celui-ci.

Le droit d’accès SQL de Databricks accorde l’accès aux fonctionnalités de Databricks SQL, y compris les tableaux de bord, les requêtes et les SQL warehouses. L’exemple utilise des requêtes SQL. Si votre agent a également besoin de fonctionnalités essentielles de l’espace de travail telles que des carnets, des jobs, des modèles ou des pipelines, accordez l’accès à l’espace de travail. Consultez les droits d’accès. Vous configurez les privilèges de données et les autorisations de l’entrepôt à l’étape 2.

Dans cet exemple, vous accordez la permission Assume séparément au lieu d’ajouter le principal du service comme membre. L’adhésion ajoute également les autorisations du groupe à l’identité du principal du service.

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

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

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 d’espace de travail ou utilisateur avec la fonction Peut gérer sur le warehouse, accordez au rôle l’accès au warehouse :

1. Dans la barre latérale de l’espace de travail, cliquez sur SQL Warehouses.
2. Cliquez sur à côté de l’entrepôt, puis cliquez sur Permissions.
3. Ajouter role-support-agent avec Utilisable.

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

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

Accordez au principal de service l’autorisation Assume en utilisant l’une ou l’autre méthode :

Console de compte

1. En tant qu’administrateur de compte, ouvrez la console de compte et cliquez sur Gestion utilisateur.
2. Dans l’onglet Groupes, cliquez sur role-support-agent.
3. Cliquez sur l’onglet Permissions , puis cliquez sur Accorder l’accès.
4. Recherchez et sélectionnez le principal de service, sélectionnez Assumer, puis cliquez sur Enregistrer.

Paramètres d’administrateur de l’espace de travail

1. En tant qu’administrateur d’espace de travail avec la permission de gérer le rôle, ouvrez Paramètres>Identité et accès dans l’espace de travail de test.
2. À côté de Groupes, cliquez sur Gérer, puis sélectionnez role-support-agent.
3. Cliquez sur Permissions, puis sur Grant access.
4. Recherchez et sélectionnez le service principal, sélectionnez Assume, puis cliquez sur Enregistrer.

Étape 4 : Demander un jeton à portée de rôle

Dans votre environnement de requête de token de confiance, définissez ces variables d’environnement :

• DATABRICKS_HOST: l’URL de l’espace de travail, incluant https:// et sans slash final.
• CLIENT_ID et CLIENT_SECRET: l’ID de l’application du principal de service 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 d’espaces de travail et les gestionnaires de groupes peuvent également récupérer le id du groupe via l’API des groupes de compte.
• DATABRICKS_SQL_WAREHOUSE_ID: l’ID de l’entrepôt attribué à l’étape 2. Il se trouve après /sql/1.0/warehouses/ dans le chemin HTTP de l’entrepôt. Consultez les détails de connexion pour une ressource de calcul Azure Databricks.

Demandez un jeton au niveau de l’espace de travail avec le assume_group paramètre et le sql scope OAuth. Le scope limite le jeton aux API SQL. Les privilèges de données du rôle déterminent quelles tables il peut interroger. Voir les secrets OAuth à portée limitée.

Pour demander le jeton, exécutez :

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"

Réglez DATABRICKS_TOKEN sur la valeur access_token de la réponse. Utilisez la valeur expires_in pour déterminer quand demander un remplacement. Les requêtes de jetons au niveau du compte ne prennent pas en charge assume_group. Voir Assumer un rôle.

Étape 5 : Vérifier les droits d’accès du jeton

Effectuez ces vérifications dans l’environnement de confiance avant de fournir le jeton à l’agent.

D’abord, obtenez une base de référence avec un jeton pour l’identité du principal du service. Répétez la requête à l’étape 4 sans le paramètre assume_group, et définissez temporairement DATABRICKS_TOKEN sur ce jeton. Effectuez les deux requêtes à cette étape et vérifiez qu’elles réussissent. Ensuite, remettez DATABRICKS_TOKEN sur le jeton à portée de rôle et recommencez les vérifications.

Lire les tickets de support

Exécutez cette requête avec le jeton à portée de rôle :

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 requête réussit car le rôle peut lire support.tickets. Vérifiez que le/la status.state de la réponse est SUCCEEDED. Si c’est PENDING ou RUNNING, utilisez le statement_id retourné pour récupérer le résultat avec le même jeton :

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

Voir API d’exécution des instructions : Exécuter SQL sur des entrepôts pour l’état 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 et entrepôt avec le même scope de rôle, exécutez :

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, récupérez le résultat décrit dans la section précédente. La requête échoue à cause d’une erreur d’autorisation sur status.error, bien qu’elle réussisse avec le jeton propre au principal du service. Une réponse HTTP réussie seule ne signifie pas que la requête a réussi. Une table manquante, un jeton expiré ou une erreur d’entrepôt ne prouvent pas que les privilèges de données du rôle sont correctement configurés.

Vérifier l’attribution de l’audit

Utilisez un lecteur d’audit avec l’accès décrit dans Vérifier l’attribution de l’audit. Inspectez les événements de requête de test dans system.access.audit: identity_metadata.run_as identifie le rôle autorisant, run_as_display_name contient role-support-agent, et run_by identifie le principal de service qui a initié la requête. Les données d’audit sont mises à jour tout au long de la journée, donc un événement récent peut ne pas apparaître immédiatement. Voir la référence des métadonnées d’identité.

Étape 6 : Configurez l’agent

Configurez le client Azure Databricks de l'agent avec l'URL de l'espace de travail et le jeton vérifié limité à un rôle. Fournissez uniquement ce jeton à l’agent, pas le secret OAuth du principal de service ni son jeton sans portée. Le jeton à portée de rôle limite les requêtes effectuées avec ce jeton. Il ne supprime pas les autorisations du principal de service 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 :

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

Le SDK lit le jeton depuis l’environnement en utilisant une authentification unifiée. Fournir un jeton d’accès ne donne pas au SDK les identifiants nécessaires pour demander un nouveau jeton. Pour un agent de longue durée, faites en sorte qu’un composant de confiance demande et fournisse un jeton de remplacement limité au rôle avant l’expiration du jeton.

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 la CLI Databricks comme décrit dans Installer ou mettre à jour la CLI Databricks, puis s’authentifie en utilisant sa propre connexion et un profil séparé :

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 :

databricks auth token --profile support-agent

Le développeur utilise le DATABRICKS_TOKEN retourné comme access_token pour les vérifications de requête à portée de rôle à l’étape 5. Les événements d’audit pour ces requêtes identifient le développeur comme run_by. Le jeton retourné par la CLI Databricks expire. Le développeur récupère un nouveau token si nécessaire. Voir API (jetons d’accès OAuth).

Nettoyage

Pour un test temporaire, supprimez la configuration du jeton de l’agent et révoquez l’attribution de l’autorisation Assume créée pour le test une fois 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