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

KI-Agenten authentifizieren

Wenn Sie einen Agenten in Cloud Run bereitstellen, können Sie ihm eine Identität zuweisen, mit der er sich bei der Kommunikation mit APIs und anderen Agenten sicher authentifizieren kann.

Authentifizierung bei Google Cloud APIs, anderen Agents und Tools

Wenn Ihre Cloud Run-Arbeitslast mit dem Identitätstyp agent-identity konfiguriert ist, erhält sie eine vom System verwaltete Identität im folgenden Format:

principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/run/projects/PROJECT_NUMBER/locations/REGION/services/SERVICE_NAME

Bei Projekten ohne Organisation wird die Projektnummer verwendet:

principal://agents.global.project-PROJECT_NUMBER.system.id.goog/resources/run/projects/PROJECT_NUMBER/locations/REGION/services/SERVICE_NAME

Sie können diese Identität verwenden, um Ihren Agenten bei der Kommunikation mit Google Cloud APIs, anderen Agenten oder Tools sicher zu authentifizieren.

Bei Google Cloud APIs authentifizieren

Agents können ihre zugewiesene Agent-Identität verwenden, um sich beiGoogle Cloud APIs wie Vertex AI, Cloud Storage und anderenGoogle Cloud -Produkten zu authentifizieren. Dazu verwenden sie Zugriffstokens, die vom Cloud Run-Metadatenserver abgerufen werden.

Weisen Sie dem Hauptkonto Ihres Agenten die entsprechende IAM-Rolle zu, z. B.:
- Zugriff auf Vertex AI gewähren:
```
gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="AGENT_PRINCIPAL" \
    --role="roles/aiplatform.user"
```
- Zugriff auf andere Google Cloud APIs gewähren:
  
  Weisen Sie AGENT_PRINCIPAL die erforderliche Rolle für die Zielressource zu, z. B. roles/storage.objectViewer für einen Cloud Storage-Bucket. Weitere Informationen finden Sie unter Mit Standardanmeldedaten für Anwendungen authentifizieren.
Ersetzen Sie Folgendes:
- PROJECT_ID: Projekt-ID in Google Cloud .
- AGENT_PRINCIPAL: die Identität Ihres Agenten, z. B. principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/run/projects/PROJECT_NUMBER/locations/REGION/services/AGENT_NAME.
Verwenden Sie im Anwendungscode Ihres Agents Standard-Google Cloud-Clientbibliotheken. Die Clientbibliotheken verwenden automatisch Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC), um kurzlebige Zugriffstokens vom Metadatenserver abzurufen.

Alternativ können Sie ein Zugriffstoken manuell vom Metadatenserver in Ihrem Container abrufen:
```
curl -s -H "Metadata-Flavor: Google" \
"http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token"
```

Authentifizierung bei anderen Agents in Cloud Run

Wenn ein Agent einen anderen Agent aufrufen muss, der auf Cloud Run gehostet wird, z. B. A2A-Agents, authentifizieren Sie sich mit einem JWT-Identitätstoken (JSON Web Token), das von der integrierten roles/run.invoker-IAM-Prüfung von Cloud Run validiert wird:

Weisen Sie der Identität des aufrufenden Agents die Rolle roles/run.invoker für den Ziel-Cloud Run-Dienst zu:
```
gcloud run services add-iam-policy-binding TARGET_SERVICE_NAME \
    --member="CALLER_AGENT_PRINCIPAL" \
    --role="roles/run.invoker" \
    --region=REGION
```
Ersetzen Sie Folgendes:
- TARGET_SERVICE_NAME: der Name des Cloud Run-Zielagentendienstes.
- CALLER_AGENT_PRINCIPAL: die Identität des aufrufenden Agenten.
- REGION: die Google Cloud Region des Zieldienstes.

Optionen für die Tokenvalidierung

Cloud Run unterstützt zwei Methoden zur Validierung von Identitätstokens:

Nicht gebundene Tokens: Standardmäßige zielgruppenbezogene Identitätstokens, die vom Metadatenserver generiert werden. Dies ist der Standardmechanismus für die Dienst-zu-Dienst- und Agent-zu-Agent-Authentifizierung.
Gebundene Tokens: Ermöglichen die kryptografische Bindung zwischen dem Token und dem Zertifikat der Arbeitslast über mTLS. Wenn gebundene Tokens verwendet werden sollen, muss der aufrufende Client seine Blattzertifikatkette in der Anfrage angeben.

Sie können mTLS-gebundene Tokens verwenden, um Cloud Run-Ressourcen aufzurufen, die mit ingress=internal konfiguriert sind. So können Sie den öffentlichen Internetzugriff auf Ihre Agenten oder MCP-Server einschränken, ohne dass ein VPC-Netzwerk erforderlich ist.

Nicht gebundenes ID-Token abrufen

Rufen Sie im Container des aufrufenden Agents ein Identitätstoken mit der URL des Zieldienstes als Zielgruppe ab:
```
TOKEN=$(curl -s -H "Metadata-Flavor: Google" \
  "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience=TARGET_SERVICE_URL")
```
Ersetzen Sie TARGET_SERVICE_URL durch die URL des Cloud Run-Zieldienstes, z. B. https://target-agent-1234567890.us-central1.run.app.

