Aller au contenu principal

Authentification pour les agents IA

Les agents IA doivent souvent s'authentifier auprès d'autres ressources pour accomplir des tâches. Par exemple, un agent déployé peut avoir besoin d'accéder à un index de recherche IA pour query des données non structurées, à un Endpoint de service pour appeler un modèle de base, ou à des fonctions Unity Catalog pour exécuter une logique personnalisée.

Cette page couvre les méthodes d'authentification pour les agents déployés sur Databricks Apps. Pour les agents déployés sur les Endpoint de Model Serving, consultez Authentification pour les agents d'IA (Model Serving).

Databricks Apps propose deux méthodes d'authentification pour les agents. Chaque méthode répond à différents cas d'utilisation :

Méthode

Description

Quand utiliser

Autorisation de l'application

L'agent s'authentifie à l'aide d'un Service Principal créé automatiquement avec des autorisations cohérentes. Anciennement appelée authentification du Service Principal.

Cas d'utilisation le plus courant. À utiliser lorsque tous les utilisateurs doivent avoir le même accès aux Ressources.

Autorisation utilisateur

L’agent s’authentifie à l’aide de l’identité de l’utilisateur qui effectue la requête. Anciennement appelée authentification On-Behalf-Of (OBO).

Utilisez lorsque vous avez besoin d'autorisations spécifiques à l'utilisateur, de journaux d'audit ou d'un contrôle d'accès détaillé avec Unity Catalog.

Méthode

Description

Quand utiliser

Autorisation de l'application

L'agent s'authentifie à l'aide d'un Service Principal créé automatiquement avec des autorisations cohérentes. Anciennement appelée authentification du Service Principal.

Cas d'utilisation le plus courant. À utiliser lorsque tous les utilisateurs doivent avoir le même accès aux Ressources.

Autorisation utilisateur

L’agent s’authentifie à l’aide de l’identité de l’utilisateur qui effectue la requête. Anciennement appelée authentification On-Behalf-Of (OBO).

Utilisez lorsque vous avez besoin d'autorisations spécifiques à l'utilisateur, de journaux d'audit ou d'un contrôle d'accès détaillé avec Unity Catalog.

Vous pouvez combiner les deux méthodes en un seul agent. Par exemple, utilisez l'autorisation de l'application pour accéder à un index AI Search partagé tout en utilisant l'autorisation de l'utilisateur pour interroger des tables spécifiques à l'utilisateur.

Configurez l'authentification avec l'interface utilisateur du Workspace ou les Declarative Automation Bundles.

Vous pouvez configurer tous les paramètres d'authentification de deux manières :

  • **Interface utilisateur du workspace** : Modifiez l'application et gérez les ressources et les étendues à partir de l'étape **Configurer**. Recommandé lorsque vous itérez sur une seule application dans le Workspace.
  • ** Declarative Automation Bundles ** : déclarez des Ressources, des étendues et des variables d'environnement dans un databricks.yml fichier et déployez databricks bundle deploy avec. Recommandé lorsque vous souhaitez une gestion de version basée sur Git, le CI/CD ou déployer le même agent sur plusieurs Workspace. Tous les templates d'agent sont livrés avec un databricks.yml.

Les deux chemins d'accès produisent la même configuration d'exécution. Le reste de cette page présente chaque instruction sous ses deux formes afin que vous puissiez en sélectionner une et rester cohérent au sein de votre projet.

Pour ajouter une ressource à l’application via l’une ou l’autre des voies, vous devez disposer de l’autorisation Can Manage sur la ressource et sur l’application.

Pour la référence complète du bundle, consultez ressource d’application et app.resources. Pour une présentation complète du bundle, consultez Gérer les applications Databricks à l’aide de Declarative Automation Bundles.

Autorisation de l’application

Par default, les Databricks Apps s'authentifient à l'aide de l'autorisation d'application. Databricks crée automatiquement un Service Principal lorsque vous créez l'application, et celui-ci agit comme l'identité de l'application.

