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

Aperçu

Cette fonctionnalité est soumise aux "Conditions des offres de pré-DG" de la section "Conditions générales du service" des Conditions spécifiques du service. Les fonctionnalités pré-DG sont disponibles "en l'état" et peuvent avoir une prise en charge limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

Pour permettre à vos agents de s'authentifier auprès d'outils externes tels que ServiceNow ou Salesforce à l'aide de leur propre autorité, configurez l'authentification sortante à l'aide de fournisseurs d'authentification OAuth à deux étapes (identifiants client) dans le gestionnaire d'authentification des identités d'agent.

En gérant les identifiants et les jetons, les fournisseurs d'authentification OAuth en deux étapes éliminent le besoin de code personnalisé pour gérer les flux d'authentification.

Avertissement : L'API IAM Connectors ne sera pas disponible pour tous. Nous vous recommandons d'utiliser l'API Agent Identity. Pour consulter la documentation sur l'API des connecteurs IAM, consultez Utiliser l'API des connecteurs IAM pour s'authentifier à l'aide d'OAuth à deux facteurs avec le gestionnaire d'authentification.

Workflow OAuth en deux étapes

Les fournisseurs d'authentification OAuth à deux étapes utilisent l'identité de l'agent et ne nécessitent pas le consentement de l'utilisateur. Google gère le stockage des identifiants client. Lorsque vous utilisez l'Agent Development Kit (ADK), il récupère et injecte automatiquement les jetons d'accès obtenus dans les en-têtes d'appel d'outil.

Avant de commencer

1. Vérifiez que vous avez choisi la bonne méthode d'authentification.

2. Activez l'API Agent Identity.

   Rôles requis pour activer les API

   Pour activer les API, vous avez besoin du rôle IAM Administrateur Service Usage (roles/serviceusage.serviceUsageAdmin), qui contient l'autorisation serviceusage.services.enable. Découvrez comment attribuer des rôles.

   Activer l'API

3. Créez et déployez un agent.

4. Obtenez l'ID client et le code secret du client de l'application tierce à laquelle vous souhaitez vous connecter.

5. 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 d'identité d'agent à deux pattes, demandez à votre administrateur de vous accorder les rôles IAM suivants sur le projet :

• Pour créer des fournisseurs d'authentification :
  • Administrateur de l'identité de l'agent (roles/agentidentity.admin)
  • Éditeur d'identité de l'agent (roles/agentidentity.editor)
• Pour utiliser les fournisseurs d'authentification :
  • Utilisateur de l'identité de l'agent (roles/agentidentity.user)
  • Accès par défaut de l'agent (roles/aiplatform.agentDefaultAccess)
  • Éditeur de contexte d'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 d'identité d'agent à deux jambes. 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 d'identité d'agent à deux jambes :

• Pour créer des fournisseurs d'authentification : agentidentity.authProviders.create
• Pour utiliser les fournisseurs d'authentification :
  • agentidentity.authProviders.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 à deux jambes

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

Pour créer un fournisseur d'authentification à deux comptes, utilisez la gcloud CLI :

1. Créez le fournisseur d'authentification :

   gcloud alpha agent-identity authProviders create AUTH_PROVIDER_NAME \
       --location="LOCATION" \
       --two-legged-oauth-client-id="CLIENT_ID" \
       --two-legged-oauth-client-secret="CLIENT_SECRET" \
       --two-legged-oauth-token-endpoint="TOKEN_ENDPOINT"

2. Vérifiez que votre fournisseur d'authentification apparaît dans la liste et que son état est ENABLED :

   gcloud alpha agent-identity authProviders list \
      --project="PROJECT_ID" \
      --location="LOCATION"

