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

KI-Agenten authentifizieren

Wenn Sie einen Agent 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 Agenten 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 im Format die Projektnummer verwendet:

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

Mit dieser Identität können Sie Ihren Agenten bei der Kommunikation mit Google Cloud APIs, anderen Agenten oder Tools sicher authentifizieren.

Authentifizierung bei Google Cloud APIs

Agenten können ihre zugewiesene Agentenidentität verwenden, um sich bei Google Cloud APIs wie Vertex AI, Cloud Storage und anderen Google 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:
  
  Gewähren Sie AGENT_PRINCIPAL die erforderliche Rolle für die Zielressource, z. B. roles/storage.objectViewer für einen Cloud Storage-Bucket. Weitere Informationen finden Sie unter siehe Mit Standardanmeldedaten für Anwendungen authentifizieren.
Ersetzen Sie Folgendes:
- PROJECT_ID: Ihre Google Cloud Projekt-ID.
- 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 die 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 Agenten in Cloud Run

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

Weisen Sie der Identität des aufrufenden Agenten 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 Ziel-Cloud Run-Agentendienstes.
- CALLER_AGENT_PRINCIPAL: die Identität des aufrufenden Agenten.
- REGION: die Google Cloud Region des Zieldienstes.

Optionen zur Tokenvalidierung

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

Ungebundene Tokens: Standard-Identitätstokens, die vom Metadatenserver generiert werden und an die Zielgruppe gebunden sind. Dies ist der Standardmechanismus für die Authentifizierung von Dienst zu Dienst und von Agent zu Agent.
Gebundene Tokens: bieten eine kryptografische Bindung zwischen dem Token und dem Zertifikat der Arbeitslast mithilfe von mTLS. Wenn Sie gebundene Tokens verwenden möchten, stellt der aufrufende Client seine Leaf-Zertifikatskette in der Anfrage bereit.

Ungebundenes ID-Token abrufen

Rufen Sie im Container des aufrufenden Agenten 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 Ziel-Cloud Run-Dienstes, 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 Agenten Ihre Leaf-Zertifikatskette 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 Arbeitslast Zertifikate 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 Agentencode schreiben, fordern die Standard-Google Cloud-Clientbibliotheken standardmäßig 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 Ziel-Cloud Run-Dienstes, 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 Kennung --functional-type=mcp-server, um die automatische Registrierung des MCP-Servers in der Agent Registry zu aktivieren.

Wenn auf Ihren MCP-Server nur von anderen Agenten zugegriffen wird, die in Cloud Run ausgeführt werden, verwenden Sie die integrierte IAM-Invoker-Prüfung. Lassen Sie Ihre Agenten nativ mit Standardrichtlinien für den Aufruf ausführen:

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 Ziel-Cloud Run-Dienstes, der den MCP-Server hostet.
CALLING_AGENT_PRINCIPAL: die Hauptkonto-Identität des Agenten, der den MCP-Server aufruft. Beispiel: serviceAccount:my-agent@my-project.iam..
REGION: die Google Cloud Region, in der der MCP-Server bereitgestellt wird.

Nachdem Sie die run.invoker Rolle gewährt haben, kann der aufrufende Agent ein Identität token abrufen, wie im Abschnitt Optionen zur Tokenvalidierung beschrieben.

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

Authentifizierung im Namen von Nutzern

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

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

Eine Anleitung zum Binden dieser Auth Manager an Ihre Toolsets finden Sie unter Authentifizierung bei Tools und Ressourcen.