Tous les utilisateurs qui interagissent avec l’application partagent les mêmes autorisations définies pour le Service Principal. Ce modèle fonctionne bien lorsque vous souhaitez que tous les utilisateurs voient les mêmes données ou lorsque l’application effectue des opérations partagées non liées aux contrôles d’accès spécifiques à l’utilisateur.

Pour des informations détaillées sur l'autorisation d'application, consultez Autorisation d'application.

Accorder les autorisations à l'expérimentation MLflow

Votre agent a besoin d'accéder à une Experimentation MLflow pour enregistrer les traces et les résultats d'évaluation. Accorder au Service Principal Can Edit l'autorisation sur l'expérimentation.

  1. Cliquez sur Modifier sur la page d'accueil de votre application.
  2. Accédez à l'étape de Configuration .
  3. Dans la section Ressources de l'application , ajoutez la ressource d'Experimentation MLflow avec la permission Can Edit.

Voir Ajouter une ressource d'expérimentation MLflow à une application Databricks.

Accordez des autorisations à d'autres ressources Databricks

Si votre agent utilise d'autres ressources Databricks, telles que des agents Genie, des index de recherche IA ou des SQL warehouses, accordez les autorisations du Service Principal sur chacun d'eux.

Pour accéder au registre d’invites, accordez les autorisations CREATE FUNCTION, EXECUTE et MANAGE sur le schéma Unity Catalog pour le stockage des invites.

Lors de l'octroi de l'accès aux ressources Unity Catalog, vous devez également octroyer des autorisations à toutes les ressources dépendantes en aval. Par exemple, si vous accordez l'accès à un Genie Agent, vous devez également accorder l'accès à ses tables sous-jacentes, à ses SQL Warehouse et aux fonctions Unity Catalog.

Ajoutez des ressources à l'application par la section **Ressources de l'application** lorsque vous créez ou modifiez l'application dans le Databricks Workspace.

  1. Cliquez sur Modifier sur la page d'accueil de votre application.
  2. Accédez à l'étape de Configuration .
  3. Dans Ressources de l'application , cliquez sur + Ajouter une ressource pour chaque ressource utilisée par l'agent et définissez l'autorisation.

Consultez Ajouter des Ressources à une application Databricks pour la liste complète des ressources prises en charge et les captures d'écran.

Le tableau suivant répertorie les autorisations minimales utilisées dans les exemples ci-dessus et la valeur équivalente de Declarative Automation Bundles pour chaque type de ressource :

Type de ressource

Autorisation de l'interface utilisateur du Workspace

Ressource et autorisation pour les Declarative Automation Bundles

SQL Warehouse

Can Use

sql_warehouse avec CAN_USE

Endpoint de Model Serving

Can Query

serving_endpoint avec CAN_QUERY

Fonction Unity Catalog

Can Execute

uc_securable avec securable_type: FUNCTION et EXECUTE

Genie Agent

Can Run

genie_space avec CAN_RUN

Index de recherche IA

Can Select

uc_securable avec securable_type: TABLE et SELECT

Table Unity Catalog

SELECT

uc_securable avec securable_type: TABLE et SELECT

Connexion Unity Catalog

Use Connection

uc_securable avec securable_type: CONNECTION et USE_CONNECTION

Volume Unity Catalog

Can Read OU Can Read and Write

uc_securable avec securable_type: VOLUME et READ_VOLUME ou WRITE_VOLUME

Lakebase (provisionnée)

Can Connect and Create

database avec CAN_CONNECT_AND_CREATE

Lakebase (autoscaling)

Can Connect and Create

postgres avec CAN_CONNECT_AND_CREATE

Type de ressource

Autorisation de l'interface utilisateur du Workspace

Ressource et autorisation pour les Declarative Automation Bundles

SQL Warehouse

Can Use

sql_warehouse avec CAN_USE

Endpoint de Model Serving

Can Query

serving_endpoint avec CAN_QUERY

Fonction Unity Catalog

Can Execute

uc_securable avec securable_type: FUNCTION et EXECUTE

