Probleme mit der Authentifizierung der Agent-Identität beheben

In diesem Dokument wird beschrieben, wie Sie häufige Fehler bei der Authentifizierung mit der Agent-Identität mit dem Auth Manager beheben.

Nicht übereinstimmender Weiterleitungs-URI

Wenn Sie während des OAuth-Ablaufs von der Drittanbieteranwendung einen Fehler redirect URI mismatch erhalten, prüfen Sie, ob der im Drittanbieter-Entwicklerportal registrierte Weiterleitungs-URI genau mit dem vom Auth Manager generierten URI übereinstimmt.

Um dieses Problem zu beheben, suchen Sie den generierten Weiterleitungs-URI, indem Sie die Details des Authentifizierungsanbieters in der Google Cloud console aufrufen, oder führen Sie den folgenden gcloud Befehl aus:

gcloud alpha agent-identity connectors describe AUTH_PROVIDER_NAME \
    --location="LOCATION"

Nutzerrolle fehlt

Wenn Ihr Agent den Authentifizierungsanbieter nicht verwenden kann, prüfen Sie, ob die Agent-Identität die Rolle roles/iamconnectors.user für die Ressource des Authentifizierungsanbieters hat.

Um dieses Problem zu beheben, weisen Sie die Rolle über die Google Cloud console zu oder führen Sie den add-iam-policy-binding Befehl aus.

Probleme mit dem Ausstellerendpunkt

Prüfen Sie bei OIDC-Anbietern, ob der Ausstellerendpunkt öffentlich zugänglich ist und das Discovery-Dokument .well-known/openid-configuration unterstützt.

Wenn Sie die OIDC-Metadaten oder JWKS nicht abrufen können, prüfen Sie, ob sich der Endpunkt hinter einer Firewall oder in einem eingeschränkten Netzwerk befindet. Google Cloud

Fehler 401 UNAUTHENTICATED

Wenn sich Ihr Agent nicht authentifizieren kann, kann der folgende Fehler auftreten. Dieser Fehler wird in der Regel durch eine von Google verwaltete Richtlinie für den kontextsensitiven Zugriff verursacht, die die mTLS-Bindung und kryptografische DPoP-Nachweise erzwingt:

{
  "error": {
    "code": 401,
    "message": "Request had invalid authentication credentials. Expected OAuth 2 access token, login cookie or other valid authentication credential. See https://developers.google.com/identity/sign-in/web/devconsole-project.",
    "status": "UNAUTHENTICATED"
  }
}

Um diesen Fehler zu beheben, können Sie die Standardrichtlinie für den kontextsensitiven Zugriff deaktivieren, wenn Sie bestimmte Anforderungen an die Tokenfreigabe haben oder das Token direkt in den Header einfügen müssen. Setzen Sie dazu beim Bereitstellen des Agents die folgende Umgebungsvariable:

config={
  "env_vars": {
    "GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES": False,
  }
}

API-Schlüssel-Dienst blockiert (API_KEY_SERVICE_BLOCKED)

Wenn Sie Ihren API-Schlüssel validieren, kann der folgende Fehler auftreten. Dieser Fehler gibt an, dass der Dienst blockiert ist:

"details": [
  {
    "@type": "type.googleapis.com/google.rpc.ErrorInfo",
    "reason": "API_KEY_SERVICE_BLOCKED",
    "domain": "googleapis.com",
    "metadata": {
      "methodName": "google.cloud.translate.v2.TranslateService.TranslateText",
      "service": "translate.googleapis.com",
      "consumer": "projects/PROJECT_NUMBER",
      "apiName": "translate"
    }
  },
  {
    "@type": "type.googleapis.com/google.rpc.LocalizedMessage",
    "locale": "en-US",
    "message": "Requests to this API translate method google.cloud.translate.v2.TranslateService.TranslateText are blocked."
  }
]

Dieser Fehler tritt auf, weil der Ziel-API-Dienst (z. B. Cloud Translation API) in Ihrem Google Cloud Projekt nicht aktiviert wurde oder die Einschränkungen des API-Schlüssels keinen Zugriff auf diesen Dienst zulassen.

