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 |
|---|---|---|
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. | |
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.ymlet déployez avecdatabricks 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 undatabricks.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.
- Workspace UI
- Declarative Automation Bundles
- Cliquez sur Modifier sur la page d'accueil de votre application.
- Accédez à l'étape Configurer .
- Dans la section **Ressources d'application**, ajoutez la ressource d'Experimentation MLflow avec
Can Editl'autorisation.
Consultez Ajouter une ressource d'Experimentation MLflow à une application Databricks.
-
Déclarez l'Expérimentation sous la liste
resourcesde votre application dansdatabricks.yml. Lanameque vous affectez à la ressource est référencée ultérieurement lorsque vous câblez les variables d'environnement.YAMLresources:
apps:
my_agent:
name: 'my-agent'
source_code_path: ./
resources:
- name: 'experiment'
experiment:
experiment_id: '<experiment-id>'
permission: 'CAN_EDIT' -
Redéployez le bundle :
Bashdatabricks bundle deploy
databricks bundle run my_agent
Voir app.Ressources.Experimentation pour tous les champs.
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.
- Workspace UI
- Declarative Automation Bundles
Ajoutez des ressources à l'application via la section **Ressources d'application** lorsque vous créez ou modifiez l'application dans le workspace Databricks.
- Cliquez sur Modifier sur la page d'accueil de votre application.
- Accédez à l'étape Configurer .
- 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.
-
Déclarez chaque ressource utilisée par l'agent dans la liste
resourcessous votre application dansdatabricks.yml. L'exemple ci-dessous montre un agent qui utilise une expérimentation MLflow, un endpoint de service, un Genie Agent, un SQL warehouse, un index de recherche IA, une fonction Unity Catalog et une instance Lakebase. Chaque ressourcenameest référencée à partir deconfig.envviavalue_fromafin que l'agent reçoive l'identifiant résolu au moment de l'exécution.YAMLbundle:
name: my_agent
resources:
apps:
my_agent:
name: 'my-agent'
description: 'Custom agent deployed on Databricks Apps'
source_code_path: ./
config:
command: ['uv', 'run', 'start-app']
env:
- name: MLFLOW_EXPERIMENT_ID
value_from: 'experiment'
- name: LAKEBASE_INSTANCE_NAME
value_from: 'database'
resources:
- name: 'experiment'
experiment:
experiment_id: '<experiment-id>'
permission: 'CAN_EDIT'
- name: 'llm'
serving_endpoint:
name: 'databricks-claude-sonnet-4-5'
permission: 'CAN_QUERY'
- name: 'sales-genie'
genie_space:
space_id: '<genie-space-id>'
permission: 'CAN_RUN'
- name: 'warehouse'
sql_warehouse:
id: '<warehouse-id>'
permission: 'CAN_USE'
- name: 'docs-index'
uc_securable:
securable_full_name: 'main.docs.chunks_index'
securable_type: 'TABLE'
permission: 'SELECT'
- name: 'lookup-function'
uc_securable:
securable_full_name: 'main.tools.order_lookup'
securable_type: 'FUNCTION'
permission: 'EXECUTE'
- name: 'database'
database:
instance_name: '<lakebase-instance-name>'
database_name: 'databricks_postgres'
permission: 'CAN_CONNECT_AND_CREATE'
targets:
dev:
mode: development
default: true
Chaque valeur value_from de config.env doit correspondre à un champ name de la liste resources. Les incohérences entraînent la résolution de la variable d'environnement en None dans l'application déployée.
-
Déployer et start le bundle :
Bashdatabricks bundle validate
databricks bundle deploy
databricks bundle run my_agentbundle deployupload la source et configure les ressources.bundle rundémarre ou redémarre l'application avec la dernière source. L'argument debundle runest la clé YAML sousresources.apps(icimy_agent), pas le champnamede l'application déployée.
Pour le schéma complet de chaque sous-type de ressources, consultez app.resources.
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 |
|
|
Endpoint de Model Serving |
|
|
Fonction Unity Catalog |
|
|
Genie Agent |
|
|
Index de recherche IA |
|
|
Table Unity Catalog. |
|
|
Connexion Unity Catalog |
|
|
Volume Unity Catalog |
|
|
Lakebase (provisionné) |
|
|
Lakebase (autoscaling) |
|
|
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
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 :
- 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.
- Les identifiants utilisateur sont restreints : Databricks prend les identifiants de l'utilisateur et les limite uniquement aux API scopes que vous avez définis.
- 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. - 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.
- Workspace UI
- Declarative Automation Bundles
- Dans l'interface utilisateur de Databricks, accédez aux paramètres d' autorisation de votre application.
- 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.
- Enregistrer les modifications et redémarrer l'application.
-
Déclarez les étendues sous
user_api_scopessur la ressource de l'application dansdatabricks.yml:YAMLresources:
apps:
my_agent:
name: 'my-agent'
source_code_path: ./
user_api_scopes:
- sql
- genie
- model-serving
resources:
- name: 'experiment'
experiment:
experiment_id: '<experiment-id>'
permission: 'CAN_EDIT' -
Redéployez le bundle et redémarrez l'application :
Bashdatabricks bundle deploy
databricks bundle run my_agent
Après avoir activé l'autorisation utilisateur sur un workspace pour la première fois, vous devez redémarrer les applications existantes avant qu'elles ne puissent utiliser les périmètres. Consultez Ajouter des périmètres à une 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.
-
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 :
Pythonfrom databricks_app.utils import get_user_workspace_clientSinon, importez depuis les utilitaires du serveur d'agents :
Pythonfrom agent_server.utils import get_user_workspace_clientLa fonction
get_user_workspace_client()utilise le serveur d'agent pour capturer l'en-têtex-forwarded-access-tokenet construit un client de workspace avec ces identifiants d'utilisateur, gérant l'authentification entre l'utilisateur, l'application et le serveur d'agent. -
Initialisez le client Workspace au moment de la query, et non au Startup :
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.
# 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.
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.
- Workspace UI
- Python
Le test d'IU du Workspace est la vérification la plus rapide et ne nécessite pas de jetons OAuth.
- 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.
- Confirmez que vous disposez de l'autorisation
CAN USEsur l'application. Voir Configurer les autorisations d'une application Databricks. - 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.
- 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.
- Ouvrez DevTools : appuyez sur **F12**, ou **Cmd+Option+I** sur macOS, ou **Ctrl+Shift+I** sur Windows ou Linux.
- Ouvrez l'onglet Application tab .
- Sous Stockage > Cookies , sélectionnez l'URL de votre application.
- Faites un clic droit sur chaque cookie et choisissez Supprimer .