Genie Agent

Can Run

genie_space avec CAN_RUN

Index de recherche IA

Can Select

uc_securable avec securable_type: TABLE et SELECT

Table Unity Catalog

SELECT

uc_securable avec securable_type: TABLE et SELECT

Connexion Unity Catalog

Use Connection

uc_securable avec securable_type: CONNECTION et USE_CONNECTION

Volume Unity Catalog

Can Read OU Can Read and Write

uc_securable avec securable_type: VOLUME et READ_VOLUME ou WRITE_VOLUME

Lakebase (provisionnée)

Can Connect and Create

database avec CAN_CONNECT_AND_CREATE

Lakebase (autoscaling)

Can Connect and Create

postgres avec CAN_CONNECT_AND_CREATE

Appliquez le principe du moindre privilège. Accordez au Service Principal uniquement les autorisations dont l'agent a besoin et utilisez un Service Principal dédié par application. Pour la liste complète, consultez les Bonnes pratiques de sécurité.

Autorisation utilisateur

info

Aperçu

L'autorisation utilisateur est en préversion publique. Votre administrateur Workspace doit l'activer avant que vous ne puissiez utiliser l'autorisation utilisateur.

L’autorisation utilisateur permet à un agent d’agir avec l’identité de l’utilisateur qui effectue la requête. Ceci fournit :

  • Accès par utilisateur aux données sensibles.
  • Contrôles de données granulaires appliqués par Unity Catalog
  • Pistes d'audit spécifiques à l'utilisateur.
  • Application automatique des filtres au niveau des lignes et des masques de colonne

Utilisez l'autorisation de l'utilisateur lorsque votre agent doit accéder à des Ressources en utilisant l'identité de l'utilisateur demandeur au lieu du Service Principal de l'application.

Fonctionnement de l'autorisation utilisateur

Lorsque vous configurez l'autorisation utilisateur pour votre agent :

  1. Ajoutez des périmètres d'API à votre application : Définissez les APIs Databricks auxquelles l'application peut accéder au nom des utilisateurs. Consultez Ajouter des périmètres à une application.
  2. Les identifiants utilisateur sont restreints : Databricks prend les identifiants de l'utilisateur et les restreint aux seules portées d'API que vous avez définies.
  3. Transfert de jeton : le jeton à portée réduite est mis à la disposition de votre application par l'intermédiaire de l'en-tête HTTP x-forwarded-access-token.
  4. MLflow AgentServer stocke le jeton : le serveur d'agents stocke automatiquement ce jeton par requête pour un accès pratique dans le code de l'agent.

Configurez l'autorisation utilisateur en ajoutant des périmètres dans l'interface utilisateur de Databricks Apps lors de la création ou de la modification de votre application, ou par programme à l'aide de l'API. Reportez-vous à Ajouter des périmètres à une application pour des instructions détaillées.

Les agents disposant d'une autorisation utilisateur peuvent accéder aux ressources Databricks suivantes :

  • SQL Warehouse
  • Genie Agent
  • Fichiers et répertoires
  • Endpoint de Model Serving
  • Index de recherche IA
  • Connexions Unity Catalog
  • Tables Unity Catalog

Implémenter l'autorisation utilisateur

Pour implémenter l'autorisation de l'utilisateur, vous devez ajouter des périmètres d'autorisation à votre application. Les périmètres limitent ce que l'application peut faire au nom de l'utilisateur. Pour la liste des périmètres disponibles et la sémantique des périmètres, veuillez consulter Sécurité basée sur les périmètres et élévation de privilèges.

  1. Dans l'interface utilisateur de Databricks, accédez aux paramètres d' Autorisation de votre application.
  2. Sous Autorisation de l'utilisateur , cliquez sur + Ajouter une étendue et sélectionnez les étendues dont l'application a besoin pour accéder aux ressources au nom de l'utilisateur.
  3. Enregistrez les modifications et redémarrez l'application.