3. Accordez des autorisations d'accès pour permettre à votre agent et à votre environnement de développement local de récupérer les identifiants auprès du fournisseur d'authentification. Pour autoriser votre agent déployé et votre compte utilisateur personnel à accéder au fournisseur d'authentification, accordez le rôle Utilisateur de l'identité de l'agent (roles/agentidentity.user) sur la ressource du fournisseur d'authentification :

   1. Accordez l'accès à l'ID SPIFFE de votre agent déployé (identité de l'agent) :

      gcloud alpha agent-identity authProviders add-iam-policy-binding AUTH_PROVIDER_NAME \
          --project="PROJECT_ID" \
          --location="LOCATION" \
          --role="roles/agentidentity.user" \
          --member="principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID"

   2. Accordez l'accès à votre compte utilisateur personnel pour le développement et les tests en local (adk web) :

      gcloud alpha agent-identity authProviders add-iam-policy-binding AUTH_PROVIDER_NAME \
          --project="PROJECT_ID" \
          --location="LOCATION" \
          --role="roles/agentidentity.user" \
          --member="user:USER_EMAIL"

Remplacez les éléments suivants :

• PROJECT_ID : ID de votre projet Google Cloud .
• LOCATION : emplacement où votre fournisseur d'authentification et votre agent sont déployés (par exemple, us-west1).
• AUTH_PROVIDER_NAME : nom de votre fournisseur d'authentification (par exemple, bigquery-mcp-3lo-authprovider).
• AUTHORIZATION_URL : URL du serveur d'autorisation (par exemple, https://accounts.google.com/o/oauth2/v2/auth).
• TOKEN_URL : URL du serveur de jetons (par exemple, https://oauth2.googleapis.com/token).
• CLIENT_ID : ID client OAuth que vous avez généré à partir du service tiers.
• CLIENT_SECRET : code secret du client OAuth que vous avez généré à partir du service tiers.
• ORGANIZATION_ID : ID de votre organisation Google Cloud .
• PROJECT_NUMBER : numéro de votre projet Google Cloud .
• ENGINE_ID : ID de votre agent de moteur de raisonnement déployé.
• USER_EMAIL : adresse e-mail de votre compte utilisateur personnel.

S'authentifier dans le code de votre agent

Pour authentifier votre agent, vous pouvez utiliser l'ADK.

ADK

Référencez le fournisseur d'authentification dans le code de votre agent en utilisant l'ensemble d'outils MCP dans l'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())

# Create the Google Cloud Auth Provider scheme
# Note: If using the legacy V1 API, the resource name uses 'connectors'
# instead of 'authProviders': projects/.../connectors/...
auth_scheme = GcpAuthProviderScheme(
    name="projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME"
)

# 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="AGENT_NAME",
    model="gemini-2.5-flash",
    instruction="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 l'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())

# Create Auth Config
# Note: If using the legacy V1 API, the resource name uses 'connectors'
# instead of 'authProviders': projects/.../connectors/...
spotify_auth_config = AuthConfig(
    auth_scheme=GcpAuthProviderScheme(
        name=(
            "projects/PROJECT_ID/locations/"
            "LOCATION/authProviders/"
            "AUTH_PROVIDER_NAME"
        )
    )
)

# 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="AGENT_NAME",
    model="MODEL_NAME",
    instruction="AGENT_INSTRUCTIONS",
    tools=[spotify_search_track_tool],
)

app = App(
    name="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 du registre d'agents dans l'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())

# Create Google Cloud auth provider scheme
# Note: If using the legacy V1 API, the resource name uses 'connectors'
# instead of 'authProviders': projects/.../connectors/...
auth_scheme = GcpAuthProviderScheme(
    name=(
        "projects/PROJECT_ID/locations/"
        "LOCATION/authProviders/"
        "AUTH_PROVIDER_NAME"
    )
)

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

toolset = registry.get_mcp_toolset(
    mcp_server_name=(
        "projects/PROJECT_ID/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="AGENT_NAME",
    model="MODEL_NAME",
    instruction="AGENT_INSTRUCTIONS",
    tools=[toolset],
)

  

Installer des dépendances pour les tests en local

Pour tester votre agent localement dans un environnement virtuel, installez les dépendances nécessaires suivantes :

1. Créez et activez un environnement virtuel :

   python3 -m venv env
   source env/bin/activate

2. Installez les packages requis :

   pip install google-cloud-aiplatform[agent_engines,adk] google-adk[agent-identity]

Déployer l'agent

Lorsque vous déployez votre agent sur Google Cloud, assurez-vous que l'identité de l'agent est activée.

Si vous déployez sur Agent Runtime sur Gemini Enterprise Agent Platform , 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]"],
    },
)

Étapes suivantes

• Présentation de l'identité de l'agent
• S'authentifier à l'aide du protocole OAuth en trois étapes avec le gestionnaire d'authentification
• S'authentifier à l'aide d'une clé API avec le gestionnaire d'authentification
• Gérer les fournisseurs d'authentification des identités d'agent
• Résoudre les problèmes liés au gestionnaire d'authentification des identités d'agent