Utilisez un profil CLI ou les identifiants de Service Principal Databricks pour invoquer l'agent. Consultez Interroger un agent déployé sur Databricks pour les options de requête et Se connecter à une application Databricks API à l'aide de l'authentification par jeton pour savoir comment générer des jetons OAuth.
-
Les modifications de portée prennent effet immédiatement, mais les caches internes peuvent prendre jusqu'à 5 minutes pour se refresh. Attendez donc avant de tester (aucun redémarrage de l'application n'est requis).
-
Appelez l'agent en tant que vous-même :
Pythonfrom databricks.sdk import WorkspaceClient
from databricks_openai import DatabricksOpenAI
app_name = "<your-app-name>"
prompt = [{"role": "user", "content": "Call the whoami tool and return only the raw result."}]
w = WorkspaceClient(profile="<your-profile>")
client = DatabricksOpenAI(workspace_client=w)
response = client.responses.create(model=f"apps/{app_name}", input=prompt)
print(response.output_text)La sortie doit être votre nom d’utilisateur — par exemple,
you@your-company.com.
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 :
- L'autorisation utilisateur est activée sur le workspace.
- L'application a des périmètres configurés.
get_user_workspace_client()est appelé à l'intérieur du gestionnaire@invokeou@stream, et non au Startup.- Le code utilise
get_user_workspace_client()et nonWorkspaceClient().
Quelques points à surveiller :
- Retirez l’outil
whoamiavant 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 instructionSELECT current_user()sur un warehouse exerce l'étenduesqlde 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_supporthttps://<your-workspace>/api/2.0/mcp/ai-search/prod/billinghttps://<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.
- Workspace UI
- Declarative Automation Bundles
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.
-
Ajoutez une entrée
uc_securablepar index et par fonction sous la listeresourcesde votre application :YAMLresources:
apps:
my_agent:
resources:
- name: 'support-index'
uc_securable:
securable_full_name: 'prod.customer_support.tickets_index'
securable_type: 'TABLE'
permission: 'SELECT'
- name: 'billing-index'
uc_securable:
securable_full_name: 'prod.billing.invoices_index'
securable_type: 'TABLE'
permission: 'SELECT'
- name: 'refund-function'
uc_securable:
securable_full_name: 'prod.billing.process_refund'
securable_type: 'FUNCTION'
permission: 'EXECUTE' -
Redéployez le bundle :
Bashdatabricks bundle deploy
databricks bundle run my_agent
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.