Google verwendet KI-Technologie, um Inhalte in Ihre bevorzugte Sprache zu übersetzen. KI-Übersetzungen können Fehler enthalten.

Authentifizierung bei Google Cloud mit der Identität eines Agents

Agenten können mit ihrer eigenen Identität auf Google Cloud -APIs und andere Ressourcen zugreifen. Google empfiehlt diese Methode für Agenten, die auf Google Cloudgehostet werden, um mit anderen Google Cloud -Diensten zu interagieren.

Wenn ein Agent eigenständig handelt, verwendet er seine primäre SPIFFE-Identität, um Zugriffstokens für Google Cloud anzufordern.

Hinweis

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für die Zielressource zuzuweisen, um die Berechtigungen zu erhalten, die Sie benötigen, um einem Agenten Zugriff auf Google Cloud -Dienste zu gewähren:

So gewähren Sie einem KI-Agenten Zugriff:
- Projekt-IAM-Administrator (roles/resourcemanager.projectIamAdmin)
- Sicherheitsadministrator (roles/iam.securityAdmin)
Empfohlene Rollen für die Agentenidentität:
- Agent Context Editor (roles/aiplatform.agentContextEditor)
- Standardzugriff für Agenten (roles/aiplatform.agentDefaultAccess)
- Service Usage Consumer (roles/serviceusage.serviceUsageConsumer)
- Browser (roles/browser)
- Storage-Objekt-Betrachter (roles/storage.objectViewer)

Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Sie können die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.

Agenten Zugriff gewähren

Damit Ihr Agent auf einen Google Cloud -Dienst zugreifen kann, müssen Sie der Identität des Agents die erforderlichen Rollen für die Zielressource zuweisen.

In IAM-Zulassungsrichtlinien verwenden Agentenidentitäten Hauptkonto-IDs.

Wenn Sie einem Agent Zugriff auf eine Ressource gewähren möchten, verwenden Sie die Google Cloud Console oder die gcloud CLI.

Console

Rufen Sie in der Google Cloud Console die Seite IAM für die Ressource auf, auf die Sie Zugriff gewähren möchten.
- Rufen Sie für ein Projekt die Seite IAM auf:
  Zur IAM-Seite
