Partager via

Authentification pour les agents IA

Les agents IA doivent souvent s’authentifier auprès d’autres ressources pour effectuer des tâches. Par exemple, un agent déployé peut avoir besoin d’accéder à un index Recherche vectorielle pour interroger des données non structurées, un point de terminaison de service pour appeler un modèle de base ou des fonctions catalogue Unity pour exécuter une logique personnalisée.

Cette page traite des méthodes d’authentification pour les agents déployés sur Databricks Apps. Pour les agents déployés sur des points de terminaison du service de modèle, consultez Authentification des agents IA (Modèle servant).

Databricks Apps fournit deux méthodes d’authentification pour les agents. Chaque méthode sert différents cas d’usage :

Méthode Descriptif Quand utiliser
Autorisation de l’application L’agent s’authentifie à l’aide d’un principal de service créé automatiquement avec des autorisations cohérentes. Anciennement appelée authentification du principal de service. Cas d’usage le plus courant. Utilisez quand tous les utilisateurs doivent avoir le même accès aux ressources.
Autorisation de l’utilisateur L’agent s’authentifie à l’aide de l’identité de l’utilisateur qui effectue la requête. Précédemment appelée authentification On-Behalf-Of (OBO). Utilisez cette option lorsque vous avez besoin d’autorisations spécifiques à l’utilisateur, de pistes d’audit ou d’un contrôle d’accès affiné avec Le catalogue Unity.

Vous pouvez combiner les deux méthodes dans un seul agent. Par exemple, utilisez l’autorisation d’application pour accéder à un index de recherche vectorielle partagée tout en utilisant l’autorisation utilisateur pour interroger des tables spécifiques à l’utilisateur.

Autorisation de l’application

Par défaut, Databricks Apps s’authentifie à l’aide de l’autorisation d’application. Azure Databricks crée automatiquement un principal de service lorsque vous créez l’application, et agit comme l’identité de l’application.

Tous les utilisateurs qui interagissent avec l’application partagent les mêmes autorisations définies pour le principal de service. 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 plus d’informations sur l’autorisation d’application, consultez Autorisation d’application.

Accorder des autorisations à l’expérience MLflow

Votre agent a besoin d’accéder à une expérience MLflow pour consigner les traces et les résultats d’évaluation.

Accordez au principal de service Can Edit l’autorisation à l'expérience MLflow :

  1. Cliquez sur Modifier sur la page d’accueil de votre application.
  2. Accédez à l’étape Configurer .
  3. Dans la section Ressources de l’application , ajoutez la ressource d’expérience MLflow.

Consultez Ajouter une ressource d’expérience MLflow à une application Databricks.

Accorder des autorisations à d’autres ressources Databricks

Si votre agent utilise d’autres ressources Databricks, telles que les espaces Genie, les index de recherche vectorielle ou les entrepôts SQL, accordez les autorisations du principal de service via l’interface utilisateur Databricks Apps. Consultez Ajouter des ressources à une application Databricks pour obtenir la liste complète des ressources prises en charge et des instructions de configuration.

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

Le tableau suivant répertorie les autorisations minimales requises pour que les agents accèdent aux ressources Databricks courantes :

Type de ressource Autorisation
SQL Warehouse Can Use
Point de terminaison de mise en service de modèles Can Query
Fonction du catalogue Unity CAN Execute
Espace Génie Can Run
Index de recherche vectorielle Can Select
Table de catalogue Unity SELECT
Connexion de catalogue Unity Use Connection
Volume du catalogue Unity Can Read ou Can Read and Write
Lakebase Can Connect and Create

Lorsque vous accordez l’accès aux ressources du catalogue Unity, vous devez également accorder des autorisations à toutes les ressources dépendantes en aval. Par exemple, si vous accordez l’accès à un espace Génie, vous devez également accorder l’accès à ses tables sous-jacentes, entrepôts SQL et fonctions catalogue Unity.

L’utilisateur qui ajoute la ressource doit avoir l’autorisation Can Manage sur la ressource et l’application. Pour obtenir la liste complète des ressources prises en charge et de toutes les autorisations disponibles, consultez les types de ressources pris en charge.

Pour connaître les meilleures pratiques relatives à la gestion sécurisée de l’autorisation d’application, notamment la gestion des informations d’identification et les principes des privilèges minimum, consultez l’autorisation d’application.

Autorisation de l’utilisateur

Important

L’autorisation utilisateur est en aperçu public. Votre administrateur d’espace de travail doit l’activer avant de pouvoir utiliser l’autorisation utilisateur.

