1. Introduction
Un agent disposant de ses propres identifiants avec une autorisation étendue voit les données de tout le monde. Dans cet atelier de programmation, vous allez créer un agent qui appelle une API tierce avec les identifiants de l'utilisateur connecté. Il ne verra donc que ce que cette personne peut voir, et rien d'autre.
Vous allez le créer avec Google Agent Development Kit (ADK) et Gemini Enterprise.
Plus précisément, vous allez apprendre à concevoir une architecture à double identité dans laquelle :
- L'agent agit en son propre nom (identité d'agent) : à l'aide d'une identité d'agent basée sur SPIFFE, l'agent appelle Auth Manager, stocke la télémétrie et appelle les API Google Cloud.
- L'agent agit au nom de l'utilisateur (identité déléguée par l'utilisateur) : pour accéder à des ressources externes telles que GitHub, l'agent déclenche un flux de consentement OAuth à trois étapes (3LO) pour interroger les outils de manière sécurisée à l'aide des identifiants de l'utilisateur.

Pour ce faire, vous allez apprendre à :
- Créez un agent ADK qui se connecte au serveur MCP (Model Context Protocol) de GitHub.
- Remplacez le jeton d'accès personnel (PAT) GitHub statique de l'outil de l'agent par un flux OAuth à trois étapes (3LO) à l'aide de Google Cloud Auth Manager.
- Déployer l'agent de manière sécurisée sur Agent Runtime et provisionner Agent Identity.
- Configurez des rôles IAM pour permettre à l'identité de l'agent d'accéder au coffre de jetons au nom de l'utilisateur.
- Comprendre le flux 3LO de bout en bout pour le gestionnaire d'authentification dans Google Cloud.
Prérequis
À vérifier avant de commencer :
- Un projet Google Cloud pour lequel la facturation est activée.
- Google Cloud SDK (
gcloudCLI) installé et authentifié sur votre projet sur votre ordinateur local. La version 586.0.0 ou ultérieure est requise : exécutezgcloud components update. - Python 3.10 à 3.13 installé localement.
- Le
uvgestionnaire de paquets installé (pip install uv). - Un compte GitHub pour enregistrer une application OAuth et créer des jetons. Si vous n'avez pas de compte GitHub, vous pouvez utiliser n'importe quel serveur MCP tiers compatible avec l'autorisation OAuth 2.0 à trois acteurs.
2. Configuration du projet
1. S'authentifier sur Google Cloud
Authentifiez-vous auprès de Google Cloud depuis votre ligne de commande locale pour vous assurer que votre environnement dispose des autorisations nécessaires pour déployer sur Agent Runtime, provisionner l'identité de l'agent et configurer Auth Manager pendant cet atelier.
Exécutez les commandes suivantes pour vous connecter à votre compte Google Cloud, définir votre projet actif (remplacez YOUR_PROJECT_ID par l'ID de votre projet Google Cloud) et configurer les identifiants par défaut de l'application (ADC) :
gcloud auth login
gcloud config set project YOUR_PROJECT_ID
gcloud auth application-default login
2. Activer les services Google Cloud requis
Activez les API nécessaires dans votre projet Google Cloud pour suivre cet atelier. Exécutez la commande suivante dans votre terminal :
gcloud services enable \
agentidentity.googleapis.com \
agentregistry.googleapis.com \
aiplatform.googleapis.com \
apphub.googleapis.com
L'exécution de cette commande peut prendre une minute. Une fois l'opération terminée, l'invite de commande s'affiche à nouveau, confirmant que les API sont actives.
3. Installer la CLI d'agent et configurer le projet
agents-cli est l'outil de ligne de commande utilisé pour structurer, gérer, tester et déployer des agents ADK sur Gemini Enterprise. Installez-le en local :
uvx google-agents-cli setup
Vérifiez votre installation :
agents-cli --help
Le menu d'aide de la CLI devrait s'afficher avec les commandes disponibles (telles que deploy, run et status).
Générez l'échafaudage initial du projet. Vous allez commencer par un prototype local, puis l'améliorer pour le déploiement sur Agent Runtime :
agents-cli create secure-agent-demo --prototype --yes
Cela crée le répertoire secure-agent-demo contenant le code de base de votre agent, ses dépendances et ses fichiers de test.
4. Ajouter les extras ADK requis
Ajoutez les deux extras manquants dans le fichier pyproject.toml généré : mcp pour l'ensemble d'outils GitHub et agent-identity pour Auth Manager, qui sera utilisé plus tard dans l'atelier. Ouvrez secure-agent-demo/pyproject.toml et remplacez l'intégralité du
google-adk
ligne de dépendance par :
"google-adk[agent-identity,gcp,mcp,otel-gcp]>=2.5.0,<3.0.0",
Ensuite, installez :
cd secure-agent-demo
agents-cli install
3. Créer et tester l'agent
1. Créer l'agent
Dans votre projet, remplacez le code de secure-agent-demo/app/agent.py par le code suivant :
# app/agent.py
from google.adk.agents import Agent
from google.adk.apps import App
from google.adk.models import Gemini
from google.genai import types
from app.tools import github_toolset
import os
import google.auth
_, project_id = google.auth.default()
os.environ["GOOGLE_CLOUD_PROJECT"] = project_id
os.environ["GOOGLE_CLOUD_LOCATION"] = "global"
os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "True"
INSTRUCTION = """You are the DevOps Assistant. You help developers list and triage their GitHub issues and pull requests.
Your capabilities: You have a GitHub MCP toolset that you can use to perform actions that the user requests.
Rules:
- NEVER write, update, or delete. You are only allowed read access.
- Act on behalf of the signed-in user.
- If a tool returns an authentication or authorization error, guide the user to sign in.
- NEVER fabricate information. Only report real issues returned by tools.
"""
root_agent = Agent(
name="root_agent",
model=Gemini(
model="gemini-3.8-flash",
retry_options=types.HttpRetryOptions(attempts=3),
),
instruction=INSTRUCTION,
tools=[github_toolset()],
)
app = App(
root_agent=root_agent,
name="app",
)
Ce fichier définit trois composants clés de l'agent :
- Instruction système (
INSTRUCTION) : définit le persona, limite l'assistant au tri GitHub et applique des règles de sécurité strictes (comme l'accès en lecture seule et l'invitation des utilisateurs à s'authentifier en cas d'erreur). - Configuration de l'agent (
root_agent) : instancie unAgentADK à l'aide du modèlegemini-3.8-flash, configure la logique de nouvelle tentative HTTP et équipe l'agent de l'ensemble d'outils GitHub. - App Wrapper (
app) : encapsule l'agent racine dans un conteneur ADKApp, ce qui permet de le déployer dans Agent Runtime.
2. Ajouter l'outil MCP GitHub
L'agent se connecte à GitHub à l'aide du protocole MCP (Model Context Protocol). Créez un fichier dans secure-agent-demo/app/tools.py pour enregistrer les paramètres de connexion de la passerelle MCP. Copiez et collez le code suivant :
# app/tools.py
from __future__ import annotations
import os
from google.adk.tools.mcp_tool import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams
GITHUB_MCP_URL = "https://api.githubcopilot.com/mcp/"
GITHUB_TOKEN = os.environ.get("GITHUB_TOKEN", "")
def github_toolset() -> McpToolset:
"""Returns the McpToolset connecting to the public GitHub Copilot MCP gateway."""
return McpToolset(
connection_params=StreamableHTTPConnectionParams(
url=GITHUB_MCP_URL,
headers={
"Authorization": f"Bearer {GITHUB_TOKEN}",
"X-MCP-Toolsets": "all",
"X-MCP-Readonly": "true",
},
)
)
Cette fonction crée un outil qui appelle le serveur MCP de GitHub :
- Ensemble d'outils MCP (
McpToolset) : découvre et enregistre de manière dynamique les fonctionnalités GitHub en tant qu'outils d'agent appelables. - Paramètres de connexion (
StreamableHTTPConnectionParams) : pointe l'ensemble d'outils vers la passerelle MCP publique de GitHub. - En-têtes d'autorisation : injecte le
GITHUB_TOKENen tant que jeton de support et applique le mode lecture seule (X-MCP-Readonly: true) directement au niveau de la couche transport.
3. Tester localement avec un jeton d'accès personnel GitHub
Pour exécuter l'agent localement avec des identifiants statiques :
- Créez un jeton d'accès personnel précis sur la page Personal Access Tokens (Jetons d'accès personnels) de GitHub :
- Cliquez sur Generate new token (Générer un nouveau jeton), puis attribuez un nom à votre jeton.
- Sous Repository access (Accès aux dépôts), sélectionnez All repositories (Tous les dépôts) ou sélectionnez les dépôts spécifiques que vous souhaitez tester.
- Sous Permissions > Repositories (Autorisations > Dépôts), cliquez sur +Add permissions (+ Ajouter des autorisations), puis sélectionnez Contents (Contenus), Issues (Problèmes) et Pull requests (Demandes d'extraction) pour Read-only (Lecture seule) (Metadata (Métadonnées) est automatiquement défini sur "Lecture seule").
- Cliquez sur Générer un jeton et copiez la valeur du jeton généré. (Si vous utilisez un jeton d'accès personnel (classique), sélectionnez le champ d'application
repo.)
- Définissez-la dans votre environnement :
export GITHUB_TOKEN="your_github_pat_here" - Accédez au dossier
secure-agent-demo(si vous n'y êtes pas déjà) et démarrez le playground local :cd secure-agent-demo agents-cli playground - Ouvrez l'interface du playground et sélectionnez le dossier
appdans le menu déroulant. Dans la boîte de discussion, essayez une requête ciblée telle que"Get the last 2 GitHub issues reported against my name"ou"List my 3 most recently updated repositories", puis vérifiez que l'agent appelle l'ensemble d'outils MCP GitHub et renvoie vos données GitHub. Pour vérifier si l'agent utilise bien votre jeton d'accès personnel pour agir en votre nom, essayez de lui poser des questions sur vos dépôts privés ou vos contributions.
4. Configurer Auth Manager
Bien que le codage en dur d'identifiants statiques (comme un jeton d'accès personnel) soit pratique pour le prototypage, il expose les applications de production à des fuites d'identifiants, à des temps d'arrêt liés à l'actualisation manuelle des jetons et à un manque de contrôles d'accès cloud natifs.
Pour résoudre ce problème, Google Cloud propose le gestionnaire d'authentification Agent Identity. Le gestionnaire d'authentification Agent Identity est un coffre-fort d'identifiants conçu pour protéger les identifiants. Il permet aux agents de s'authentifier à l'aide d'une clé API ou d'un ID client et d'un code secret OAuth, ou au nom d'un utilisateur via la délégation OAuth à l'aide de jetons d'accès d'utilisateur final.
Dans le gestionnaire d'authentification, vous configurez des fournisseurs d'authentification qui définissent le type d'authentification et les identifiants pour des applications tierces spécifiques. Les fournisseurs d'authentification sont régionaux, et la région doit correspondre à celle où vous déployez l'agent. Le workflow Auth Manager de bout en bout fonctionne comme suit :

- Interception dynamique du consentement : lorsque l'agent tente d'exécuter un outil au nom d'un utilisateur, l'ADK vérifie si Auth Manager dispose d'un identifiant valide existant. Si aucun n'existe, le gestionnaire d'authentification renvoie une URL d'autorisation pour lancer un flux de consentement OAuth à trois étapes (3LO).
- Stockage sécurisé dans Vault : une fois que l'utilisateur final a autorisé l'application, Auth Manager intercepte automatiquement le rappel OAuth et stocke les jetons d'accès et d'actualisation de l'utilisateur dans un coffre d'identifiants sécurisé géré par Google.
- Cycle de vie automatisé des jetons : Auth Manager gère entièrement l'expiration et la rotation des jetons en arrière-plan, ce qui évite d'avoir à actualiser manuellement les jetons ou à subir des temps d'arrêt.
- Exécution d'outils sans secret : pour les actions ultérieures, l'agent (qui s'authentifie via son identité d'agent SPIFFE) demande de manière dynamique le jeton d'accès délégué de l'utilisateur au gestionnaire d'authentification au moment de l'exécution, ce qui permet de garder le code du client et de l'agent entièrement sans secret.
Étape A : Configurer GitHub en tant que fournisseur d'authentification
Exécutez la commande gcloud suivante pour créer un fournisseur d'authentification GitHub dans votre projet Google Cloud. Vous fournirez l'ID client et le code secret ultérieurement : GitHub ne les émettra pas tant qu'il ne connaîtra pas l'URL de rappel de ce fournisseur.
gcloud agent-identity auth-providers create github-oauth-provider \
--project="YOUR_PROJECT_ID" \
--location="us-central1" \
--three-legged-oauth-authorization-url="https://github.com/login/oauth/authorize" \
--three-legged-oauth-token-url="https://github.com/login/oauth/access_token"
Décrivez le fournisseur pour récupérer l'URL de redirection OAuth générée :
gcloud agent-identity auth-providers describe github-oauth-provider \
--project="YOUR_PROJECT_ID" \
--location="us-central1"
Le champ est redirectUrl, imbriqué sous authProviderTypeParams.threeLeggedOauth. Pour le lire directement :
gcloud agent-identity auth-providers describe github-oauth-provider \
--project="YOUR_PROJECT_ID" --location="us-central1" \
--format="value(authProviderTypeParams.threeLeggedOauth.redirectUrl)"
Il se présente comme suit : https://agentidentitycredentials.googleapis.com/v1/projects/YOUR_PROJECT_ID/locations/us-central1/authProviders/github-oauth-provider/oauthcallback.
Étape B : Enregistrez l'application OAuth dans GitHub
- Accédez à la page GitHub Developer Settings (Paramètres du développeur GitHub), sélectionnez OAuth Apps (Applications OAuth) dans la barre latérale de gauche, puis cliquez sur New OAuth App (Nouvelle application OAuth) ou sur Register a new application (Enregistrer une nouvelle application) si vous n'en avez pas encore créé.
- Renseignez les champs du formulaire de l'application OAuth :
- Nom de l'application : saisissez un nom pour votre application (par exemple,
secure-agent-demo). - URL de la page d'accueil : saisissez l'URL de votre application d'interface (
http://localhost:8501pour le prototypage local ; vous pouvez la remplacer par l'URL déployée en production). - Description de l'application : facultatif (vous pouvez laisser ce champ vide).
- URL de rappel d'autorisation (URI de redirection) : collez l'
redirectUrlrécupéré à l'étape A. - Activer le flux de l'appareil : ne cochez pas cette option.
- Nom de l'application : saisissez un nom pour votre application (par exemple,
- Cliquez sur Enregistrer l'application.
- Sur la page de l'application qui s'affiche, copiez l'ID client, puis cliquez sur Generate a new client secret (Générer un nouveau code secret du client) et copiez le code secret du client généré. Enregistrez les deux valeurs. Vous les utiliserez comme
YOUR_GITHUB_CLIENT_IDetYOUR_GITHUB_CLIENT_SECRETà l'étape suivante.
Étape C : Ajoutez les identifiants GitHub au fournisseur d'authentification
Remplacez YOUR_PROJECT_ID, YOUR_GITHUB_CLIENT_ID et YOUR_GITHUB_CLIENT_SECRET par vos valeurs, puis exécutez la commande suivante :
gcloud agent-identity auth-providers update github-oauth-provider \
--project="YOUR_PROJECT_ID" \
--location="us-central1" \
--three-legged-oauth-client-id="YOUR_GITHUB_CLIENT_ID" \
--three-legged-oauth-client-secret="YOUR_GITHUB_CLIENT_SECRET"
La commande renvoie le fournisseur avec clientId visible. Le secret n'est pas renvoyé.
👉 Une fois cette étape terminée, votre gestionnaire d'authentification Google Cloud est entièrement configuré avec les identifiants de votre application OAuth GitHub. Google Cloud est ainsi configuré pour agir en tant que coffre-fort sécurisé qui gère le consentement et les cycles de vie des jetons.
5. Passer du jeton PAT à Auth Manager
Maintenant que le gestionnaire d'authentification est entièrement configuré, l'étape suivante consiste à mettre à jour le code de l'outil de l'agent. Remplacez le contenu de secure-agent-demo/app/tools.py par le code suivant.
👉 Remplacez l'ID du projet et l'emplacement dans la variable OAUTH_PROVIDER_NAME ci-dessous.
# app/tools.py
from __future__ import annotations
import os
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider, GcpAuthProviderScheme
from google.adk.tools.mcp_tool import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams
# 1. Register the GCP Auth Provider in the global Credential Manager
CredentialManager.register_auth_provider(GcpAuthProvider())
# 2. Replace YOUR_PROJECT_ID with your project ID.
OAUTH_PROVIDER_NAME = "projects/YOUR_PROJECT_ID/locations/us-central1/authProviders/github-oauth-provider"
# 3. The frontend callback URL where the user is redirected after authorizing GitHub. Resolved from the environment variable.
OAUTH_CONTINUE_URI = os.environ.get(
"OAUTH_CONTINUE_URI",
"http://localhost:8501/validateUserId"
)
def github_toolset() -> McpToolset:
"""Returns the McpToolset using 3LO credentials retrieved via GCP Auth Manager."""
auth_scheme = GcpAuthProviderScheme(
name=OAUTH_PROVIDER_NAME,
# Required to read private repositories. Auth Manager currently supports a
# single scope for GitHub.
scopes=["repo"],
continue_uri=OAUTH_CONTINUE_URI,
)
return McpToolset(
connection_params=StreamableHTTPConnectionParams(
url="https://api.githubcopilot.com/mcp/",
headers={
"X-MCP-Toolsets": "all",
"X-MCP-Readonly": "true",
},
),
auth_scheme=auth_scheme,
)
Comprendre le code de l'outil
Le principal changement est auth_scheme. En l'associant à l'ensemble d'outils, chaque fois que l'agent appelle GitHub, ADK demande d'abord à Auth Manager le jeton de cet utilisateur. S'il n'y en a pas encore, il invite l'utilisateur à se connecter au lieu d'échouer. Le GITHUB_TOKEN codé en dur a complètement disparu.
6. Déployer l'agent sur Agent Runtime
Maintenant que nous avons mis à jour l'outil MCP GitHub pour utiliser Auth Manager, l'étape suivante consiste à déployer l'agent sur Agent Runtime. Le déploiement avec l'identité d'agent activée provisionne un ID SPIFFE unique pour l'agent.
Initialisez la configuration de déploiement du projet. Assurez-vous que votre terminal se trouve dans le répertoire racine du projet secure-agent-demo, puis exécutez la commande suivante :
agents-cli scaffold enhance . --deployment-target agent_runtime --prototype --yes
Cette commande inspecte la structure de votre projet pour vérifier sa compatibilité avec l'ADK, prépare les configurations d'empaquetage du conteneur sous-jacent et génère un fichier agents-cli-manifest.yaml à la racine de votre projet, prérempli avec les paramètres de déploiement par défaut.
👉 Ouvrez le fichier agents-cli-manifest.yaml que vous venez de créer, puis vérifiez ou modifiez le champ region pour qu'il soit défini sur us-central1. Cela permet de s'assurer que votre agent est déployé dans la même région que votre fournisseur d'authentification :
region: "us-central1"
Déployer l'agent avec une identité d'agent
Déployez avec adk deploy agent_engine. L'agent est ainsi provisionné avec sa propre identité d'agent, une identité cryptographique unique basée sur SPIFFE appartenant à ce déploiement, que l'agent utilise pour s'authentifier auprès d'Auth Manager et d'autres services Google Cloud.
👉 Dans le répertoire secure-agent-demo, remplacez YOUR_PROJECT_ID et exécutez ces commandes :
# Write a config file inside the `app/` folder instructing Agent Runtime to provision a SPIFFE-backed `AGENT_IDENTITY` for this deployment.
echo '{ "identity_type": "AGENT_IDENTITY" }' > app/.agent_engine_config.json
# Generate the dependency list the build will install
uv export --no-emit-workspace --no-hashes --format requirements.txt \
--output-file app/requirements.txt
uv run adk deploy agent_engine app \
--project="YOUR_PROJECT_ID" \
--region="us-central1"
La création et l'importation du conteneur prennent quelques minutes. Une fois l'opération terminée, la CLI affiche le nom de la ressource déployée. Notez la valeur reasoningEngines/ENGINE_ID, car vous en aurez besoin pour autoriser votre agent et y faire pointer le client de l'UI.
Autoriser Agent Identity
Maintenant que votre agent s'exécute dans le cloud, il doit être autorisé à accéder aux identifiants stockés dans Auth Manager. Par défaut, l'identité SPIFFE de l'agent n'a pas accès aux ressources cloud externes.
Exécutez la commande gcloud suivante pour accorder le rôle roles/agentidentity.user à l'identité de votre agent sur la ressource du fournisseur d'authentification. Votre agent dispose ainsi des autorisations exactes dont il a besoin pour demander des jetons utilisateur au coffre-fort, et rien de plus.
# Get YOUR_ORG_ID
gcloud projects get-ancestors $(gcloud config get-value project) \
--filter="type=organization" \
--format="value(id)"
# Get YOUR_PROJECT_NUMBER
gcloud projects describe $(gcloud config get-value project) \
--format="value(projectNumber)"
Ensuite, liez la stratégie IAM au fournisseur d'authentification (en remplaçant YOUR_PROJECT_ID et le compte principal --member) :
gcloud agent-identity auth-providers add-iam-policy-binding github-oauth-provider \
--project="YOUR_PROJECT_ID" \
--location="us-central1" \
--role="roles/agentidentity.user" \
--member="principal://agents.global.org-YOUR_ORG_ID.system.id.goog/resources/aiplatform/projects/YOUR_PROJECT_NUMBER/locations/us-central1/reasoningEngines/YOUR_ENGINE_ID"
👉 Vous pouvez également obtenir la valeur --member="principal://..." complète de votre agent déployé depuis la console Google Cloud : accédez à la console Agent Runtime, sélectionnez votre agent déployé, accédez à l'onglet Identité et copiez directement la chaîne principal://... complète.
Attribuez maintenant à votre propre compte le même rôle sur le fournisseur. Le client d'interface utilisateur que vous exécuterez à l'étape suivante appelle l'API de finalisation des identifiants avec vos identifiants par défaut de l'application. Sans cela, le flux de consentement échoue avec une erreur 403 sur agentidentity.authProviders.retrieveCredentials :
gcloud agent-identity auth-providers add-iam-policy-binding github-oauth-provider \
--project="YOUR_PROJECT_ID" \
--location="us-central1" \
--role="roles/agentidentity.user" \
--member="user:YOUR_EMAIL_ADDRESS"
7. Comprendre le flux de consentement 3LO
Maintenant que l'agent est déployé sur Agent Runtime avec une identité d'agent sécurisée, l'étape suivante consiste à fournir une interface d'interface personnalisée permettant aux utilisateurs de discuter avec lui. Plus important encore, Google Cloud Auth Manager nécessite un gestionnaire de rappel d'application cliente pour terminer la boucle d'authentification.
Bien que Google Cloud Auth Manager gère de manière sécurisée les identifiants utilisateur dans un coffre-fort, il ne peut pas finaliser l'échange de jetons OAuth par lui-même. Le handshake 3LO s'appuie sur l'application cliente pour combler l'écart :
- Lorsqu'un utilisateur autorise l'application GitHub, GitHub le redirige vers l'
redirectUrldu fournisseur d'authentification Agent Identity . - Le gestionnaire d'authentification redirige ensuite le pop-up du navigateur de l'utilisateur vers une URL de rappel côté client (
continue_uri). - Il incombe à l'application cliente d'intercepter cette redirection, de lire le nonce à partir des cookies du navigateur et d'appeler le point de terminaison
credentials:finalizede Google Cloud pour terminer l'établissement de liaison. - Une fois que le client a finalisé l'échange, Google Cloud enregistre le jeton de manière sécurisée dans le coffre-fort du fournisseur d'authentification, ce qui permet à l'agent d'appeler l'outil GitHub.
Sans ce client personnalisé hébergeant le point de terminaison de rappel, l'établissement de liaison reste incomplet et le coffre-fort ne peut pas stocker les identifiants.
Le flux OAuth 3LO interactif s'étend sur plusieurs couches. Voici le cycle de vie complet de l'exécution d'une requête d'outil. Nous allons détailler cela dans l'explication ci-dessous et à l'étape suivante.
👉 Cliquez sur l'image pour l'agrandir.
Responsabilités principales du client dans le handshake
- Relayer la demande de consentement (étapes 5 et 6) : l'agent émet un
adk_request_credentialcontenant l'URL de consentement et un nonce à usage unique. Le client ouvre le pop-up et stocke le nonce sous forme de cookie. - Héberger le rappel de redirection (étapes 10 et 11) :
/validateUserId, où le gestionnaire d'authentification envoie le pop-up après le consentement. - Finaliser le jeton (étapes 12 à 14) : combinez l'état de validation de la redirection avec le nonce mis en cache et appelez
credentials:finalize, qui stocke le jeton dans le coffre-fort.
Créer votre propre client
Vous n'avez pas besoin d'écrire ce client pour l'atelier. L'étape suivante exécute un client prédéfini. Lorsque vous implémenterez cette fonctionnalité dans votre propre application, vous pourrez vous appuyer sur les deux références suivantes :
- Mettre à jour votre application côté client dans la documentation du gestionnaire d'authentification, qui explique comment gérer la demande de consentement et appeler
credentials:finalize. - L'exemple de client exécutable dans le dépôt adk-python. Consultez
main.pypour obtenir une implémentation complète et fonctionnelle des trois responsabilités ci-dessus.
8. Exécuter le client d'UI localement
Comme indiqué dans le diagramme de séquence du flux de consentement 3LO, le gestionnaire d'authentification redirige la fenêtre du navigateur vers un point de terminaison de rappel côté client. L'exemple de client du dépôt adk-python héberge ce point de terminaison sur /validateUserId. Téléchargez-le et exécutez-le localement en procédant comme suit.
Télécharger les fichiers du client
Le répertoire contributing/samples/integrations/gcp_auth/client dans adk-python contient trois éléments clés :
main.py: backend FastAPI qui se connecte à votre Agent Engine déployé et héberge le point de terminaison de rappel/validateUserIdpour finaliser les jetons OAuth.static/: fichiers HTML et JavaScript pour l'UI de chat du navigateur.requirements.txt: packages Python requis pour exécuter le serveur client.
Comme adk-python est un dépôt volumineux, utilisez la fonctionnalité sparse checkout de Git pour ne télécharger que le dossier contributing/samples/integrations/gcp_auth/client :
- Tout d'abord, remontez d'un répertoire hors de
secure-agent-demopour cloner le client dans un dossier frère :cd .. - Exécutez les commandes suivantes pour cloner les métadonnées du dépôt sans télécharger tous les fichiers (
--no-checkout), limiter le chemin d'extraction àcontributing/samples/integrations/gcp_auth/clientet n'extraire que ce dossier :git clone --filter=blob:none --no-checkout https://github.com/google/adk-python.git cd adk-python git sparse-checkout init --cone git sparse-checkout set contributing/samples/integrations/gcp_auth/client git checkout
Exécuter le client
- Dans le répertoire
adk-pythonauquel vous venez d'accéder, accédez au dossierclient:cd contributing/samples/integrations/gcp_auth/client - Créez et activez un environnement virtuel Python, puis installez les dépendances du client à partir de
requirements.txt:uv venv --python 3.13 .venv source .venv/bin/activate uv pip install --python .venv/bin/python -r requirements.txt - Définissez les variables d'environnement pointant le client vers votre projet Google Cloud, votre région (
us-central1) et l'ID de l'Agent Engine déployé (YOUR_ENGINE_ID), puis démarrez le serveur FastAPI local sur le port8501:export GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID export GOOGLE_CLOUD_LOCATION=us-central1 export AGENT_ID=YOUR_ENGINE_ID .venv/bin/uvicorn main:app --port 8501 - Vérifiez que le serveur a bien démarré et qu'il écoute sur
http://localhost:8501.
9. Tester le flux OAuth
Maintenant que tous les services sont déployés, que les liaisons IAM sont configurées et que les variables d'environnement sont définies, vous êtes prêt à tester le flux d'autorisation sécurisé de bout en bout délégué par l'utilisateur.
Étape A : Lancer l'exécution de l'outil
- Ouvrez un onglet de navigateur et accédez à l'URL de votre client :
http://localhost:8501. - Dans le volet de gauche, sous Paramètres de configuration, définissez le Type d'agent sur
Remote Agent (Vertex AI)(ouRemote Agent Engine). - Saisissez l'ID de projet et l'emplacement (
us-central1) de votre projet Google Cloud, puis cliquez sur Charger les agents distants. Les agents déployés dans votre projet sont alors chargés. - Sélectionnez votre agent
appdéployé dans le menu déroulant Sélectionner un moteur, puis cliquez sur Enregistrer et appliquer les paramètres. - Dans la zone de discussion, saisissez une requête ciblée (par exemple, pour récupérer vos problèmes ou dépôts récents) :
(ou essayezGet the last 2 GitHub issues reported against my name"List my 3 most recently updated repositories"), puis appuyez sur Entrée. - Observez l'interface utilisateur de chat : comme l'agent ne dispose pas encore d'identifiants pour votre session utilisateur, il reçoit une demande d'authentification et affiche la fiche "Authentification requise" dans le fil de conversation.
Étape B : Obtenir le consentement OAuth à trois étapes
- Une fenêtre pop-up distincte s'ouvre dans le navigateur et vous redirige vers la page d'autorisation OAuth de GitHub via le gestionnaire d'authentification de Google Cloud.
- Consultez les autorisations demandées, puis cliquez sur Autoriser.
- GitHub vous redirigera vers Google Cloud, qui redirigera le pop-up vers votre
localhostURL de rappel/validateUserId. - Le service de rappel traite et finalise l'échange d'identifiants.
Étape C : Reprendre
- Une fois la fenêtre pop-up fermée, l'onglet de chat parent détecte automatiquement la fermeture.
- L'interface renvoie une charge utile de reprise à l'agent.
- L'agent récupère de manière sécurisée le jeton nouvellement échangé à partir de Google Cloud Auth Manager, appelle les outils MCP GitHub en votre nom et diffuse vos données GitHub directement dans la fenêtre de chat, des données auxquelles l'agent n'aurait pas pu accéder seul.
Étape D : Inspecter les journaux Cloud
Pour vérifier que l'échange de jetons et la finalisation ont été traités de manière sécurisée :
- Accédez à l'explorateur de journaux de la console Google Cloud.
- Recherchez les journaux de serveur confirmant l'extraction du nonce et la validation réussie :
INFO:secure-agent-client:Caching consent nonce for session_id: session-xxxxxxx INFO:secure-agent-client:Successfully finalized auth provider credentials. - Inspecter les journaux d'Agent Runtime : vous pouvez également afficher les journaux d'exécution directement dans la console Agent Platform :
- Accédez à la console Agent Runtime.
- Cliquez sur l'agent que vous avez déployé dans la liste.
- Accédez à l'onglet Playground. Les journaux de l'agent en direct s'affichent dans le volet inférieur, ce qui vous permet de voir la boucle de raisonnement de l'agent, les détails de l'exécution des outils et le cycle de vie de la récupération des jetons en temps réel.
10. Effectuer un nettoyage
Pour éviter que des frais ne continuent de vous être facturés sur Google Cloud, nettoyez les ressources déployées :
# Follow the instructions here to delete the deployed Agent Runtime resource
# https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale/runtime/manage-deployed-agents#console_3
# Delete the auth provider
gcloud agent-identity auth-providers delete github-oauth-provider \
--project=YOUR_PROJECT_ID --location=us-central1
# Note: deleted providers sit in soft-delete for 30 days, and the name is not
# reusable until roughly a day after that. Pick a fresh name if you repeat this lab.
# Optionally, you could also delete your Google Cloud Project
gcloud projects delete YOUR_PROJECT_ID
# Optionally, delete the GitHub PAT Token and the OAuth app:
# https://github.com/settings/personal-access-tokens
Nettoyer les fichiers locaux
Si vous le souhaitez, vous pouvez nettoyer complètement votre environnement local :
- Arrêtez le serveur uvicorn local en appuyant sur Ctrl+C dans le terminal où il s'exécute.
- Supprimez les répertoires de projet créés lors de cet atelier :
# cd to the correct folder
rm -rf secure-agent-demo client adk-python
11. Félicitations !
Vous avez créé et sécurisé un agent qui agit au nom de l'utilisateur connecté.
Dans cet atelier, vous avez appris à effectuer les opérations suivantes :
- Identité du système de l'agent : comment l'agent fonctionne sous sa propre identité de compte pour s'interfacer de manière sécurisée avec l'infrastructure GCP, gérer les journaux de télémétrie et appeler les API de finalisation des identifiants.
- Identité déléguée de l'utilisateur : comment l'agent demande l'autorisation d'agir au nom de l'utilisateur sur des plates-formes externes (comme GitHub) en déclenchant un flux de consentement OAuth à trois étapes (3LO).
- Intégration sécurisée des outils : découvrez comment connecter des agents ADK à des serveurs MCP (Model Context Protocol) à l'aide de Google Cloud Auth Manager pour récupérer de manière dynamique des jetons utilisateur au lieu d'utiliser des secrets codés en dur.
- Configuration de la stratégie IAM : comment configurer des liaisons d'autorisation précises pour autoriser à la fois l'identité Agent Runtime et votre propre compte sur le fournisseur d'authentification.
Documentation complémentaire
- Gestionnaire d'authentification Agent Identity pour comprendre la configuration et les champs d'application du flux d'authentification.
- Agent Runtime Overview
- Documentation ADK
- Model Context Protocol
