Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

S'authentifier à l'aide d'OAuth en trois étapes avec le gestionnaire d'authentification

Si vous souhaitez que votre agent accède à des outils et services externes (par exemple, des tâches Jira ou des dépôts GitHub) au nom d'un utilisateur spécifique, vous devez configurer un fournisseur d'authentification OAuth en trois étapes dans le gestionnaire d'authentification Agent Identity.

Les fournisseurs d'authentification OAuth en trois étapes gèrent la redirection des utilisateurs et les jetons pour vous. Vous n'avez donc pas besoin d'écrire de code personnalisé pour gérer les flux OAuth 2.0 complexes.

Workflow OAuth en trois étapes

Les fournisseurs d'authentification OAuth en trois étapes nécessitent le consentement utilisateur, car l'agent accède aux ressources en son nom.

Invite et redirection : l'interface de chat invite l'utilisateur à se connecter puis le redirige vers la page de consentement de l'application tierce.
Consentement et stockage : une fois que l'utilisateur a accordé l'autorisation, les jetons OAuth obtenus sont stockés dans un coffre-fort d'identifiants géré par Google.
Injection : lorsque vous utilisez Agent Development Kit (ADK), l'agent récupère automatiquement le jeton auprès du fournisseur d'authentification et l'injecte dans les en-têtes d'appel d'outil.

Avant de commencer