L’autorisation de l’utilisateur permet à un agent d’agir avec l’identité de l’utilisateur effectuant la demande. Cela fournit les éléments suivants :

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

Utilisez l’autorisation utilisateur lorsque votre agent doit accéder aux ressources à l’aide de l’identité de l’utilisateur demandeur au lieu du principal du service de l’application.

Fonctionnement de l’autorisation utilisateur

Lorsque vous configurez l’autorisation utilisateur pour votre agent :

  1. Ajoutez des étendues d’API à votre application : définissez les API Databricks auxquelles l’application peut accéder pour le compte des utilisateurs. Voir Ajouter des étendues à une application.
  2. Les informations d’identification de l’utilisateur sont limitées : Azure Databricks accepte les informations d’identification de l’utilisateur et les limite uniquement aux étendues d’API que vous avez définies.
  3. Routage de jetons : le jeton à portée réduite est mis à la disposition de votre application via l’en-tête x-forwarded-access-token HTTP.
  4. MLflow AgentServer stocke le jeton : le serveur d’agent stocke automatiquement ce jeton par demande d’accès pratique dans le code de l’agent.

Configurez l’autorisation utilisateur en ajoutant des étendues dans l’interface utilisateur Databricks Apps lors de la création ou de la modification de votre application, ou par programmation à l’aide de l’API. Pour obtenir des instructions détaillées, consultez Ajouter des étendues à une application .

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

  • SQL Warehouse
  • L'Espace des Génies
  • Fichiers et répertoires
  • Point de terminaison de mise en service de modèles
  • Index de recherche vectorielle
  • Connexions de catalogue Unity
  • Tables de catalogue Unity

Implémenter l’autorisation utilisateur

Pour implémenter l’autorisation utilisateur, vous devez ajouter des étendues d’autorisation à votre application. Les étendues limitent ce que l’application peut faire au nom de l’utilisateur.

  1. Dans l’interface utilisateur Databricks, accédez à vos paramètres d’autorisation Databricks Apps.
  2. Cliquez sur +Ajouter une étendue et sélectionnez les étendues auxquelles vous souhaitez accéder aux ressources pour le compte de l’utilisateur.
  3. Enregistrez les modifications.

Pour configurer l’autorisation utilisateur dans votre code d’agent, récupérez l’en-tête de cette requête à partir de AgentServer et construisez un client d’espace de travail 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 :

    from databricks_app.utils import get_user_workspace_client

    Sinon, importez à partir des utilitaires du serveur d’agent :

    from agent_server.utils import get_user_workspace_client

    La get_user_workspace_client() fonction utilise le serveur agent pour capturer l’en-tête x-forwarded-access-token et construire un client d’espace de travail avec ces informations d’identification utilisateur, la gestion de l’authentification entre l’utilisateur, l’application et le serveur d’agent.

  2. Initialisez le client d’espace de travail au moment de la requête, et non pendant le démarrage de l’application :

    Important

    Appelez get_user_workspace_client() à l’intérieur des gestionnaires invoke et stream, et non pas dans __init__ ni au démarrage de l’application. Les informations d’identification de l’utilisateur sont disponibles uniquement au moment de la requête lorsqu’un utilisateur effectue une demande. L’initialisation au démarrage de l’application échoue, car aucun contexte utilisateur n’existe encore.

    # 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 obtenir un guide complet sur l’ajout d’étendues et la compréhension de la sécurité basée sur l’étendue, consultez l’escalade de privilèges et de sécurité basée sur l’étendue.

S’authentifier auprès des serveurs MCP Databricks

Pour vous authentifier auprès des serveurs MCP Databricks, spécifiez toutes les ressources dont votre agent a besoin dans votre databricks.yaml fichier. Accordez au principal de service de l’application (ou aux utilisateurs, si vous utilisez l’autorisation de l’utilisateur) l’accès à toutes les ressources en aval.

Par exemple, si votre agent utilise les URL du serveur MCP répertoriées ci-dessous, vous devez accorder l’accès à tous les index de recherche vectorielle dans les schémas prod.customer_support et prod.billing ainsi qu'à toutes les fonctions Unity Catalog dans prod.billing.

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

Configurer l’authentification avec les bundles de ressources Databricks

Vous pouvez configurer tous les paramètres d’authentification par programmation à l’aide des bundles de ressources Databricks au lieu de l’interface utilisateur Databricks Apps. Cette page affiche la configuration basée sur l’interface utilisateur pour illustrer les ressources et autorisations nécessaires, mais la même configuration peut être définie dans vos fichiers YAML groupés. Consultez les applications dans les offres groupées pour obtenir la référence complète de configuration de bundle.

Prochaines étapes

  • Last updated on