에이전트 ID 인증 문제 해결

이 문서에서는 일반적인 인증 관리자를 사용한 에이전트 ID를 사용한 인증 오류를 해결하는 방법을 설명합니다.

리디렉션 URI 불일치

OAuth 흐름 중에 서드 파티 애플리케이션에서 redirect URI mismatch 오류가 표시되면 서드 파티 개발자 포털에 등록된 리디렉션 URI가 인증 관리자에서 생성된 URI와 정확히 일치하는지 확인하세요.

이 문제를 해결하려면 Google Cloud 콘솔에서 인증 제공업체 세부정보를 확인하여 생성된 리디렉션 URI를 찾거나 다음 gcloud 명령어를 실행하세요.

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

사용자 역할 누락

에이전트가 인증 제공업체를 사용할 수 없는 경우 에이전트 ID에 인증 제공업체 리소스에 대한 roles/iamconnectors.user 역할이 있는지 확인합니다.

이 문제를 해결하려면 Google Cloud 콘솔을 사용하여 역할을 부여하거나 add-iam-policy-binding 명령어를 실행하세요.

발급자 엔드포인트 문제

OIDC 제공업체의 경우 발급기관 엔드포인트에 공개적으로 액세스할 수 있고 .well-known/openid-configuration 탐색 문서를 지원하는지 확인합니다.

Google Cloud 가 OIDC 메타데이터 또는 JWKS를 가져올 수 없는 경우 엔드포인트가 방화벽 뒤에 있거나 제한된 네트워크에 있지 않은지 확인하세요.

401 UNAUTHENTICATED 오류

에이전트가 인증할 수 없는 경우 다음 오류가 발생할 수 있습니다. 이 오류는 일반적으로 mTLS 바인딩 및 DPoP 암호화 증명을 적용하는 Google 관리 컨텍스트 인식 액세스 정책으로 인해 발생합니다.

{
  "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 권한이 없기 때문에 발생합니다.

이 오류를 해결하려면 주 구성원에게 커넥터 사용자 (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 콘솔을 열고 로그 탐색기 페이지로 이동합니다.
  2. 임시 배포 컨테이너 로그 (예: maps_mcp_agent_tmp... 또는 bigquery_mcp_agent_tmp...)를 검색합니다.
  3. Python 트레이스백을 확인하여 구문 오류를 식별하거나 누락된 패키지를 추적합니다.
  4. 필수 패키지가 모두 requirements.txt 파일에 나열되어 있는지 확인합니다.

다음 단계