Senden Sie Anfragen an den Zieldienst mit dem Token im Authorization-Header:

curl -H "Authorization: Bearer $TOKEN" \
  TARGET_SERVICE_URL/endpoint

Gebundenes ID-Token abrufen (mTLS)

Lesen Sie im Container des aufrufenden Agents Ihre Leaf-Zertifikatkette und fordern Sie mit einer POST-Anfrage ein gebundenes Token vom Metadatenserver an:

CERT_PATH="/var/run/secrets/workload-spiffe-credentials/certificates.pem"
JSON_PAYLOAD=$(jq -n --arg certs "$(cat $CERT_PATH)" '{"certificate_chain": $certs}')

TOKEN=$(curl -s -X POST \
    -H "Metadata-Flavor: Google" \
    -H "Content-Type: application/json" \
    -d "$JSON_PAYLOAD" \
  "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience=TARGET_SERVICE_MTLS_URL")

Rufen Sie den mTLS-Endpunkt des Zieldienstes auf und präsentieren Sie die Arbeitslastzertifikate während des TLS-Handshakes:

KEY_PATH="/var/run/secrets/workload-spiffe-credentials/private_key.pem"

curl --cert $CERT_PATH \
    --key $KEY_PATH \
    -H "Authorization: Bearer $TOKEN" \
  TARGET_SERVICE_MTLS_URL/endpoint

Beispiel für Python

Wenn Sie Python-basierten Agent-Code schreiben, fordern standardmäßige Google Cloud-Clientbibliotheken automatisch gebundene Tokens an, wenn Zertifikate vorhanden sind. Wenn Sie manuelle HTTP-Anfragen stellen müssen:

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

# Target agent's mTLS URL
target_mtls_url = "TARGET_SERVICE_MTLS_URL"

# 1. Fetch the ID token.
# google-auth automatically requests a bound ID token via POST because
# the platform configures the workload certificate environment variables.
auth_req = Request()
token = id_token.fetch_id_token(auth_req, target_mtls_url)

# 2. Make the HTTP call over mTLS, presenting the workload certificates.
cert_path = "/var/run/secrets/workload-spiffe-credentials/certificates.pem"
key_path = "/var/run/secrets/workload-spiffe-credentials/private_key.pem"

response = requests.get(
    target_mtls_url,
    headers={"Authorization": f"Bearer {token}"},
    cert=(cert_path, key_path)
)
print(response.text)

Ersetzen Sie TARGET_SERVICE_MTLS_URL durch die mTLS-URL des Cloud Run-Zieldienstes, z. B. https://target-agent-12345.us-central1.mtls.run.app.

Authentifizierung bei MCP-Servern in Cloud Run

Wenn Sie eine Verbindung zu einem MCP-Server oder ‑Tool herstellen möchten, das in Cloud Run gehostet wird, verwenden Sie die --functional-type=mcp-server-Kennung, um die automatische Registrierung des MCP-Servers in der Agent Registry zu aktivieren.

Wenn auf Ihren MCP-Server nur von anderen Agents zugegriffen wird, die in Cloud Run ausgeführt werden, verwenden Sie die integrierte IAM-Aufruferprüfung. Lassen Sie Ihre Kundenservicemitarbeiter nativ über Standardrichtlinien für den Aufruf von Läufen kommunizieren:

gcloud run services add-iam-policy-binding MCP_SERVICE_NAME \
    --member="CALLING_AGENT_PRINCIPAL" \
    --role="roles/run.invoker" \
    --region=REGION

Ersetzen Sie Folgendes:

MCP_SERVICE_NAME: der Name des Cloud Run-Zieldienstes, auf dem der MCP-Server gehostet wird.
CALLING_AGENT_PRINCIPAL: die Hauptidentität des Agents, der den MCP-Server aufruft. Beispiel: serviceAccount:my-agent@my-project.iam.iam.gserviceaccount.com
REGION: die Google Cloud Region, in der der MCP-Server bereitgestellt wird.

Nachdem die Rolle run.invoker gewährt wurde, kann der aufrufende Agent ein Identitätstoken abrufen, wie im Abschnitt Optionen für die Tokenvalidierung beschrieben.

Informationen zum Schutz von MCP-Servern mit IAP für CLI und programmatischen SDK-Zugriff finden Sie unter MCP-Server authentifizieren.

Im Namen von Nutzern authentifizieren

Wenn Ihr Agent im Namen eines Nutzers auf externe Tools und Dienste zugreift, kann er seine bereitgestellte Agentenidentität verwenden, um die Authentifizierung mit MCP-Servern und externen Endpunkten zu verwalten.

Um komplexe Autorisierungsworkflows wie die 3-legged OAuth-Zustimmung (3LO), 2-legged OAuth (2LO) und API-Schlüssel sicher zu verarbeiten, konfigurieren Sie den Agent Identity Auth Manager.

Eine Anleitung zum Binden dieser Autorisierungsmanager an Ihre Toolsets finden Sie unter Authentifizierung für Tools und Ressourcen.