Pour configurer l'autorisation utilisateur dans votre code d'agent, récupérez l'en-tête de cette requête auprès de l'AgentServer et créez un client Workspace avec ces informations d'identification.

  1. Dans votre code d'agent, importez l'utilitaire d'authentification :

    Si vous utilisez l’un des Template fournis de databricks/app-templates, importez l’utilitaire fourni :

    Python
    from databricks_app.utils import get_user_workspace_client

    Sinon, importez à partir des utilitaires du serveur d'agents :

    Python
    from agent_server.utils import get_user_workspace_client

    La fonction get_user_workspace_client() utilise le serveur d’agent pour capturer l’en-tête x-forwarded-access-token et construit un client Workspace avec ces informations d’identification d’utilisateur, gérant l’authentification entre l’utilisateur, l’application et le serveur d’agent.

  2. Initialisez le client Workspace au moment de la query, et non au startup de l'application :

important

Appelez get_user_workspace_client() à l'intérieur des gestionnaires invoke et stream, pas dans __init__ ou au Startup. Les identifiants d'utilisateur ne sont disponibles qu'au moment de la query, lorsqu'un utilisateur fait une requête. L'initialisation pendant le Startup de l'application échouera car aucun contexte utilisateur n'existe encore.

Python
# In your agent code (inside invoke or stream handler)
user_client = get_user_workspace_client()


# Use user_client to access Databricks resources with user permissions
response = user_client.serving_endpoints.query(name="my-endpoint", inputs=inputs)

Pour un guide complet sur l'ajout de périmètres et la compréhension de la sécurité basée sur les périmètres, reportez-vous à Sécurité basée sur les périmètres et élévation des privilèges. Demandez uniquement les périmètres minimaux dont votre agent a besoin et consignez chaque action effectuée au nom d'un utilisateur ; référez-vous à Bonnes pratiques pour l'autorisation utilisateur.

Vérifier l'autorisation de l'utilisateur

Après avoir ajouté des étendues et appelé get_user_workspace_client(), confirmez que l'agent s'exécute en tant qu'appelant et non en tant que Service Principal Databricks de l'application. Si le jeton transféré est manquant, get_user_workspace_client() se replie sur le Service Principal Databricks sans générer d'erreur, afin que l'agent puisse renvoyer une réponse d'apparence normale tout en agissant toujours en tant qu'application. Pour vérifier, ajoutez un outil whoami et invoquez-le en tant que vous-même. Si elle renvoie votre nom d'utilisateur, l'autorisation de l'utilisateur fonctionne.

current_user.me() est couvert par le périmètre iam.current-user:read par default, vous n'avez donc pas besoin d'ajouter de périmètres pour ce test.

Python
from agents import Agent, function_tool
from agent_server.utils import get_user_workspace_client

@function_tool
def whoami() -> str:
"""Returns the identity of the current user."""
user_wc = get_user_workspace_client()
return user_wc.current_user.me().user_name

agent = Agent(
name="my-agent",
instructions=(
"When the user asks who they are, call the whoami tool "
"and return the raw result."
),
model="databricks-claude-sonnet-4-6",
tools=[whoami],
)

Redéployez l'agent. Consultez Créer un agent d'IA et le déployer sur Databricks Apps.

Le test d'interface utilisateur Workspace est la vérification la plus rapide et ne nécessite pas de jetons OAuth.

  1. Les modifications de portée prennent effet immédiatement, mais les caches internes peuvent prendre jusqu'à 5 minutes pour se refresh — veuillez attendre ce délai avant de tester (aucun redémarrage d'application n'est requis). Effacez toujours les cookies de votre navigateur pour l'URL de l'application (consultez le menu déroulant ci-dessous pour les étapes), sinon la session réutilise les jetons émis avant la modification de la portée.
  2. Veuillez confirmer que vous disposez de l'autorisation CAN USE sur l'application. Consultez Configurer les autorisations pour une application Databricks.
  3. Ouvrez l'URL de l'application dans un navigateur. Lors de la première visite, acceptez l'invite de consentement pour les étendues demandées.
  4. Dans le chat, demandez Who am I? et confirmez que l'agent renvoie votre nom d'utilisateur (par exemple, you@your-company.com).

