Authentifizierung bei externen Diensten mit der Identität eines KI-Agenten

Auf Google Cloud gehostete Agents können ihre eigene Identität verwenden, um sich bei Tools und Diensten zu authentifizieren, die in Google Cloud -Laufzeiten wie Cloud Run oder Google Kubernetes Engine (GKE) gehostet werden. Dazu fordern sie ein OpenID Connect-ID-Token (OIDC) von Agent Identity an. Agents können diese ID-Tokens auch verwenden, um sich bei Cloud-Plattformen von Drittanbietern (z. B. Amazon Web Services (AWS) und Microsoft Azure), benutzerdefinierten APIs, API-Gateways und lokalen Backends zu authentifizieren.

Wenn ein Agent in eigener Verantwortung auf einen externen Dienst zugreift, stellt Agent Identity ein OpenID Connect-ID-Token (OIDC) aus. Dieses JSON Web Token (JWT) bestätigt die SPIFFE-Identität des Agents und wird von den Ausstellerschlüsseln für die vertrauenswürdige Domain des Agents (verwalteter Workload Identity-Pool) signiert. Externe Systeme können diese Tokens ohne Google Cloud Anmeldedaten oder SDKs über öffentliche Endpunkte prüfen, die vom Google Cloud Security Token Service gehostet werden:

  • Ein OpenID Connect Discovery 1.0-Endpunkt (/.well-known/openid-configuration), der die OpenID-Anbietermetadaten und den Endpunkt für öffentliche Schlüssel (jwks_uri) veröffentlicht.
  • Ein JWKS-Endpunkt (JSON Web Key Set) (/openid/jwks), der die aktiven öffentlichen Schlüssel bereitstellt, mit denen Signaturen für Agent-ID-Tokens überprüft werden.

