排查代理身份验证问题

本文档介绍了如何解决使用代理身份进行身份验证时出现的常见 身份验证管理器错误。

重定向 URI 不匹配

如果您在 OAuth 流程期间收到第三方应用的 redirect URI mismatch 错误，请确保在第三方开发者门户中注册的重定向 URI 与身份验证管理器生成的 URI 完全一致。

如需解决此问题，请在 Google Cloud 控制台中查看身份验证提供方 详细信息，找到生成的重定向 URI，或运行以下 gcloud 命令：

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

缺少用户角色

如果您的代理无法使用身份验证提供方，请验证代理身份在身份验证提供方资源上是否具有 roles/iamconnectors.user 角色。

如需解决此问题，请使用 Google Cloud 控制台授予该角色，或运行 add-iam-policy-binding 命令。

颁发者端点问题

对于 OIDC 提供方，请验证颁发者端点是否可公开访问，以及是否支持 .well-known/openid-configuration 发现文档。

如果 Google Cloud 无法提取 OIDC 元数据或 JWKS，请确保 端点不在防火墙或受限网络后面。

401 UNAUTHENTICATED 错误

如果您的代理无法进行身份验证，则可能会出现以下错误。此错误通常是由 Google 管理的情境感知访问权限政策引起的，该政策会强制执行 mTLS 绑定和 DPoP 加密证明：

{
  "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"
  }
}

如需解决此错误，您可以在有特定的令牌共享要求或必须将令牌直接注入标头时，选择停用默认的情境感知访问权限政策。 如需停用，请在部署代理时设置以下环境变量： 部署代理

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

API 密钥服务被屏蔽 (API_KEY_SERVICE_BLOCKED)

如果您验证 API 密钥，则可能会出现以下错误。此错误表示服务被屏蔽：

"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."
  }
]

出现此错误的原因是，目标 API 服务（例如 Cloud Translation API）尚未在您的 Google Cloud 项目中启用，或者 API 密钥的限制不允许访问此服务。

如需解决此错误，请执行以下步骤：

  1. 在 Google Cloud 控制台中，前往 API 和服务>库 页面，确保目标 API 已启用。

    前往“API 和服务”>“库”

  2. 在 Google Cloud 控制台中，前往 API 和服务>凭据 页面，修改 API 密钥，并验证其 API 限制是否允许访问该服务。

    前往“API 和服务”>“凭据”

API 密钥无效 (API_KEY_INVALID)

向第三方服务发送请求时，可能会出现以下错误。此错误表示 API 密钥无效：

"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."
  }
]

出现此错误的原因是，在请求标头中传递的 API 密钥字符串不正确、格式错误或不存在于项目凭据中。

如需解决此错误，请验证您是否从控制台的 Google Cloud 凭据页面复制了正确的 API 密钥字符串，并且未包含前导或尾随空格。

检索凭据时权限遭拒 (iamconnectors.connectors.retrieveCredentials)

在本地运行 adk web 或与已部署的代理互动时，可能会出现以下 403 Forbidden 错误：

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).

出现此错误的原因是，尝试调用身份验证提供方的正文没有检索凭据所需的 IAM 权限。

如需解决此错误，请向正文授予 Connector User (roles/iamconnectors.user) 角色：

  • 如果在本地开发期间（uv run adk web 或 uvicorn）出现此错误，请确保您已向个人用户账号（user:USER_EMAIL）授予该角色。
  • 如果在与已部署的代理互动时出现此错误，请确保您已向代理的 SPIFFE ID 正文 (principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID) 授予该角色。

一般部署失败

使用 uv run adk deploy 部署代理时，该命令可能会失败并显示一般错误消息。

出现此错误的原因是缺少 Python 依赖项、agent.py 中存在语法错误或环境变量配置错误。

如需解决此错误，请执行以下操作：

  1. 打开 Google Cloud 控制台，然后前往 Logs Explorer 页面。
  2. 搜索临时部署容器日志（例如 maps_mcp_agent_tmp... 或 bigquery_mcp_agent_tmp...）。
  3. 检查 Python 回溯，以找出语法错误或跟踪缺失的软件包。
  4. 确保 requirements.txt 文件中列出了所有必需的软件包。

后续步骤