[Vérifiez que vous avez choisi la méthode d'authentification appropriée](/iam/docs/agent-identity-overview#auth-models).
Activez l'API Agent Identity Connector.
Rôles requis pour activer les API
Pour activer les API, vous avez besoin du rôle IAM Administrateur d'utilisation du service (roles/serviceusage.serviceUsageAdmin), qui contient l'autorisation serviceusage.services.enable. Découvrez comment attribuer des rôles.
Activer l'API
Créez et déployez un agent.
Assurez-vous de disposer d'une application frontend pour gérer les invites de connexion des utilisateurs et la redirection vers les pages de consentement tierces.
Vérifiez que vous disposez des rôles requis pour effectuer cette tâche.

Rôles requis

Pour obtenir les autorisations nécessaires pour créer et utiliser un fournisseur d'authentification en trois étapes, demandez à votre administrateur de vous accorder les rôles IAM suivants sur le projet :

Pour créer des fournisseurs d'authentification :
- Administrateur IAM Connector (roles/iamconnectors.admin)
- Éditeur IAM Connector (roles/iamconnectors.editor)
Pour utiliser des fournisseurs d'authentification :
- Utilisateur IAM Connector (roles/iamconnectors.user)
- Accès par défaut de l'agent (roles/aiplatform.agentDefaultAccess)
- Éditeur de contexte de l'agent (roles/aiplatform.agentContextEditor)
- Utilisateur Vertex AI (roles/aiplatform.user)
- Consommateur Service Usage (roles/serviceusage.serviceUsageConsumer)

Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Ces rôles prédéfinis contiennent les autorisations requises pour créer et utiliser un fournisseur d'authentification en trois étapes. Pour connaître les autorisations exactes requises, développez la section Autorisations requises :

Autorisations requises

Les autorisations suivantes sont requises pour créer et utiliser un fournisseur d'authentification en trois étapes :

Pour créer des fournisseurs d'authentification : iamconnectors.connectors.create
Pour utiliser des fournisseurs d'authentification :
- iamconnectors.connectors.retrieveCredentials
- aiplatform.endpoints.predict
- aiplatform.sessions.create

Vous pouvez également obtenir ces autorisations avec des rôles personnalisés ou d'autres rôles prédéfinis.

Créer un fournisseur d'authentification en trois étapes

Créez un fournisseur d'authentification pour définir la configuration et les identifiants des applications tierces.

Pour créer un fournisseur d'authentification en trois étapes, utilisez la Google Cloud console ou Google Cloud CLI.

Console

Dans la Google Cloud console, accédez à la page Agent Registry.
Accéder à Agent Registry
Cliquez sur le nom de l'agent pour lequel vous souhaitez créer un fournisseur d'authentification.
Cliquez sur Identity (Identité).
Dans la section Auth Providers (Fournisseurs d'authentification), cliquez sur Add auth provider (Ajouter un fournisseur d'authentification).
Dans le volet Add auth provider (Ajouter un fournisseur d'authentification), saisissez un nom et une description.

Le nom ne peut contenir que des lettres minuscules, des chiffres ou des traits d'union. Il ne peut pas se terminer par un trait d'union et doit commencer par une lettre minuscule.
Dans la liste OAuth Type (Type OAuth), sélectionnez OAuth (3 legged) (OAuth en trois étapes).
Cliquez sur Create and continue (Créer et continuer).
Pour accorder à l'identité de votre agent l'autorisation d'utiliser le fournisseur d'authentification, cliquez sur Grant access (Accorder l'accès).
Le rôle Utilisateur du connecteur (roles/iamconnectors.user) est automatiquement attribué à l'identité de l'agent sur la ressource du fournisseur d'authentification.
Copiez l'URL de rappel.
Dans un autre onglet, enregistrez l'URL de rappel dans votre application tierce.
À partir de votre application tierce, obtenez l'ID client, le code secret du client, l'URL du jeton et l'URL d'autorisation.
Dans la section Auth provider credentials (Identifiants du fournisseur d'authentification), saisissez les informations suivantes :
- ID client
- Code secret du client
- URL du jeton
- URL d'autorisation
Cliquez sur Add provider config (Ajouter une configuration de fournisseur).

Le fournisseur d'authentification que vous venez de créer apparaît dans la liste Auth Providers (Fournisseurs d'authentification).

Google Cloud CLI

Créez le fournisseur d'authentification avec les URL d'autorisation et de jeton :

gcloud alpha agent-identity connectors create AUTH_PROVIDER_NAME \
    --location="LOCATION" \
    --three-legged-oauth-authorization-url="AUTHORIZATION_URL" \
    --three-legged-oauth-token-url="TOKEN_URL"

Récupérez l'URI de redirection à partir des détails du fournisseur d'authentification :
```
gcloud alpha agent-identity connectors describe AUTH_PROVIDER_NAME \
    --location="LOCATION"
```
La commande renvoie l'URI de redirection dans le champ redirectUrl.
Enregistrez l'URI de redirection auprès de votre application tierce pour obtenir l'ID client et le code secret du client.

Mettez à jour le fournisseur d'authentification avec l'ID client et le code secret du client :

gcloud alpha agent-identity connectors update AUTH_PROVIDER_NAME \
    --location="LOCATION" \
    --three-legged-oauth-client-id="CLIENT_ID" \
    --three-legged-oauth-client-secret="CLIENT_SECRET"

Pour accorder à l'identité de votre agent l'autorisation d'utiliser des fournisseurs d'authentification, mettez à jour la stratégie d'autorisation IAM pour le projet ou le fournisseur d'authentification spécifique, et attribuez le rôle Utilisateur du connecteur (roles/iamconnectors.user) au compte principal de l'agent.

Agent Identity est basé sur le format d'ID SPIFFE standard du secteur. Dans les stratégies d'autorisation IAM, les identités d'agent sont référencées à l'aide d'identifiants de compte principal.
Au niveau du projet (gcloud)

L'attribution du rôle au niveau du projet permet à l'agent d'utiliser n'importe quel fournisseur d'authentification de ce projet.
- Pour accorder à un seul agent l'accès aux fournisseurs d'authentification d'un projet, exécutez la commande suivante :
  gcloud projects add-iam-policy-binding PROJECT_ID \ --role='roles/iamconnectors.user' \ --member="principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID"
- Pour accorder à tous les agents d'un projet l'accès aux fournisseurs d'authentification, exécutez la commande suivante :
  gcloud projects add-iam-policy-binding PROJECT_ID \ --role='roles/iamconnectors.user' \ --member="principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER"
Au niveau du connecteur (curl)

Pour accorder à un seul agent l'accès à un fournisseur d'authentification spécifique, utilisez l'API setIamPolicy. Cette commande écrase toute stratégie d'autorisation existante sur la ressource.
```
curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{
  "policy": {
    "bindings": [
      {
        "role": "roles/iamconnectors.user",
        "members": ["principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID"]
      }
    ]
  }
}' \
    "https://iamconnectors.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/connectors/AUTH_PROVIDER_NAME:setIamPolicy"
```
Remplacez les éléments suivants :
- PROJECT_ID: ID de votre Google Cloud projet.
- AUTH_PROVIDER_NAME : nom du fournisseur d'authentification.
- ORGANIZATION_ID: ID de votre Google Cloud organisation.
- PROJECT_NUMBER : numéro de votre Google Cloud projet.
- LOCATION : emplacement de votre agent (par exemple, us-central1).
- ENGINE_ID : ID de votre moteur de raisonnement.

S'authentifier dans le code de votre agent

Pour authentifier votre agent, vous pouvez utiliser ADK ou appeler directement l'API Agent Identity.

ADK

Référencez le fournisseur d'authentification dans le code de votre agent à l'aide de l'ensemble d'outils MCP dans ADK.

from google.adk.agents.llm_agent import LlmAgent
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider, GcpAuthProviderScheme
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams
from google.adk.tools.mcp_tool.mcp_toolset import McpToolset
from google.adk.auth.auth_tool import AuthConfig

# Register the Google Cloud Auth Provider so the CredentialManager can use it.
CredentialManager.register_auth_provider(GcpAuthProvider())

# The URI to redirect the user to after consent is granted and the
# callback is received by the auth provider.
CONTINUE_URI = "https://YOUR_FRONTEND_URL/validateUserId"

# Create the Auth Provider scheme using the auth provider's full resource name.
auth_scheme = GcpAuthProviderScheme(
    name="projects/PROJECT_ID/locations/LOCATION/connectors/AUTH_PROVIDER_NAME",
    continue_uri=CONTINUE_URI
)

# Configure an MCP tool with the authentication scheme.
toolset = McpToolset(
    connection_params=StreamableHTTPConnectionParams(url="https://YOUR_MCP_SERVER_URL"),
    auth_scheme=auth_scheme,
)

# Initialize the agent with the authenticated tools.
agent = LlmAgent(
    name="YOUR_AGENT_NAME",
    model="gemini-2.0-flash",
    instruction="YOUR_AGENT_INSTRUCTIONS",
    tools=[toolset],
)

ADK

Référencez le fournisseur d'authentification dans le code de votre agent à l'aide d'un outil de fonction authentifié dans ADK.

import httpx
from google.adk.agents.llm_agent import LlmAgent
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider
from google.adk.integrations.agent_identity import GcpAuthProviderScheme
from google.adk.apps import App
from google.adk.auth.auth_credential import AuthCredential
from google.adk.auth.auth_tool import AuthConfig
from google.adk.tools.authenticated_function_tool import AuthenticatedFunctionTool
from vertexai import agent_engines

# First, register Google Cloud auth provider
CredentialManager.register_auth_provider(GcpAuthProvider())

# The URI to redirect the user to after consent is completed.
CONTINUE_URI = "WEB_APP_VALIDATE_USER_URI"

# Create Auth Config
spotify_auth_config = AuthConfig(
    auth_scheme=GcpAuthProviderScheme(
        name="projects/PROJECT_ID/locations/LOCATION/connectors/AUTH_PROVIDER_NAME",
        continue_uri=CONTINUE_URI
    )
)

# Use the Auth Config in Authenticated Function Tool
spotify_search_track_tool = AuthenticatedFunctionTool(
    func=spotify_search_track, auth_config=spotify_auth_config
)

# Sample function tool
async def spotify_search_track(credential: AuthCredential, query: str) -> str | list:
    token = None
    if credential.http and credential.http.credentials:
        token = credential.http.credentials.token

    if not token:
        return "Error: No authentication token available."

    async with httpx.AsyncClient() as client:
        response = await client.get(
            "https://api.spotify.com/v1/search",
            headers={"Authorization": f"Bearer {token}"},
            params={"q": query, "type": "track", "limit": 1},
        )
        # Add your own logic here

agent = LlmAgent(
    name="YOUR_AGENT_NAME",
    model="YOUR_MODEL_NAME",
    instruction="YOUR_AGENT_INSTRUCTIONS",
    tools=[spotify_search_track_tool],
)

app = App(
    name="YOUR_APP_NAME",
    root_agent=agent,
)

vertex_app = agent_engines.AdkApp(app_name=app)

ADK

Référencez le fournisseur d'authentification dans le code de votre agent à l'aide de l'ensemble d'outils MCP Agent Registry dans ADK.

from google.adk.agents.llm_agent import LlmAgent
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider
from google.adk.integrations.agent_identity import GcpAuthProviderScheme
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams
from google.adk.tools.mcp_tool.mcp_toolset import McpToolset
from google.adk.auth.auth_tool import AuthConfig
from google.adk.integrations.agent_registry import AgentRegistry

# First, register Google Cloud auth provider
CredentialManager.register_auth_provider(GcpAuthProvider())

# The URI to redirect the user to after consent is completed.
CONTINUE_URI="WEB_APP_VALIDATE_USER_URI"

# Create Google Cloud auth provider by providing auth provider full resource name
auth_scheme=GcpAuthProviderScheme(
name="projects/GOOGLE_PROJECT/locations/LOCATION/connectors/AUTH_PROVIDER_NAME",
continue_uri=CONTINUE_URI)

# Set Agent Registry
registry = AgentRegistry(project_id="GOOGLE_PROJECT", location="global")

toolset = registry.get_mcp_toolset(mcp_server_name="projects/GOOGLE_PROJECT/locations/global/mcpServers/agentregistry-00000000-0000-0000-0000-000000000000", auth_scheme=auth_scheme )

# Example MCP tool
toolset = McpToolset(
    connection_params=StreamableHTTPConnectionParams(url="MCP_URL"),
    auth_scheme=auth_scheme,
)

agent = LlmAgent(
    name="YOUR_AGENT_NAME",
    model="YOUR_MODEL_NAME",
    instruction="YOUR_AGENT_INSTRUCTIONS",
    tools=[toolset],
)

Appeler directement l'API

Si vous n'utilisez pas ADK, votre agent doit appeler l'API iamconnectorcredentials.retrieveCredentials pour obtenir le jeton.

Comme il s'agit d'un flux OAuth en plusieurs étapes, l'API renvoie une opération de longue durée (LRO). Votre agent doit gérer le cycle de vie de l'opération :

Requête initiale : l'agent appelle retrieveCredentials.
Consentement requis : si l'utilisateur n'a pas donné son consentement, l'API renvoie une LRO dont les métadonnées contiennent le auth_uri et un consent_nonce.
Redirection frontend : votre application doit rediriger l'utilisateur vers le auth_uri.
Finalisation : une fois que l'utilisateur a donné son consentement, appelez FinalizeCredential à l'aide du consent_nonce pour terminer le flux et obtenir le jeton.

Mettre à jour votre application côté client

Pour gérer la connexion et la redirection des utilisateurs pour OAuth en trois étapes, votre application côté client doit implémenter les étapes suivantes afin de gérer le consentement de l'utilisateur et de reprendre la conversation :

Gérer le déclencheur d'autorisation
Implémenter un point de terminaison de validation de l'utilisateur
Reprendre la conversation avec l'agent

Pour obtenir un exemple d'implémentation complet, consultez l'exemple frontend ValidateUserId.

Gérer le déclencheur d'autorisation

Lorsqu'un agent a besoin du consentement utilisateur, il renvoie un appel de fonction adk_request_credential. Votre application doit intercepter cet appel pour lancer une boîte de dialogue d'autorisation de l'utilisateur ou une redirection.

Gérez le contexte de la session en enregistrant le consent_nonce fourni par le fournisseur d'authentification. Ce nonce est requis pour valider l'utilisateur lors de l'étape de validation. Enregistrez auth_config et auth_request_function_call_id dans la session pour faciliter la reprise du flux une fois le consentement accordé.

if (auth_request_function_call := get_auth_request_function_call(event_data)):
    print("--> Authentication required by agent.")
    try:
        auth_config = get_auth_config(auth_request_function_call)
        auth_uri, consent_nonce = handle_adk_request_credential(
            auth_config, auth_provider_name, request.user_id
        )
        if auth_uri:
            event_data['popup_auth_uri'] = auth_uri
            fc_id = auth_request_function_call.get('id') if isinstance(auth_request_function_call, dict) else getattr(auth_request_function_call, 'id', None)
            event_data['auth_request_function_call_id'] = fc_id
            event_data['auth_config'] = auth_config.model_dump()

            # Store session state
            if session_id:
                consent_sessions[session_id] = {
                    "user_id": request.user_id,
                    "consent_nonce": consent_nonce
                }
    except Exception as e:
        print(f"Error handling adk_request_credential: {e}")
        # Optionally, add logic to inform the user about the error.

def handle_adk_request_credential(auth_config, auth_provider_name, user_id):
    if auth_config.exchanged_auth_credential and auth_config.exchanged_auth_credential.oauth2:
        oauth2 = auth_config.exchanged_auth_credential.oauth2
        return oauth2.auth_uri, oauth2.nonce
    return None, None

Implémenter un point de terminaison de validation de l'utilisateur

Implémentez un point de terminaison de validation sur votre serveur Web (le même URI que celui fourni en tant que continue_uri lors de la configuration). Ce point de terminaison doit effectuer les opérations suivantes :

Recevoir user_id_validation_state et auth_provider_name en tant que paramètres de requête.
Récupérer le user_id et le consent_nonce à partir du contexte de la session.
Appeler l'API FinalizeCredentials du fournisseur d'authentification avec ces paramètres.
Fermer la fenêtre d'autorisation lors de la réception d'une réponse positive.

@app.api_route("/validateUserId", methods=["GET"])
async def validate_user(request: Request):
  auth_provider_name = request.query_params.get("auth_provider_name")
  session_id = request.cookies.get("session_id")
  session = consent_sessions.get(session_id, {})

  payload = {
      "userId": session.get("user_id"),
      "userIdValidationState": request.query_params.get(
          "user_id_validation_state"
      ),
      "consentNonce": session.get("consent_nonce"),
  }

  finalize_url = f"https://iamconnectorcredentials.googleapis.com/v1alpha/{auth_provider_name}/credentials:finalize"

  try:
    async with httpx.AsyncClient(timeout=30.0) as client:
      resp = await client.post(finalize_url, json=payload)
      resp.raise_for_status()
  except httpx.HTTPError as e:
    err_text = e.response.text if hasattr(e, "response") else str(e)
    status = e.response.status_code if hasattr(e, "response") else 500
    return HTMLResponse(err_text, status_code=status)

  return HTMLResponse("""
      <script>
          window.close();
      </script>
      <p>Success. You can close this window.</p>
  """)

Reprendre la conversation avec l'agent

Une fois que l'utilisateur a donné son consentement et que la fenêtre d'autorisation s'est fermée, récupérez auth_config et auth_request_function_call_id à partir des données de votre session. Pour poursuivre la conversation, incluez ces informations dans une nouvelle requête adressée à l'agent en tant que function_response.

if request.is_auth_resume and session.auth_request_function_call_id and session.auth_config:
    auth_content = types.Content(
        role='user',
        parts=[
            types.Part(
                function_response=types.FunctionResponse(
                    id=session.auth_request_function_call_id,
                    name='adk_request_credential',
                    response=session.auth_config
                )
            )
        ],
    )
    # Send message to agent
    async for event in agent.async_stream_query(
        user_id=request.user_id,
        message=auth_content,
        session_id=session_id,
    ):
        # ...

Déployer l'agent

Lorsque vous déployez votre agent sur Google Cloud, assurez-vous qu'Agent Identity est activé.

Si vous effectuez un déploiement sur Agent Runtime, utilisez l'indicateur identity_type=AGENT_IDENTITY :

import vertexai
from vertexai import types
from vertexai.agent_engines import AdkApp

# Initialize the Vertex AI client with v1beta1 API for Agent Identity support
client = vertexai.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options=dict(api_version="v1beta1")
)

# Use the proper wrapper class for your Agent Framework (e.g., AdkApp)
app = AdkApp(agent=agent)

# Deploy the agent with Agent Identity enabled
remote_app = client.agent_engines.create(
    agent=app,
    config={
        "identity_type": types.IdentityType.AGENT_IDENTITY,
        "requirements": ["google-cloud-aiplatform[agent_engines,adk]", "google-adk[agent-identity]"],
    },
)