Hinweis

  1. Prüfen Sie, ob Sie die richtige Authentifizierungsmethode ausgewählt haben. In der Übersicht zur Agent Identity erfahren Sie, wie SPIFFE-Identitäten, Vertrauensdomänen und Agenten-Anmeldedaten funktionieren.
  2. Erstellen und stellen Sie einen Agenten mit aktivierter Agent-Identität bereit.
  3. Ihr externer Dienst oder Identitätsanbieter muss die folgenden Anforderungen erfüllen:
  4. Ermitteln Sie die folgenden Konfigurationswerte für Ihren Agent und den externen Zieldienst:
    • Aussteller-URL (iss-Anspruch): Die Aussteller-URL des Workload Identity-Pools für Ihre Organisation (https://sts.googleapis.com/v1/organizations/ORGANIZATION_ID/locations/global/workloadIdentityPools/TRUST_DOMAIN) oder Ihr Projekt (https://sts.googleapis.com/v1/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/TRUST_DOMAIN).
    • Zulässige Zielgruppe (aud-Anspruch): Der Zielgruppen-URI, den der externe Dienst oder Identitätsanbieter bei der Validierung von ID-Tokens erwartet.
  5. 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 Bereitstellen eines Agents mit Agent Identity benötigen:

  • Stellen Sie einen Agent in der Agent Runtime auf der Gemini Enterprise Agent Platform bereit: Vertex AI-Nutzer (roles/aiplatform.user)
  • Agent-Dienst in Cloud Run bereitstellen: Cloud Run-Administrator (roles/run.admin)

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

Diese vordefinierten Rollen enthalten die Berechtigungen, die zum Bereitstellen eines Agents mit Agent Identity erforderlich sind. Maximieren Sie den Abschnitt Erforderliche Berechtigungen, um die notwendigen Berechtigungen anzuzeigen:

Erforderliche Berechtigungen

Die folgenden Berechtigungen sind erforderlich, um einen Agent mit Agent-Identität bereitzustellen:

  • So stellen Sie einen Agenten in der Agent Runtime auf der Gemini Enterprise Agent Platform bereit:
    • aiplatform.reasoningEngines.create
    • aiplatform.reasoningEngines.update
  • Agent-Dienst in Cloud Run bereitstellen:
    • run.services.create
    • run.services.update

Sie können diese Berechtigungen auch mit benutzerdefinierten Rollen oder anderen vordefinierten Rollen erhalten.

OIDC-ID-Token für einen Agenten abrufen

So konfigurieren Sie Ihren Agent, damit er ein OIDC-ID-Token abruft und an einen externen Dienst sendet:

  1. KI-Agent mit der Agent-Identität konfigurieren
  2. OIDC-ID-Token im Anwendungscode anfordern

KI‑Agent mit der Funktion „Agent Identity“ konfigurieren

Aktivieren Sie die Agent-Identität, wenn Sie Ihren Agenten bereitstellen:

  • Wenn Sie Ihren Agenten in der Agent Runtime on Gemini Enterprise Agent Platform bereitstellen, legen Sie identity_type auf AGENT_IDENTITY fest:

    remote_app = client.agent_engines.create(
    agent=app,
    config={
        "identity_type": types.IdentityType.AGENT_IDENTITY,
        "requirements": ["google-cloud-aiplatform[agent_engines,adk]"],
    },
)

  • Wenn Sie einen containerisierten Agent-Dienst in Cloud Run bereitstellen, übergeben Sie das Flag --identity-type=agent-identity:

    gcloud run deploy SERVICE_NAME \
    --image=IMAGE_URL \
    --identity-type=agent-identity \
    --no-allow-unauthenticated

    Ersetzen Sie Folgendes:

    • SERVICE_NAME: Der Name Ihres Cloud Run-Dienstes.
    • IMAGE_URL: Die Container-Image-URL für Ihren Agent.

OIDC-ID-Token im Anwendungscode anfordern

Verwenden Sie im Anwendungscode Ihres Agents die Google Auth-Clientbibliothek, um ein OIDC-ID-Token für Ihre externe Zielgruppe anzufordern. Die Clientbibliothek übernimmt die Tokengenerierung, das lokale Caching und die automatische Erneuerung vom Metadatenserver.

Standardmäßig sind OIDC-ID-Tokens, die für externe Zielgruppen ausgestellt werden, nicht an das Laufzeitzertifikat gebunden.

Im folgenden Beispiel wird die google-auth-Bibliothek verwendet, um ein OIDC-ID-Token anzufordern und es als Bearer-Token an eine ausgehende Anfrage anzuhängen:

Python

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

# 1. Specify the audience expected by the external receiver
# (for example, AWS Bedrock AgentCore or your external service URL).
target_audience = "https://EXTERNAL_SERVICE_AUDIENCE"

# 2. Create ID token credentials and an AuthorizedSession, which handles
# local token caching, automatic renewal before expiry, and the Bearer header.
credentials = id_token.fetch_id_token_credentials(audience=target_audience)
authed_session = AuthorizedSession(credentials)

# 3. Send the authenticated request to the external service.
response = authed_session.post(
    "https://EXTERNAL_SERVICE_ENDPOINT",
    json={"prompt": "Hello from Agent"},
)

Ersetzen Sie Folgendes:

  • EXTERNAL_SERVICE_AUDIENCE: Der Zielgruppen-URI, der von Ihrem empfangenden Dienst erwartet wird (z. B. bedrock.us-east-1.amazonaws.com oder api.example.com).
  • EXTERNAL_SERVICE_ENDPOINT: Die URL der externen API oder des Backend-Endpunkts, die von Ihrem Agenten aufgerufen wird.

Anleitungen und Beispiele für Clientbibliotheken in anderen Programmiersprachen (einschließlich Go, Node.js und Java) finden Sie unter ID-Token abrufen. Die aktuellen Clientbibliotheksversionen für diese Sprachen unterstützen --identity-type=agent-identity, verwenden aber standardmäßig keine gebundenen Tokens.

ID-Tokens für Agent Identity überprüfen

Wenn ein externer Dienst ein OIDC-ID-Token von Ihrem Agent erhält, prüfen Sie das Token mit einer der folgenden Methoden, je nach Zieldienst:

  • Verwaltete Cloud-Plattformen (z. B. Cloud Run, AWS oder Microsoft Azure): Verwenden Sie die integrierte Workload Identity-Föderation, um eingehende Tokens zu überprüfen, ohne benutzerdefinierten Bestätigungscode schreiben zu müssen.
  • Benutzerdefinierte Backend-Dienste, API-Gateways und lokale Arbeitslasten: Tokens programmatisch überprüfen mit den öffentlichen OpenID Connect Discovery- und JWKS-Endpunkten.

Integrierte Workload Identity-Föderation verwenden

Wenn Ihr Empfangsdienst auf einer Cloud-Plattform ausgeführt wird, die die integrierte IAM-Authentifizierung oder die OIDC-Identitätsföderation von Arbeitslasten unterstützt, müssen Sie keinen benutzerdefinierten Code zur Tokenüberprüfung schreiben:

  • Cloud Run: Wenn Ihr empfangender Dienst in Cloud Run mit authentifiziertem eingehenden Traffic (--no-allow-unauthenticated) ausgeführt wird, validiert Cloud Run eingehende Agent Identity-Tokens auf der Ingress-Ebene. Gewähren Sie dem aufrufenden Agent die Rolle „Cloud Run Invoker“ (roles/run.invoker) für den empfangenden Dienst. Weitere Informationen finden Sie unter Bei MCP-Servern in Cloud Run authentifizieren.

    Wenn Ihr Dienst nicht authentifizierten Ingress zulässt und Tokens im Anwendungscode überprüft, lesen Sie den Abschnitt Tokens programmgesteuert überprüfen.

  • Amazon Bedrock: Konfigurieren Sie die eingehende JWT-Authentifizierung, indem Sie dieGoogle Cloud Security Token Service-Discovery-URL oder die Aussteller-URL und die erwartete Zielgruppe angeben. Eine Anleitung finden Sie in der AWS-Dokumentation unter Inbound-JWT-Autorisierung konfigurieren.

  • Microsoft Entra ID: Konfigurieren Sie Anmeldedaten für föderierte Identitäten mit dem Szenario Anderer Aussteller. Geben Sie die Aussteller-URL des Google Cloud Security Token Service , die erwartete Zielgruppe und die Subjekt-ID (sub-Anspruch) an. Eine Anleitung finden Sie in der Microsoft Learn-Dokumentation unter Vertrauensstellung zwischen einer App und einem externen Identitätsanbieter erstellen.

Tokens programmatisch überprüfen

Wenn Ihr Agent Anfragen an eine benutzerdefinierte API, einen Mikrodienst, ein API-Gateway oder eine lokale Arbeitslast sendet, muss der empfangende Dienst das eingehende OIDC-ID-Token überprüfen, bevor er Zugriff gewährt. Ihr KI-Agent übergibt dieses Token in der Regel im Authorization: Bearer TOKEN-HTTP-Header.

So überprüfen Sie eingehende ID-Tokens programmatisch:

  1. Aussteller-URL des Tokens extrahieren und validieren
  2. Öffentliche Signaturschlüssel ermitteln und im Cache speichern
  3. Tokensignatur und ‑ansprüche überprüfen
  4. SPIFFE-Identität des Agents autorisieren

URL des Tokenausstellers extrahieren und validieren

Wenn eine eingehende Anfrage eintrifft, lesen Sie die nicht bestätigte JWT-Nutzlast, um den Anspruch iss (Aussteller) zu extrahieren. Dieser Anspruch enthält die URL des Workload Identity-Pools für die vertrauenswürdige Domain des Agents. Diese URL dient als Basis-URL für das Discovery-Dokument und die öffentlichen Signaturschlüssel.

Bevor Sie ausgehende Netzwerkanfragen stellen, prüfen Sie, ob der iss-Anspruch mit der erwarteten Google Cloud -URL des Security Token Service-Workload Identity-Pools für Ihre Organisation oder Ihr Projekt übereinstimmt:

  • Vertrauenswürdige Domains auf Organisationsebene:

    https://sts.googleapis.com/v1/organizations/ORGANIZATION_ID/locations/global/workloadIdentityPools/TRUST_DOMAIN

    Für eine Organisation mit der ID 123456789012 ist TRUST_DOMAIN beispielsweise agents.global.org-123456789012.system.id.goog.

  • Vertrauenswürdige Domains auf Projektebene (für Projekte ohne Organisation):

    https://sts.googleapis.com/v1/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/TRUST_DOMAIN

    Für ein Projekt mit der Nummer 9876543210 ist TRUST_DOMAIN beispielsweise agents.global.proj-9876543210.system.id.goog.

Öffentliche Signaturschlüssel ermitteln und im Cache speichern

Nachdem Sie die Aussteller-URL validiert haben, rufen Sie die öffentlichen Signaturschlüssel vom Google Cloud Security Token Service ab und speichern Sie sie im Cache:

  1. OpenID Connect-Discovery-Endpunkt abfragen: Hängen Sie /.well-known/openid-configuration an die Basis-Aussteller-URL an und senden Sie eine nicht authentifizierte HTTP-GET-Anfrage:

    Ersetzen Sie diese Werte in den folgenden Anfragedaten:

    • ORGANIZATION_ID: Ihre Google Cloud Organisations-ID. Ersetzen Sie bei einem Projekt ohne Organisation organizations/ORGANIZATION_ID durch projects/PROJECT_NUMBER.
    • TRUST_DOMAIN: Die ID des Workload Identity-Pools für die Vertrauensdomäne Ihres Agenten (z. B. agents.global.org-123456789012.system.id.goog).

    HTTP-Methode und URL: 

    GET https://sts.googleapis.com/v1/organizations/ORGANIZATION_ID/locations/global/workloadIdentityPools/TRUST_DOMAIN/.well-known/openid-configuration

    Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

    Bei einer erfolgreichen Anfrage wird der Status HTTP 200 OK und ein JSON-Objekt mit den OpenID-Anbietermetadaten zurückgegeben, einschließlich des Felds jwks_uri:

    {
  "issuer": "https://sts.googleapis.com/v1/organizations/123456789012/locations/global/workloadIdentityPools/agents.global.org-123456789012.system.id.goog",
  "jwks_uri": "https://sts.googleapis.com/v1/organizations/123456789012/locations/global/workloadIdentityPools/agents.global.org-123456789012.system.id.goog/openid/jwks",
  "authorization_endpoint": "https://sts.googleapis.com/v1/organizations/123456789012/locations/global/workloadIdentityPools/agents.global.org-123456789012.system.id.goog/authorize",
  "token_endpoint": "https://sts.googleapis.com/v1/organizations/123456789012/locations/global/workloadIdentityPools/agents.global.org-123456789012.system.id.goog/token",
  "response_types_supported": [
    "id_token"
  ],
  "subject_types_supported": [
    "public"
  ],
  "id_token_signing_alg_values_supported": [
    "RS256"
  ]
}

  2. JWKS-Endpunkt (JSON Web Key Set) abfragen: Senden Sie eine nicht authentifizierte HTTP-GET-Anfrage an die jwks_uri-URL, die in den OpenID-Anbietermetadaten zurückgegeben wird:

    Ersetzen Sie diese Werte in den folgenden Anfragedaten:

    • ORGANIZATION_ID: Ihre Google Cloud Organisations-ID. Ersetzen Sie bei einem Projekt ohne Organisation organizations/ORGANIZATION_ID durch projects/PROJECT_NUMBER.
    • TRUST_DOMAIN: Die ID des Workload Identity-Pools für die Vertrauensdomäne Ihres Agenten (z. B. agents.global.org-123456789012.system.id.goog).

    HTTP-Methode und URL: 

    GET https://sts.googleapis.com/v1/organizations/ORGANIZATION_ID/locations/global/workloadIdentityPools/TRUST_DOMAIN/openid/jwks

    Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

    Bei einer erfolgreichen Anfrage wird der Status HTTP 200 OK und ein JSON-Objekt mit einem Array von öffentlichen Schlüsseln zurückgegeben, die gemäß RFC 7517 formatiert sind:

    {
  "keys": [
    {
      "kty": "RSA",
      "use": "sig",
      "alg": "RS256",
      "kid": "4d1933f8e6c4e0b512c140989f6655c68997...",
      "n": "uQn4zN_1mQ0VpGv82-Wp3w...",
      "e": "AQAB"
    }
  ]
}

  3. Discovery-Dokument und Schlüssel im Cache speichern: Antworten vom OpenID Connect Discovery-Endpunkt und vom JWKS-Endpunkt enthalten den folgenden HTTP-Cache-Header:

    Cache-Control: public, max-age=86400, must-revalidate

    Das Discovery-Dokument und die JWKS können bis zu 24 Stunden (86400 Sekunden) im Cache gespeichert werden, um die Überprüfungsleistung zu verbessern und Ratenbegrenzungen zu vermeiden.

    Google Cloud rotiert regelmäßig die privaten und öffentlichen Signaturschlüssel für Workload Identity-Pools. Wenn Ihr Verifier ein eingehendes Token mit einer kid (Schlüssel-ID) empfängt, die sich nicht in seinem lokalen Schlüsselcache befindet, rufen Sie ein neues JWKS vom /openid/jwks-Endpunkt ab, bevor Sie das Token ablehnen.

    Wenn beim Abfragen der Discovery- oder JWKS-Endpunkte HTTP-Fehler auftreten, lesen Sie den Abschnitt Probleme bei der Authentifizierung der Agent-Identität beheben.

Tokensignatur und ‑claims prüfen

Verwenden Sie eine Standardbibliothek für die OIDC- oder JWT-Verifizierung (z. B. Google Tink), um die Tokensignatur kryptografisch zu verifizieren und die JWT-Ansprüche zu validieren. Gehen Sie dazu so vor:

  1. Signatur: Suchen Sie im zwischengespeicherten JWKS nach dem öffentlichen Schlüssel, der mit der kid (Schlüssel-ID) im JWT-Header übereinstimmt. Validieren Sie die Signatur mit dem Algorithmus, der im Feld alg (RS256) angegeben ist. Um die Vorwärtskompatibilität zu gewährleisten, sollten Sie die Felder alg und kty in den JWKS dynamisch prüfen, anstatt Algorithmustypen fest zu codieren.
  2. Aussteller (iss): Prüfen Sie, ob der iss-Anspruch mit der vertrauenswürdigenGoogle Cloud -Aussteller-URL des Workload Identity-Pools für Ihre Vertrauensdomäne übereinstimmt.
  3. Zielgruppe (aud): Prüfen Sie, ob der aud-Anspruch mit der konfigurierten Zielgruppen-ID Ihres Dienstes übereinstimmt.
  4. Ausstellungszeitpunkt (iat) und Ablaufzeit (exp): Prüfen Sie, ob die Anforderung iat in der Vergangenheit liegt und die aktuelle Zeit vor der Anforderung exp liegt (mit einer geringen Toleranz für die Zeitabweichung, z. B. 1 bis 2 Minuten).

Im folgenden Beispiel wird Google Tink (tink.jwt) verwendet, um ein Agent Identity-ID-Token anhand einer JWKS-JSON-Nutzlast zu überprüfen:

Python

import tink
from tink import jwt

# Initialize Tink JWT signature primitives (call once at application startup).
jwt.register_jwt_signature()


def verify_agent_identity_token(
    token: str,
    jwks_json: str,
    expected_issuer: str,
    expected_audience: str,
) -> jwt.VerifiedJwt:
    """Verifies an Agent Identity JWT against a JWKS JSON string using Tink.

    Args:
        token: The compact serialized JWT string.
        jwks_json: The JWKS JSON string fetched from the STS pool endpoint.
        expected_issuer: The expected token issuer ('iss' claim).
        expected_audience: The expected token audience ('aud' claim).

    Returns:
        jwt.VerifiedJwt: The verified JWT claims object.

    Raises:
        tink.TinkError: If the JWKS cannot be parsed, the key is not found,
            or token validation (signature, issuer, audience, expiration) fails.
    """
    # 1. Convert the JWKS JSON into a Tink public KeysetHandle.
    keyset_handle = jwt.jwk_set_to_public_keyset_handle(jwks_json)

    # 2. Instantiate the Tink JwtPublicKeyVerify primitive.
    jwt_verifier = keyset_handle.primitive(jwt.JwtPublicKeyVerify)

    # 3. Configure expected validation rules (issuer, audience, expiration).
    # Google Cloud STS sets 'typ': 'JWT' in the header, so
    # expected_type_header="JWT" is required.
    validator = jwt.new_validator(
        expected_issuer=expected_issuer,
        expected_audience=expected_audience,
        expected_type_header="JWT",
        allow_missing_expiration=False,
    )

    # 4. Cryptographically verify the signature and standard OIDC claims.
    return jwt_verifier.verify_and_decode(token, validator)

SPIFFE-Identität des KI-Agenten autorisieren

Nachdem Sie die Signatur und die Standardansprüche des Tokens überprüft haben, prüfen Sie den bestätigten Anspruch sub (subject), um die Anfrage zu autorisieren und den aufrufenden Agent in Ihren Audit-Logs zu erfassen.

Der sub-Anspruch enthält die eindeutige SPIFFE-ID des Agenten, z. B.:

  spiffe://agents.global.org-123456789012.system.id.goog/resources/aiplatform/projects/9876543210/locations/us-central1/reasoningEngines/my-test-agent

Vergleichen Sie in der Autorisierungslogik Ihres Dienstes den bestätigten sub-Anspruch mit einer Zulassungsliste vertrauenswürdiger Agent-SPIFFE-IDs (oder Vertrauensdomänenpräfixe), bevor Sie den Zugriff auf geschützte Ressourcen gewähren.

Nächste Schritte