Aller au contenu principal

Authentification pour les agents d'IA

Les agents d'IA ont souvent besoin de s'authentifier auprès d'autres Ressources pour accomplir des tâches. Par exemple, un agent déployé pourrait avoir besoin d'accéder à un index de recherche IA pour interroger des données non structurées, à un endpoint de diffusion pour appeler un modèle de fondation, 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 Endpoints Model Serving, consultez Authentification pour les agents d'IA (Model Serving).

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

Méthode

Description

Quand utiliser

Autorisation d'application

L'agent s'authentifie à l'aide d'un Service Principal automatiquement créé avec des autorisations cohérentes. Anciennement appelé authentification 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 en utilisant l'identité de l'utilisateur qui effectue la requête. Authentification « Au nom de » (OBO) précédemment appelée.

À utiliser lorsque vous avez besoin d’autorisations spécifiques à l’utilisateur, de pistes d’audit ou d’un contrôle d’accès affiné avec Unity Catalog.

Méthode

Description

Quand utiliser

Autorisation d'application

L'agent s'authentifie à l'aide d'un Service Principal automatiquement créé avec des autorisations cohérentes. Anciennement appelé authentification 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 en utilisant l'identité de l'utilisateur qui effectue la requête. Authentification « Au nom de » (OBO) précédemment appelée.

À utiliser lorsque vous avez besoin d’autorisations spécifiques à l’utilisateur, de pistes d’audit ou d’un contrôle d’accès affiné avec Unity Catalog.

Vous pouvez combiner les deux méthodes en un seul agent. Par exemple, utilisez l’autorisation d’application pour accéder à un index de recherche AI partagé tout en utilisant l’autorisation utilisateur pour query 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 les ressources, les étendues et les variables d’environnement dans un fichier databricks.yml et déployez avec databricks bundle deploy. Recommandé lorsque vous souhaitez une gestion des versions basée sur Git, le CI/CD ou l'expédition du même agent sur plusieurs Workspace. Tous les templates d'agent sont livrés avec un databricks.yml.

Les deux chemins 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 par l'un ou l'autre chemin, vous devez disposer de l'autorisation Can Manage sur la ressource et l'application.

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

Autorisation de l’application

Par défaut, 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 il 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 expérimentation MLflow pour logguer des traces et des résultats d'évaluation. Accorder la permission Can Edit du Service Principal sur l'expérimentation.

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

Consultez Ajouter une ressource d'Experimentation MLflow à une application Databricks.

Accorder des autorisations à d’autres ressources Databricks

Si votre agent utilise d'autres ressources Databricks, tels que les agents Genie, les index AI Search ou les SQL Warehouse, accordez les autorisations de 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.

Lorsque vous accordez l'accès aux ressources Unity Catalog, vous devez également accorder 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 warehouses et à ses fonctions Unity Catalog.

Ajoutez des ressources à l'application via la section **Ressources d'application** lorsque vous créez ou modifiez l'application dans le workspace Databricks.

  1. Cliquez sur Modifier sur la page d'accueil de votre application.
  2. Accédez à l'étape Configurer .
  3. Dans Ressources d'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 d’interface utilisateur de Workspace

Ressource et autorisation des 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é)

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 d’interface utilisateur de Workspace

Ressource et autorisation des 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é)

Can Connect and Create

database avec CAN_CONNECT_AND_CREATE

Lakebase (autoscaling)

Can Connect and Create

postgres avec CAN_CONNECT_AND_CREATE

Suivez 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 de l'utilisateur

info

Aperçu

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

L'autorisation d'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 affinés appliqués par Unity Catalog.
  • Pistes d'audit spécifiques à l'utilisateur
  • Application automatique des filtres au niveau des lignes et des masques de colonnes

Utilisez l'autorisation utilisateur lorsque votre agent doit accéder aux 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 d'utilisateur pour votre agent :

  1. Ajouter des périmètres d'API à votre application : définissez les APIs Databricks auxquelles l'application peut accéder au nom des utilisateurs. Voir Ajouter des portées à une application.
  2. Les identifiants utilisateur sont restreints : Databricks prend les identifiants de l'utilisateur et les limite uniquement aux API scopes que vous avez définis.
  3. Transfert de jeton : Le jeton à portée réduite est mis à la disposition de votre application via 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. Voir Ajouter des étendues à une application pour des instructions détaillées.