Effacer les cookies dans Chrome

  1. Ouvrez les DevTools : appuyez sur **F12**, ou sur **Cmd+Option+I** sur macOS, ou sur **Ctrl+Shift+I** sur Windows ou Linux.
  2. Ouvrez l'onglet Application tab .
  3. Sous Storage > Cookies , sélectionnez l’URL de votre application.
  4. Faites un clic droit sur chaque cookie et choisissez Supprimer .

Chrome DevTools affichant l'tab Application, les cookies pour une URL d'application et le menu Supprimer du clic droit.

Si l'outil renvoie un UUID au lieu d'un nom d'utilisateur, l'en-tête x-forwarded-access-token n'atteint pas l'outil et l'agent a eu recours au Service Principal Databricks de l'application (l'UUID est l'ID client du Service Principal de l'application). Pour diagnostiquer, confirmez chacun des éléments suivants :

  1. L'autorisation utilisateur est activée sur le Workspace.
  2. L'application dispose de périmètres configurés.
  3. get_user_workspace_client() est appelée à l'intérieur du gestionnaire @invoke ou @stream, et non au Startup de l'application.
  4. Le code utilise get_user_workspace_client() et non WorkspaceClient().

Voici quelques points à surveiller :

  • Supprimez l'outil whoami avant la production. C'est à des fins de diagnostic uniquement et cela expose l'identité de l'utilisateur à toute personne pouvant appeler l'agent.
  • Testez avec un second utilisateur. Une vérification mono-utilisateur confirme que le jeton est transmis ; un second appelant confirme que chaque requête obtient sa propre identité au lieu d’un fallback partagé.
  • Ne consignez jamais le jeton transféré. Consultez les bonnes pratiques pour l'autorisation des utilisateurs.
  • Pour vérifier un champ d’application spécifique , remplacez current_user.me() par un appel qui nécessite ce champ d’application. Par exemple, une instruction SELECT current_user() exécutée sur un warehouse exerce le champ d'application sql de bout en bout.

Authentifiez-vous auprès des serveurs MCP Databricks

Les serveurs MCP gérés de Databricks exposent les index de recherche d'IA et les fonctions Unity Catalog comme des outils via des URL de la forme https://<workspace>/api/2.0/mcp/ai-search/<catalog>/<schema> et https://<workspace>/api/2.0/mcp/functions/<catalog>/<schema>. Le préfixe d'URL hérité /api/2.0/mcp/vector-search/ continue de fonctionner pour la rétrocompatibilité. Pour la liste des serveurs disponibles et leurs modèles d'URL, consultez les serveurs MCP gérés Databricks.

Pour vous authentifier, accordez au Service Principal de l'agent (ou à l'utilisateur, si vous utilisez l'autorisation utilisateur) l'accès à chaque ressource en aval dans ces schémas.

Par exemple, si votre agent utilise les URL de serveur MCP suivantes :

  • https://<your-workspace>/api/2.0/mcp/ai-search/prod/customer_support
  • https://<your-workspace>/api/2.0/mcp/ai-search/prod/billing
  • https://<your-workspace>/api/2.0/mcp/functions/prod/billing

Vous devez accorder l'accès à chaque index AI Search dans prod.customer_support et prod.billing, et à chaque fonction Unity Catalog dans prod.billing.

Ajoutez chaque index et fonction en tant que ressource sous **Ressources de l’application**. Suivez les mêmes étapes que Accorder des autorisations à d’autres ressources Databricks.

Les serveurs MCP personnalisés hébergés en tant que leurs propres Applications Databricks (noms d'applications préfixés par mcp-) ne sont pas encore pris en charge en tant que Ressources de bundle. Accordez manuellement le Service Principal de l'agent Can Use sur l'application du serveur MCP avec databricks apps update-permissions. Consultez la compétence de serveur MCP personnalisé dans le repository de templates d'agents.

Étapes suivantes