Wenn Sie Ihrem KI-Agenten im Namen eines bestimmten Endnutzers Zugriff auf externe Tools und Dienste (z. B. Jira-Aufgaben oder GitHub-Repositories) gewähren möchten, konfigurieren Sie im Authentifizierungsmanager für die Identität von KI-Agenten einen Authentifizierungsanbieter für das dreibeinige OAuth.
Dreibeinige OAuth-Authentifizierungsanbieter verwalten die Nutzerweiterleitung und Tokens für Sie. Dadurch ist es nicht mehr erforderlich, benutzerdefinierten Code für die Verarbeitung komplexer OAuth 2.0-Abläufe zu schreiben.
Dreibeiniger OAuth-Ablauf
Für 3-legged OAuth-Authentifizierungsanbieter ist die Einwilligung des Nutzers erforderlich, da der Agent im Namen des Nutzers auf Ressourcen zugreift.
- Aufforderung und Weiterleitung: Die Chatoberfläche fordert den Nutzer auf, sich anzumelden, und leitet ihn dann zur Einwilligungsseite der Drittanbieteranwendung weiter.
- Einwilligung und Speicherung: Nachdem der Nutzer die Berechtigung erteilt hat, speichert der Agent Identity-Authentifizierungsmanager die resultierenden OAuth-Tokens in einem von Google verwalteten Anmeldedatenspeicher.
- Einfügen: Wenn Sie das Agent Development Kit (ADK) verwenden, ruft der Agent das Token automatisch vom Authentifizierungsanbieter ab und fügt es in die Header des Toolaufrufs ein.
Hinweis
- Prüfen Sie, ob Sie die richtige Authentifizierungsmethode ausgewählt haben.
-
Aktivieren Sie die Agent Identity Connector API.
Rollen, die zum Aktivieren von APIs erforderlich sind
Zum Aktivieren von APIs benötigen Sie die Berechtigung
serviceusage.services.enable. Wenn Sie das Projekt erstellt haben, haben Sie diese Berechtigung wahrscheinlich bereits über die Rolle „Inhaber“ (roles/owner). Andernfalls können Sie diese Berechtigung über die Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin) erhalten. Informationen zum Zuweisen von Rollen - Agent erstellen und bereitstellen.
- Sie benötigen eine Frontend-Anwendung, um Nutzeranmeldeaufforderungen und Weiterleitungen zu Drittanbieter-Einwilligungsseiten zu verarbeiten.
- Prüfen Sie, ob Sie die Rollen haben, die für diese Aufgabe erforderlich sind.
Erforderliche Rollen
Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für das Projekt zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Erstellen und Verwenden eines 3-Legged-Authentifizierungsanbieters benötigen:
-
So erstellen Sie Authentifizierungsanbieter:
- IAM Connector Admin (
roles/iamconnectors.admin) - IAM Connector Editor (
roles/iamconnectors.editor)
- IAM Connector Admin (
-
So verwenden Sie Authentifizierungsanbieter:
- IAM Connector User (
roles/iamconnectors.user) - Vertex AI-Nutzer (
roles/aiplatform.user) - Service Usage Consumer (
roles/serviceusage.serviceUsageConsumer)
- IAM Connector User (
Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.
Diese vordefinierten Rollen enthalten die Berechtigungen, die zum Erstellen und Verwenden eines 3-Legged-Authentifizierungsanbieters erforderlich sind. Maximieren Sie den Abschnitt Erforderliche Berechtigungen, um die notwendigen Berechtigungen anzuzeigen:
Erforderliche Berechtigungen
Die folgenden Berechtigungen sind erforderlich, um einen 3-Legged-Authentifizierungsanbieter zu erstellen und zu verwenden:
-
So erstellen Sie Authentifizierungsanbieter:
iamconnectors.connectors.create -
So verwenden Sie Authentifizierungsanbieter:
-
iamconnectors.connectors.retrieveCredentials -
aiplatform.endpoints.predict -
aiplatform.sessions.create
-
Sie können diese Berechtigungen auch mit benutzerdefinierten Rollen oder anderen vordefinierten Rollen erhalten.
Anbieter für die 3-legged-Authentifizierung erstellen
Erstellen Sie einen Authentifizierungsanbieter, um die Konfiguration und Anmeldedaten für Drittanbieteranwendungen zu definieren.
Verwenden Sie die Google Cloud Console oder die Google Cloud CLI, um einen 3-legged-Authentifizierungsanbieter zu erstellen.
Console
- Rufen Sie in der Google Cloud Console die Seite Agent Registry auf.
- Klicken Sie auf den Namen des Agenten, für den Sie einen Authentifizierungsanbieter erstellen möchten.
- Klicken Sie auf Identität.
- Klicken Sie im Bereich Authentifizierungsanbieter auf Authentifizierungsanbieter hinzufügen.
-
Geben Sie im Bereich Authentifizierungsanbieter hinzufügen einen Namen und eine Beschreibung ein.
Der Name darf nur Kleinbuchstaben, Ziffern oder Bindestriche enthalten, darf nicht mit einem Bindestrich enden und muss mit einem Kleinbuchstaben beginnen.
- Wählen Sie in der Liste OAuth Type (OAuth-Typ) die Option OAuth (3 legged) (OAuth (3-legged)) aus.
- Klicken Sie auf Erstellen und fortfahren.
- Wenn Sie der Identität Ihres Agents die Berechtigung zur Verwendung des Autorisierungsanbieters erteilen möchten, klicken Sie auf Zugriff gewähren.
Dadurch wird der Agent-Identität in der Ressource des Authentifizierungsanbieters automatisch die Rolle Connector User (
roles/iamconnectors.user) zugewiesen. - Kopieren Sie die Rückruf-URL.
- Registrieren Sie die Callback-URL auf einem separaten Tab in Ihrer OAuth-Clientanwendung eines Drittanbieters.
- Geben Sie im Bereich Anmeldedaten des Authentifizierungsanbieters die folgenden Informationen ein:
- Client-ID
- Client-Secret
- Token-URL
- Autorisierungs-URL
- Klicken Sie auf Anbieterkonfiguration hinzufügen.
Der neu erstellte Authentifizierungsanbieter wird in der Liste Auth Providers (Authentifizierungsanbieter) angezeigt.
gcloud-CLI
-
Konfigurieren Sie Ihre OAuth-Clientanwendung, um Ihren Client zu registrieren und eine Client-ID und einen Clientschlüssel zu erhalten. Geben Sie den Weiterleitungs-URI mit der Vorlage in diesem Abschnitt an.
-
Erstellen Sie den Authentifizierungsanbieter mit Ihren Clientanmeldedaten:
gcloud alpha agent-identity connectors create
AUTH_PROVIDER_NAME\ --project="PROJECT_ID" \ --location="LOCATION" \ --three-legged-oauth-client-id="CLIENT_ID" \ --three-legged-oauth-client-secret="CLIENT_SECRET" \ --three-legged-oauth-authorization-url="AUTHORIZATION_URL" \ --three-legged-oauth-token-url="TOKEN_URL" - Prüfen Sie, ob Ihr Authentifizierungsanbieter in der Liste aufgeführt ist und den Status
ENABLEDhat:gcloud alpha agent-identity connectors list \ --project="
PROJECT_ID" \ --location="LOCATION" -
Gewähren Sie Zugriffsberechtigungen, damit Ihr Agent und Ihre lokale Entwicklungsumgebung Anmeldedaten vom Authentifizierungsanbieter abrufen können. Damit Ihr bereitgestellter Agent und Ihr persönliches Nutzerkonto auf den Authentifizierungsanbieter zugreifen können, weisen Sie die Rolle Connector User (
roles/iamconnectors.user) für die Authentifizierungsanbieterressource zu:-
Gewähren Sie Zugriff auf die SPIFFE-ID Ihres bereitgestellten Agenten (Agentenidentität):
gcloud alpha agent-identity connectors add-iam-policy-binding
AUTH_PROVIDER_NAME\ --project="PROJECT_ID" \ --location="LOCATION" \ --role="roles/iamconnectors.user" \ --member="principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID" -
Gewähren Sie Zugriff auf Ihr persönliches Nutzerkonto für die lokale Entwicklung und das lokale Testen (
adk web):gcloud alpha agent-identity connectors add-iam-policy-binding
AUTH_PROVIDER_NAME\ --project="PROJECT_ID" \ --location="LOCATION" \ --role="roles/iamconnectors.user" \ --member="user:USER_EMAIL"
-
Ersetzen Sie Folgendes:
PROJECT_ID: Ihre Google Cloud Projekt-IDLOCATION: Der Ort, an dem Ihr Authentifizierungsanbieter und Ihr Agent bereitgestellt werden (z. B.us-west1).AUTH_PROVIDER_NAME: Der Name Ihres Authentifizierungsanbieters (z. B.bigquery-mcp-3lo-authprovider).AUTHORIZATION_URL: Die URL des Autorisierungsservers (z. B.https://accounts.google.com/o/oauth2/v2/auth).TOKEN_URL: Die Token-Server-URL (z. B.https://oauth2.googleapis.com/token).CLIENT_ID: Die OAuth-Client-ID, die Sie vom Drittanbieterdienst generiert haben.CLIENT_SECRET: Der OAuth-Clientschlüssel, den Sie vom Drittanbieterdienst generiert haben.ORGANIZATION_ID: Ihre Google Cloud Organisations-ID.PROJECT_NUMBER: Ihre Google Cloud Projektnummer.ENGINE_ID: Die ID Ihres bereitgestellten Reasoning-Engine-Agents.USER_EMAIL: Die E-Mail-Adresse Ihres persönlichen Nutzerkontos.
OAuth-Clientanwendung konfigurieren
Bevor Sie Ihre OAuth-Clientanmeldedaten registrieren, müssen Sie eine Client-ID und einen Clientschlüssel vom Autorisierungsserver des Drittanbieters (z. B. Google, GitHub oder Jira) abrufen.
Wenn Sie eine Verbindung zu einem Drittanbieterdienst außerhalb vonGoogle Cloudherstellen, rufen Sie die OAuth-Clientanmeldedaten über das Entwicklerportal dieses Dienstes ab und überspringen Sie die Schritte in diesem Abschnitt.
Weiterleitungs-URI registrieren
Wenn Sie Ihre OAuth-Clientanmeldedaten konfigurieren, müssen Sie den dedizierten Callback-Weiterleitungs-URI des Authentifizierungsanbieters registrieren.
Erstellen Sie den Weiterleitungs-URI mit der folgenden Vorlage:
https://iamconnectorcredentials.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/connectors/CONNECTOR_NAME/oauthcallbackErsetzen Sie Folgendes:
PROJECT_ID: Ihre Google Cloud Projekt-IDLOCATION: The region where your auth provider will be deployed (for example,us-west1`).CONNECTOR_NAME: Der Name Ihres Authentifizierungsanbieters.
Beispiel:
https://iamconnectorcredentials.googleapis.com/v1/projects/my-project/locations/us-west1/connectors/bigquery-mcp-3lo-authprovider/oauthcallbackWenn Sie eine Verbindung zu Google Cloud -Diensten (z. B. BigQuery) herstellen, können Sie den Einwilligungsbildschirm konfigurieren und OAuth-Clientanmeldedaten in der Google Cloud -Konsole erstellen:
-
OAuth-Zustimmungsbildschirm konfigurieren:
- Rufen Sie in der Google Cloud Console die Seite APIs & Dienste >OAuth-Zustimmungsbildschirm auf.
- Geben Sie im Bereich App-Informationen einen Anwendungsnamen (z. B. „BigQuery Manager Application“) und eine Support-E-Mail-Adresse ein.
- Wählen Sie im Bereich Zielgruppe die Option Intern oder Extern aus.
- Geben Sie Ihre Kontaktdaten ein, um Benachrichtigungen zu erhalten.
- Lesen und akzeptieren Sie die Nutzerdatenrichtlinie für Google API-Dienste.
- Klicken Sie auf Beenden.
-
OAuth-Clientanmeldedaten erstellen:
- Rufen Sie in der Google Cloud Console die Seite APIs & Dienste >OAuth-Zustimmungsbildschirm >Clients auf.
Rufen Sie „APIs & Dienste“ > „OAuth-Zustimmungsbildschirm“ >„Clients“ auf.
- Klicken Sie auf Anmeldedaten erstellen > OAuth-Client-ID.
- Wählen Sie in der Liste die Option Webanwendung aus.
- Geben Sie einen aussagekräftigen Namen für Ihren OAuth-Client ein.
- Klicken Sie im Abschnitt Autorisierte Weiterleitungs-URIs auf URI hinzufügen und geben Sie den erstellten Weiterleitungs-URI ein.
- Klicken Sie auf Erstellen. Kopieren Sie im Dialogfeld OAuth-Client erstellt die generierten Werte für Client-ID und Clientschlüssel.
- Rufen Sie in der Google Cloud Console die Seite APIs & Dienste >OAuth-Zustimmungsbildschirm >Clients auf.
-
Im Agent-Code authentifizieren
Zur Authentifizierung Ihres Agenten können Sie das ADK verwenden oder die Agent Identity API direkt aufrufen.
ADK
Verweisen Sie im Code Ihres KI-Agenten mit dem MCP-Toolset im ADK auf den Authentifizierungsanbieter.
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="AGENT_NAME", model="gemini-2.5-flash", instruction="AGENT_INSTRUCTIONS", tools=[toolset], )
Beispiel: Verbindung zu BigQuery MCP herstellen
Im folgenden Beispiel wird eine agent.py-Konfiguration gezeigt, mit der ein Agent über 3-legged OAuth eine Verbindung zum BigQuery MCP-Server herstellt:
import os from google.adk.agents import Agent from google.adk.apps import App from google.adk.auth.credential_manager import CredentialManager from google.adk.integrations.agent_identity import GcpAuthProvider, GcpAuthProviderScheme from google.adk.models import Gemini from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams from google.adk.tools.mcp_tool.mcp_toolset import McpToolset import google.auth from google.genai import types _, project_id = google.auth.default() os.environ["GOOGLE_CLOUD_PROJECT"] = "PROJECT_ID" os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "True" bigquery_mcp_auth_provider_id = "AUTH_PROVIDER_NAME" bigquery_mcp_endpoint = os.environ.get( "BIGQUERY_MCP_ENDPOINT", "https://bigquery.googleapis.com/mcp" ) # Register Google Cloud auth provider for Agent Identity Credentials service CredentialManager.register_auth_provider(GcpAuthProvider()) # The URI to redirect the user to after consent is granted and the callback is received. CONTINUE_URI = "http://127.0.0.1:8501/validateUserId" bigquery_mcp_auth_scheme = GcpAuthProviderScheme( name=f"projects/{project_id}/locations/LOCATION/connectors/{bigquery_mcp_auth_provider_id}", scopes=["https://www.googleapis.com/auth/bigquery"], continue_uri=CONTINUE_URI, ) bigquery_mcp_tools = McpToolset( connection_params=StreamableHTTPConnectionParams(url=bigquery_mcp_endpoint), auth_scheme=bigquery_mcp_auth_scheme, errlog=None, ) root_agent = Agent( name="root_agent", model=Gemini( model="gemini-2.5-flash", retry_options=types.HttpRetryOptions(attempts=3), ), instruction=( "You are a helpful AI assistant designed to provide accurate and useful" " information. You can also use your BigQuery MCP tools to look up" " BigQuery data." ), tools=[bigquery_mcp_tools], ) app = App( root_agent=root_agent, name="AGENT_NAME", )
ADK
Verweisen Sie im Code Ihres KI-Agenten mit einem authentifizierten Funktionstool im ADK auf den Authentifizierungsanbieter.
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="AGENT_NAME", model="gemini-2.5-flash", 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
Verweisen Sie im Code Ihres KI-Agenten mit dem MCP-Toolset für die Agent-Registrierung im ADK auf den Authentifizierungsanbieter.
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/PROJECT_ID/locations/LOCATION/connectors/AUTH_PROVIDER_NAME", continue_uri=CONTINUE_URI ) # 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"),