S'authentifier à l'aide d'une clé API 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 les API Google Maps ou Weather, configurez l'authentification sortante à l'aide de fournisseurs d'authentification par clé API dans le gestionnaire d'authentification de l'identité de l'agent.

Les fournisseurs d'authentification par clé API gèrent vos clés cryptographiques pour vous. Cette fonctionnalité vous évite de coder en dur les clés dans le code de votre agent ou de les gérer manuellement.

Workflow de clé API

Les fournisseurs d'authentification par clé API utilisent l'identité de l'agent et ne nécessitent pas le consentement utilisateur. Google prend des mesures pour sécuriser la clé API lors du stockage. Lorsque vous utilisez l'Agent Development Kit (ADK), il récupère et injecte automatiquement la clé API 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 Connector.

   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 la clé API du service tiers auquel 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 par clé API, demandez à votre administrateur de vous accorder les rôles IAM suivants sur le projet :

• Pour créer des fournisseurs d'authentification :
  • Administrateur de connecteur IAM (roles/iamconnectors.admin)
  • Éditeur de connecteurs IAM (roles/iamconnectors.editor)
• Pour utiliser des fournisseurs d'authentification :
  • Utilisateur de connecteurs IAM (roles/iamconnectors.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 par clé API. Pour connaître les autorisations exactes requises, développez la section Autorisations requises :

Autorisations requises

Vous devez disposer des autorisations suivantes pour créer et utiliser un fournisseur d'authentification par clé API :

• 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 par clé API

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

Pour créer un fournisseur d'authentification par clé API, utilisez la console Google Cloud ou Google Cloud CLI.

Console

1. Dans la console Google Cloud , accédez à la page Registre d'agents.

   Accéder au registre d'agents

2. Cliquez sur le nom de l'agent pour lequel vous souhaitez créer un fournisseur d'authentification.
3. Cliquez sur Identité.
4. Dans la section Fournisseurs d'authentification, cliquez sur Ajouter un fournisseur d'authentification.

5. Dans le volet 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.

6. Dans la liste Type OAuth, sélectionnez Clé API.
7. Cliquez sur Créer et continuer.
8. Pour autoriser l'identité de votre agent à utiliser le fournisseur d'authentification, cliquez sur Accorder l'accès.

   Cela attribue automatiquement le rôle Utilisateur du connecteur (roles/iamconnectors.user) à l'identité de l'agent sur la ressource du fournisseur d'authentification.

9. Dans la section Identifiants du fournisseur d'authentification, saisissez la clé API.
10. Cliquez sur Ajouter une configuration de fournisseur.

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

Google Cloud CLI

1. Créez le fournisseur d'authentification :

   gcloud alpha agent-identity connectors create AUTH_PROVIDER_NAME \
       --location="LOCATION" \
       --api-key="API_KEY"

2. 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 accordez le rôle Utilisateur du connecteur (roles/iamconnectors.user) au principal de l'agent.

   L'identité de l'agent est basée sur le format d'ID SPIFFE standard du secteur. Dans les stratégies d'autorisation IAM, les identités d'agent sont désigné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 dans 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 projet Google Cloud .
   • AUTH_PROVIDER_NAME : nom du fournisseur d'authentification.
   • ORGANIZATION_ID : ID de votre organisation Google Cloud .
   • PROJECT_NUMBER : numéro de votre projet Google Cloud .
   • 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 l'ADK.

ADK

Faites référence au fournisseur d'authentification dans le code de votre agent à l'aide de 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 using the auth provider's full resource name.
auth_scheme = GcpAuthProviderScheme(
    name="projects/PROJECT_ID/locations/LOCATION/connectors/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="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 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
spotify_auth_config = AuthConfig(
    auth_scheme=GcpAuthProviderScheme(
        name="projects/PROJECT_ID/locations/LOCATION/connectors/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="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 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 by providing Auth Provider full resource name
auth_scheme = GcpAuthProviderScheme(
    name="projects/PROJECT_ID/locations/LOCATION/connectors/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="YOUR_AGENT_NAME",
    model="YOUR_MODEL_NAME",
    instruction="YOUR_AGENT_INSTRUCTIONS",
    tools=[toolset],
)

  

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, 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'OAuth en deux étapes 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