So beheben Sie diesen Fehler:

  1. Rufen Sie in der Google Cloud console die Seite APIs & Dienste >Bibliothek auf und prüfen Sie, ob die Ziel-API aktiviert ist.

    Zu „APIs & Dienste >Bibliothek“

  2. Rufen Sie in der Google Cloud console die Seite APIs & Dienste >Anmeldedaten auf, bearbeiten Sie Ihren API-Schlüssel und prüfen Sie, ob die API-Einschränkungen den Zugriff auf den Dienst zulassen.

    Zu „APIs & Dienste >Anmeldedaten“

Ungültiger API-Schlüssel (API_KEY_INVALID)

Wenn Sie Anfragen an einen Drittanbieterdienst senden, kann der folgende Fehler auftreten. Dieser Fehler gibt an, dass der API-Schlüssel ungültig ist:

"details": [
  {
    "@type": "type.googleapis.com/google.rpc.ErrorInfo",
    "reason": "API_KEY_INVALID",
    "domain": "googleapis.com",
    "metadata": {
      "service": "translate.googleapis.com"
    }
  },
  {
    "@type": "type.googleapis.com/google.rpc.LocalizedMessage",
    "locale": "en-US",
    "message": "API key not valid. Please pass a valid API key."
  }
]

Dieser Fehler tritt auf, weil die im Anfrageheader übergebene API-Schlüssel-String falsch oder fehlerhaft ist oder nicht in den Anmeldedaten Ihres Projekts vorhanden ist.

Um diesen Fehler zu beheben, prüfen Sie, ob Sie die richtige API-Schlüssel-String von der Seite Anmeldedaten in der Google Cloud console kopiert haben und ob keine Leerzeichen am Anfang oder Ende vorhanden sind.

Berechtigung zum Abrufen von Anmeldedaten verweigert (iamconnectors.connectors.retrieveCredentials)

Wenn Sie adk web lokal ausführen oder mit Ihrem bereitgestellten Agent interagieren, kann der folgende Fehler 403 Forbidden auftreten:

google.api_core.exceptions.Forbidden: 403 POST https://iamconnectorcredentials.mtls.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/connectors/AUTH_PROVIDER_NAME/credentials:retrieve?%24alt=json%3Benum-encoding%3Dint: Permission 'iamconnectors.connectors.retrieveCredentials' denied on resource '//iamconnectors.googleapis.com/projects/PROJECT_ID/locations/LOCATION/connectors/AUTH_PROVIDER_NAME' (or it may not exist).

Dieser Fehler tritt auf, weil das Prinzipal, das versucht, den Authentifizierungsanbieter aufzurufen, nicht die erforderlichen IAM-Berechtigungen zum Abrufen von Anmeldedaten hat.

Um diesen Fehler zu beheben, weisen Sie dem Prinzipal die Rolle Connector-Nutzer (roles/iamconnectors.user) zu:

  • Wenn dieser Fehler während der lokalen Entwicklung auftritt (uv run adk web oder uvicorn), prüfen Sie, ob Sie die Rolle Ihrem persönlichen Nutzerkonto zugewiesen haben (user:USER_EMAIL).
  • Wenn dieser Fehler bei der Interaktion mit einem bereitgestellten Agent auftritt, prüfen Sie, ob Sie die Rolle dem SPIFFE-ID-Prinzipal Ihres Agents zugewiesen haben (principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID).

Allgemeiner Bereitstellungsfehler

Wenn Sie Ihren Agent mit uv run adk deploy bereitstellen, kann der Befehl mit einer allgemeinen Fehlermeldung fehlschlagen.

Dieser Fehler tritt aufgrund fehlender Python-Abhängigkeiten, Syntaxfehlern in agent.py oder falsch konfigurierten Umgebungsvariablen auf.

So beheben Sie diesen Fehler:

  1. Öffnen Sie die Google Cloud console und rufen Sie die Seite Log-Explorer auf.
  2. Suchen Sie nach den Logs des temporären Bereitstellungscontainers (z. B. maps_mcp_agent_tmp... oder bigquery_mcp_agent_tmp...).
  3. Prüfen Sie den Python-Traceback, um den Syntaxfehler zu identifizieren oder fehlende Pakete zu verfolgen.
  4. Prüfen Sie, ob alle erforderlichen Pakete in der Datei requirements.txt aufgeführt sind.

Nächste Schritte