Les Agents avec autorisation d'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 d’utilisateur, vous devez ajouter des étendues d’autorisation à votre application. Les périmètres restreignent ce que l'application peut faire au nom de l'utilisateur. Pour la liste des étendues disponibles et la sémantique des étendues, consultez Sécurité basée sur les étendues et escalade 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 portée et sélectionnez les portées dont l'application a besoin pour accéder aux ressources au nom de l'utilisateur.
  3. Enregistrer les modifications et redémarrer 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 construisez 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 modèles fournis à partir de databricks/app-templates, importez l'utilitaire fourni :

    Python
    from databricks_app.utils import get_user_workspace_client

    Sinon, importez depuis les 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 de workspace avec ces identifiants 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 :

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 effectue une requête. L'initialisation lors du 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 portées et la compréhension de la sécurité basée sur les portées, consultez Sécurité basée sur les portées et élévation des privilèges. Demandez uniquement les étendues minimales dont votre agent a besoin et enregistrez chaque action effectuée au nom d'un utilisateur ; consultez Meilleures pratiques pour l'autorisation des utilisateurs.

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 pas en tant que Service Principal Databricks de l’application. Si le jeton transmis est manquant, get_user_workspace_client() revient au Service Principal Databricks sans erreur, de sorte que l'agent peut renvoyer une réponse normale tout en agissant comme l'application. Pour vérifier, ajoutez un outil whoami et invoquez-le en tant que vous-même. Si cela renvoie votre nom d’utilisateur, l’autorisation utilisateur fonctionne.

current_user.me() est couvert par le scope iam.current-user:read default, vous n'avez donc pas besoin d'ajouter de scopes 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éployer l'agent. Consultez Créer un agent IA et le déployer sur Databricks Apps.

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

  1. Les changements de portée prennent effet immédiatement, mais les caches internes peuvent prendre jusqu'à 5 minutes pour refresh — attendez ce délai avant de tester (aucun redémarrage de l'application requis). Effacez toujours les cookies de votre navigateur pour l'URL de l'application (voir le menu déroulant ci-dessous pour les étapes), sinon la session réutilise les jetons émis avant le changement de périmètre.
  2. Confirmez que vous disposez de l'autorisation CAN USE sur l'application. Voir Configurer les autorisations d'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 périmètres demandés.
  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 DevTools : appuyez sur **F12**, ou **Cmd+Option+I** sur macOS, ou **Ctrl+Shift+I** sur Windows ou Linux.
  2. Ouvrez l'onglet Application tab .
  3. Sous Stockage > Cookies , sélectionnez l'URL de votre application.
  4. Faites un clic droit sur chaque cookie et choisissez Supprimer .

Chrome DevTools affichant le tab Application, les cookies d'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 s'est rabattu sur le 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 a des périmètres configurés.
  3. get_user_workspace_client() est appelé à l'intérieur du gestionnaire @invoke ou @stream, et non au Startup.
  4. Le code utilise get_user_workspace_client() et non WorkspaceClient().

Quelques points à surveiller :

  • Retirez l’outil whoami avant la production. C'est uniquement un diagnostic et cela expose l'identité de l'utilisateur à toute personne pouvant invoquer l'agent.
  • Testez avec un second utilisateur. Une vérification à utilisateur unique confirme que le jeton est transmis ; un deuxième appelant confirme que chaque requête obtient sa propre identité au lieu d'un fallback partagé.
  • N'enregistrez jamais le jeton transmis. Voir les bonnes pratiques en matière d'autorisation d'utilisateur.
  • Pour vérifier une étendue spécifique , remplacez current_user.me() par un appel qui requiert cette étendue. Par exemple, une instruction SELECT current_user() sur un warehouse exerce l'étendue sql de bout en bout.

S’authentifier auprès des serveurs MCP Databricks

Les serveurs MCP gérés de Databricks exposent les index de recherche 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 par Databricks.

Pour s'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 serveurs 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 comme 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 (dont les noms d'application sont préfixés par mcp-) ne sont pas encore pris en charge en tant que ressources de bundle. Accorder manuellement le Service Principal de l'agent Can Use sur l'application serveur MCP avec databricks apps update-permissions. Consultez le skill custom-mcp-server dans le repository de modèles d'agent.

Étapes suivantes