Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

에이전트 ID 인증 문제 해결

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

인증 제공업체 구성에 관한 안내는 에이전트 ID 인증 제공업체 관리를 참고하세요.

리디렉션 URI 불일치

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

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

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

사용자 역할 누락

에이전트가 인증 제공업체를 사용할 수 없는 경우 에이전트 ID에 인증 제공업체 리소스에 대한 roles/agentidentity.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 키의 제한으로 인해 이 서비스에 액세스할 수 없기 때문에 발생합니다.

이 오류를 해결하려면 다음 단계를 따르세요.

Google Cloud 콘솔에서 API 및 서비스 >라이브러리 페이지로 이동하여 타겟 API가 사용 설정되어 있는지 확인합니다.
API 및 서비스 >라이브러리로 이동
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 키 문자열을 복사했고 앞이나 뒤에 공백이 포함되지 않았는지 확인합니다.

사용자 인증 정보를 가져오는 권한이 거부됨 (`agentidentity.authProviders.retrieveCredentials`)

adk web를 로컬에서 실행하거나 배포된 에이전트와 상호작용할 때 다음 403 Forbidden 오류가 발생할 수 있습니다.

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

이 오류는 인증 프로바이더를 호출하려고 시도하는 주 구성원에게 사용자 인증 정보를 가져오는 데 필요한 IAM 권한이 없기 때문에 발생합니다.

이 오류를 해결하려면 주 구성원에게 에이전트 ID 사용자 (roles/agentidentity.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의 문법 오류 또는 잘못 구성된 환경 변수로 인해 발생합니다.

이 오류를 해결하려면 다음 안내를 따르세요.

Google Cloud 콘솔을 열고 로그 탐색기 페이지로 이동합니다.
임시 배포 컨테이너 로그 (예: maps_mcp_agent_tmp... 또는 bigquery_mcp_agent_tmp...)를 검색합니다.
Python 트레이스백을 확인하여 문법 오류를 식별하거나 누락된 패키지를 추적합니다.
필수 패키지가 모두 requirements.txt 파일에 나열되어 있는지 확인합니다.

ServiceNow 인증 루프 또는 예기치 않은 범위

상담사가 3-legged OAuth를 사용하여 ServiceNow에 인증하면 인증 흐름이 실패하거나 상담사가 요청 루프에 진입할 수 있습니다.

이 문제는 ServiceNow가 에이전트가 요청한 범위가 아닌 애플리케이션 수준에서 부여된 범위를 결정하기 때문에 발생합니다. 관리자가 ServiceNow 애플리케이션에서 특정 범위를 구성하는 경우 (예: useraccount) 에이전트가 다른 범위 (예: mcp_server)를 요청하더라도 ServiceNow는 구성된 범위만 포함하는 토큰을 반환합니다. 에이전트가 요청된 범위를 엄격하게 예상하거나 검증하는 경우 수신된 토큰을 거부하고 루프에서 사용자 인증 정보를 다시 요청할 수 있습니다.

이 문제를 해결하려면 다음 단계를 따르세요.

관리자로 ServiceNow 인스턴스에 로그인합니다.
ServiceNow OAuth 애플리케이션 구성으로 이동합니다.
에이전트에 필요한 모든 범위가 애플리케이션의 허용된 범위 목록에 명시적으로 추가되어 있는지 확인합니다.
ServiceNow에서 사용 설정된 범위만 요청하도록 에이전트를 구성합니다.

자세한 내용은 지원되는 서드 파티 서비스를 참고하세요.

GitHub 또는 Microsoft 다중 범위 오류

GitHub 또는 Microsoft용 인증 제공업체를 구성할 때 여러 OAuth 범위를 요청하면 인증이 실패합니다.

인증 관리자는 GitHub 및 Microsoft의 단일 범위 통합을 지원합니다. 인증 관리자는 여러 범위를 동시에 요청하는 것을 지원하지 않습니다.

이 문제를 해결하려면 통합에 필요한 단일 범위만 요청하도록 에이전트 또는 인증 제공업체를 구성하세요.