- Rufen Sie für andere Ressourcen die Seite für diese Ressource auf und klicken Sie auf den Tab Berechtigungen oder IAM.
Klicken Sie auf Zugriff gewähren.
Geben Sie im Feld Neue Hauptkonten die Hauptkonto-ID ein, die der Zugriffsebene entspricht, die Sie gewähren möchten:
- Einzelner Agent: principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID
- Alle Agenten in einem Projekt: principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER
- Alle Agenten in einer Organisation: principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/*
Suchen Sie im Feld Rolle auswählen nach der Rolle, die Sie gewähren möchten, und wählen Sie sie aus.
Klicken Sie auf Speichern.

Google Cloud CLI

Führen Sie den folgenden Befehl aus, um einem Agent Zugriff auf eine Ressource zu gewähren:

gcloud SERVICE add-iam-policy-binding RESOURCE_NAME \
    --member="PRINCIPAL_IDENTIFIER" \
    --role="ROLE"

Ersetzen Sie Folgendes:

SERVICE: Der Dienst von Google Cloud (z. B. storage oder bigquery).
RESOURCE_NAME: Der Name der Ressource (z. B. der Bucket-Name oder die Dataset-ID).
PRINCIPAL_IDENTIFIER: Die Hauptkonto-ID, die der Zugriffsebene entspricht, die Sie gewähren möchten:
- Einzelner Agent: principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID
- Alle Agenten in einem Projekt: principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER
- Alle Agenten in einer Organisation: principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/*
ORGANIZATION_ID: Ihre Organisations-ID von Google Cloud .
PROJECT_NUMBER: Ihre Google Cloud -Projektnummer.
LOCATION: Der Standort Ihres Agenten (z. B. us-central1). (Nur für den Zugriff durch einen einzelnen Agenten erforderlich.)
ENGINE_ID: Die ID Ihrer Reasoning Engine. (Nur für den Zugriff auf einen einzelnen KI-Agenten erforderlich.)
ROLE: Die IAM-Rolle, die Sie zuweisen möchten.

Agentenidentität im Code referenzieren

Die Google Cloud -Clientbibliotheken verwenden automatisch die Agentenidentität, wenn Ihr Agent in einer unterstützten Google Cloud -Umgebung bereitgestellt wird.

Das folgende Python-Snippet zeigt, wie Sie Agent Identity-Anmeldedaten manuell verwenden, um die Cloud Vision API mit dem Agent Development Kit (ADK) aufzurufen.

from google.cloud import vision
from google.auth import default
from google.adk.tools import tool

@tool
def analyze_image_from_gcs(gcs_uri: str) -> dict:
    # Application default credentials automatically retrieve the
    # Agent Identity token from the metadata server.
    agent_identity_credentials, project_id = default()

    client = vision.ImageAnnotatorClient(
        credentials=agent_identity_credentials,
        project=project_id
    )

    # Prepare the image object with the Cloud Storage URI.
    image = vision.Image()
    image.source.image_uri = gcs_uri

    # Perform label detection on the image.
    response = client.label_detection(image=image)

    # Check for any errors returned by the API.
    if response.error.message:
        return {"status": "failure", "error_message": response.error.message}

    labels = response.label_annotations
    return {"status": "success", "labels": [label.description for label in labels]}

Optional: Zertifikatsgebundene Tokens deaktivieren

Eine von Google verwaltete Standardrichtlinie für den kontextsensitiven Zugriff trägt zum Schutz der Anmeldedaten für die Agentenidentität bei. Über das Agent Gateway hinaus erzwingt die Richtlinie den Nachweis des Besitzes (Demonstrating Proof of Possession, DPoP) durch Authentifizierung des Zugriffstokens des KI-Agenten. Die Richtlinie erfordert außerdem gegenseitiges TLS (mTLS) für den Zugriff auf das KI-Agenten-Gateway. Diese Anforderung trägt dazu bei, dass nur die beabsichtigte, vertrauenswürdige Laufzeitumgebung, z. B. ein Cloud Run-Container oder ein Google Kubernetes Engine-Pod (GKE), die zertifikatsgebundenen Tokens verwenden kann. Diese Sicherheitsgrundlage sorgt dafür, dass gestohlene Anmeldedaten nicht wiederverwendet werden können, und trägt so zum Schutz vor Diebstahl von Anmeldedaten und Kontoübernahme bei.

Die Zertifikatsbindung schützt zwei Arten von Agent-Anmeldedaten:

Google Cloud -Zugriffstokens: Kurzlebige OAuth 2.0-Zugriffstokens, die Anfragen an Google Cloud APIs und andere Ressourcen (*.googleapis.com) authentifizieren.
OIDC-ID-Tokens (OpenID Connect): JSON Web Tokens (JWTs), die Anfragen an externe Dienste und an Tools und Dienste authentifizieren, die auf Laufzeiten von Google Cloud gehostet werden, z. B. Cloud Run (*.mtls.run.app) oder GKE.

Bindung für alle Zugriffs- und ID-Tokens deaktivieren

Es wird nicht empfohlen, die Standardrichtlinie für den kontextsensitiven Zugriff und zertifikatsgebundene Tokens in der gesamten Laufzeitumgebung zu deaktivieren. Wenn Sie GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN=false festlegen, wird der Tokenbindungsschutz sowohl für Google Cloud -Zugriffstokens als auch für OIDC-ID-Tokens entfernt. Dadurch sind diese kurzlebigen Tokens anfällig für Diebstahl oder Replay-Angriffe.

In den folgenden seltenen Fällen können Sie die Funktion jedoch für die gesamte Laufzeitumgebung deaktivieren:

Sie haben bestimmte Anforderungen an die Tokenfreigabe zwischen Agenten.
Sie müssen das Token direkt in den Anfrageheader einfügen.
Ihr Agent kann sich nicht authentifizieren und gibt den Fehler 401 UNAUTHENTICATED zurück.

Wenn Sie die Funktion für die gesamte Laufzeitumgebung deaktivieren möchten, legen Sie beim Bereitstellen des Agents die folgende Umgebungsvariable fest:

config={
  "env_vars": {
    "GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN": "false",
  }
}

Deaktivierung für einzelne ID-Token-Anfragen

Standardmäßig binden unterstützte Google Auth-Clientbibliotheken OIDC-ID-Tokens kryptografisch an das eindeutige X.509-Zertifikat des Agents, indem sie den Zertifikat-Fingerabdruck in die cnf-Anforderung (x5t#S256) des Tokens einfügen.

Einige Dienste wie Cloud Run erzwingen die Zertifikatsbindung, wenn der Anspruch cnf vorhanden ist. Wenn Ihr Agent diese Dienste über einen Nicht-mTLS-Endpunkt aufruft, z. B. eine Standard-*.run.app-URL, oder wenn für einen Zielendpunkt keine Zertifikatsbindung erforderlich ist, können Sie die Bindung für einzelne ID-Token-Anfragen deaktivieren. Diese Einstellung wirkt sich nur auf diese Anfrage aus und deaktiviert die Zertifikatsbindung für Google Cloud -Zugriffstokens nicht.

Python

Legen Sie in der Python-Bibliothek google-auth (2.61.0 oder höher in GKE und 2.62.0 oder höher in Cloud Run) bind_id_token=False fest:

from google.auth.transport.requests import AuthorizedSession
from google.auth.transport.requests import Request
from google.oauth2 import id_token

target_audience = "https://TARGET_SERVICE_URL"

# Option 1: Use AuthorizedSession with IDTokenCredentials
credentials = id_token.fetch_id_token_credentials(
    audience=target_audience,
    bind_id_token=False,
)
authed_session = AuthorizedSession(credentials)
response = authed_session.get(target_audience)

# Option 2: Fetch a raw ID token directly
token = id_token.fetch_id_token(
    Request(),
    audience=target_audience,
    bind_id_token=False,
)

Ersetzen Sie TARGET_SERVICE_URL durch den Zielgruppen-URI oder die URL des empfangenden Dienstes, den Ihr Agent aufruft.

Agent bereitstellen

Wenn Sie Ihren KI-Agenten in Google Cloudbereitstellen, muss die Agentenidentität aktiviert sein. Wenn Sie die Bereitstellung in der Agent Runtime auf der Gemini Enterprise Agent Platform vornehmen, verwenden Sie das Flag 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]"],
    },
)