IAM 통합 액세스 정책 문제 해결

이 문서는 Agent Gateway 이그레스에 대한 IAM 통합 액세스 정책 (UAP)을 구성하고 적용할 때 발생하는 일반적인 문제를 진단하고 해결하는 데 도움이 됩니다.

정책 시정 조치 및 액세스 실패

이 섹션에서는 시행 문제를 설명합니다.

정책이 시행되지 않음

증상: 액세스를 차단하도록 IAM 거부 규칙 또는 제한적인 허용 규칙이 구성되어 있어도 에이전트가 대상 도구, MCP 서버 또는 엔드포인트에 액세스할 수 있습니다.

원인: Agent Gateway 승인 확장 프로그램이 테스트 실행 모드로 실행 중이거나 정책 바인딩 범위가 대상 리소스와 일치하지 않습니다. 테스트 실행 모드에서는 액세스 결정이 평가되고 감사를 위해 로깅되지만 요청은 차단되지 않습니다.

해결책:

  1. 테스트 실행 모드를 시행 모드로 전환: 먼저 승인 확장 프로그램 구성 파일(iap-request-authz-extension.yaml)을 확인합니다. iamEnforcementMode이 "DRY_RUN"로 설정되어 있으면 "ENFORCE"로 업데이트하거나 DRY_RUN 설정을 삭제하고 gcloud CLI를 사용하여 확장 프로그램을 다시 가져옵니다.

    gcloud service-extensions authz-extensions import EXTENSION_NAME \
    --source=EXTENSION_FILE.yaml \
    --location=LOCATION

    다음을 바꿉니다.

    • EXTENSION_NAME: 승인 확장 프로그램의 이름
    • EXTENSION_FILE: YAML 확장 프로그램 구성의 파일 이름
    • LOCATION: 게이트웨이가 배포된 Google Cloud 리전

  2. 게이트웨이 승인 정책 위임 확인: 게이트웨이 승인 정책 (policyProfile: REQUEST_AUTHZ)이 올바른 Agent Gateway 인스턴스 (target.resources)에 바인딩되어 있는지 확인합니다.

  3. 정책 바인딩 범위 확인: IAM UAP가 트래픽이 도착하는 대상 리소스 범위에 바인딩되어 있는지 확인합니다.

  4. 규칙 우선순위 검사: 조합 정책에서 거부 규칙은 동일한 범위의 허용 규칙을 명시적으로 재정의합니다. 그러나 레지스트리 또는 프로젝트 수준에서 바인딩된 더 넓은 허용 규칙이 있는 UAP가 조건 제한 없이 액세스 권한을 부여하는지 확인합니다.

시정 조치 정책이 에이전트 액세스를 차단함

증상: Agent Gateway 정책 시행이 사용 설정된 경우 에이전트의 이그레스 요청이 HTTP 403 Forbidden 또는 PERMISSION_DENIED 오류와 함께 실패합니다.

원인:

  • 에이전트의 ID가 UAP에 지정되지 않았습니다.

  • 에이전트의 ID에 대상 리소스에 대한 iap.resources.egressViaIAP 권한이 부여되지 않았습니다.

  • 정확한 대상 호스트 이름이 Agent Registry에 등록되지 않았습니다.

  • 요청 속성이 UAP의 Common Expression Language (CEL) 조건을 충족하지 않습니다.

해결책:

  1. 중단 없는 디버깅을 위해 테스트 실행 모드로 전환: 실패를 진단하는 동안 감사 로그를 검사하는 동안 활성 에이전트 트래픽이 차단되지 않도록 승인 확장 프로그램을 일시적으로 테스트 실행 모드 (iamEnforcementMode: "DRY_RUN")로 전환합니다.

  2. Cloud 감사 로그 쿼리: Cloud 감사 로그를 쿼리하여 정확한 승인 확인 및 CEL 속성 평가를 검사합니다.

    gcloud

    다음 gcloud logging read 명령어를 실행합니다.

    gcloud logging read \
    'protoPayload.serviceName="iap.googleapis.com" AND protoPayload.authorizationInfo.permission="iap.resources.egressViaIAP" AND protoPayload.status.code!=0' \
    --project=PROJECT_ID \
    --limit=20

    PROJECT_ID를 프로젝트 ID로 바꿉니다.

    콘솔

    1. 콘솔에서 Google Cloud 로그 탐색기 페이지로 이동합니다.
    2. 프로젝트를 선택합니다.
    3. 쿼리 편집기에서 다음 쿼리를 입력합니다. 
          protoPayload.serviceName="iap.googleapis.com"
    protoPayload.authorizationInfo.permission="iap.resources.egressViaIAP"
    protoPayload.status.code!=0
    4. 쿼리 실행 을 클릭합니다.
    5. 로그 항목을 펼치고 protoPayload.authorizationInfo를 검사하여 평가에 실패한 대상 리소스 URI와 권한을 확인합니다.

  3. 정확한 호스트 이름 일치 확인: Agent Gateway는 대상 호스트 이름을 정확히 일치시킵니다. Google API 또는 서드 파티 서비스는 SDK 버전, 리전 클라이언트 구성 또는 mTLS 사용에 따라 여러 호스트 이름 변형을 통해 확인할 수 있습니다(예: us-central1-aiplatform.googleapis.com 대 us-central1-aiplatform.mtls.googleapis.com 대 aiplatform.googleapis.com).

    • 등록된 대상을 사용하는 경우 모든 정확한 호스트 이름 변형이 Agent Registry에 등록되어 있는지 확인합니다.
    • 에이전트가 등록되지 않은 엔드포인트에 액세스하는 경우 등록되지 않은 엔드포인트 정책 이 해당 호스트 및 경로에 대해 iap.resources.egressViaIAP를 부여하는지 확인합니다.

  4. 범위 전반의 정책 바인딩 적용 범위 확인: 정책 바인딩이 지원되는 세 가지 범위 중 하나에 있는지 확인합니다.

    • 레지스트리 전체: 레지스트리의 모든 에이전트, MCP 서버, 엔드포인트에 대한 액세스 권한을 부여합니다.
    • 리소스별: 특정 등록된 MCP 서버, 엔드포인트 또는 에이전트에 대한 액세스 권한을 부여합니다.
    • 등록되지 않은 엔드포인트: Agent Registry 외부의 대상에 대한 액세스 권한을 부여합니다.
    • 참고: 대상 리소스의 정책 바인딩을 설명할 때 반환된 출력에 "etag" 필드는 포함되지만 바인딩은 포함되지 않는 경우 해당 대상에 대한 IAM 정책이 없습니다.

일반적인 UI, gcloud, REST API 오류 메시지

이 섹션에서는 오류 메시지와 해결 방법을 설명합니다.

정책을 찾을 수 없음

오류 메시지:

  • 콘솔 UI: "요청된 정책이 없습니다. 선택한 리소스에 정책이 있는지 확인하세요.'
  • API / gcloud: POLICY_NOT_FOUND / HTTP 404 Not Found

원인: 업데이트 요청 또는 정책 바인딩에 지정된 UAP ID가 프로젝트 또는 위치에 없거나 삭제되었습니다.

해결책: 프로젝트에서 사용 가능한 모든 UAP를 사용하여 gcloud iam access-policies list --project=<var>PROJECT_ID</var> --location=global 바인딩하거나 업데이트하기 전에 정확한 정책 ID와 위치를 확인합니다.

대상 바인딩 한도 초과

오류 메시지:

  • 콘솔 UI: "선택한 대상이 액세스 정책 바인딩 한도에 도달했습니다. 새 바인딩을 추가하기 전에 기존 바인딩을 삭제하세요.'
  • API / gcloud: TOO_MANY_ACCESS_POLICY_BINDINGS_PER_TARGET

원인: 대상당 허용되는 최대 한도보다 많은 정책 바인딩을 대상 리소스 (예: MCP 서버 또는 레지스트리)에 연결하려고 했습니다.

해결책: 개별 규칙마다 별도의 UAP 및 바인딩을 만드는 대신 여러 허용 또는 거부 규칙을 단일 UAP로 통합합니다. gcloud iam policy-bindings delete를 사용하여 사용하지 않는 바인딩을 삭제합니다.

정책 바인딩 한도 초과

오류 메시지:

  • 콘솔 UI: "선택한 정책의 바인딩 한도에 도달했습니다. 새 바인딩을 추가하기 전에 기존 바인딩을 삭제하세요.'
  • API / gcloud: TOO_MANY_ACCESS_POLICY_BINDINGS_TO_POLICY

원인: 단일 UAP가 프로젝트 전반에서 너무 많은 고유한 대상 리소스에 연결되어 있습니다.

해결책: 레지스트리 전체 범위 (AgentRegistry) 또는 프로젝트 범위와 같은 더 넓은 범위에서 정책을 바인딩하고 CEL 속성 조건 (예: destination.agent_registry.mcp_server.name)을 사용하여 정책 규칙 내에서 개별 도구에 대한 액세스를 관리합니다.

조건 한도 초과

오류 메시지:

  • 콘솔 UI: "이 정책이 최대 속성 조건 수에 도달했습니다. 변경사항을 저장하려면 일부 조건을 삭제하세요.'
  • API / gcloud: TOO_MANY_CONDITIONS / 정책의 규칙에 대한 조건 한도 초과

원인: 단일 허용 또는 거부 규칙에 단일 규칙에서 지원되는 것보다 세분화된 액세스 제어 (FGAC) 속성 조건 또는 복잡한 하위 표현식이 더 많이 포함되어 있습니다.

해결책: CEL 논리 연산자 (&&, ||) 또는 집합 포함 조회 (in)를 사용하여 속성 검사를 통합하거나 동일한 UAP 내에서 여러 규칙에 걸쳐 표현식을 분할합니다.

규칙 세부정보가 오래됨

오류 메시지:

  • 콘솔 UI: "규칙 세부정보가 오래되었습니다. 이 페이지가 로드된 후에 다른 사용자가 이 규칙을 수정했습니다. 수정하거나 삭제하기 전에 페이지를 새로고침하여 현재 세부정보를 가져오세요.'
  • API / gcloud: etag 불일치로 인한 HTTP 412 Precondition Failed / ABORTED

원인: 다른 관리자 또는 자동화된 프로세스가 UAP를 가져온 후에 수정하여 요청의 etag가 활성 서버 상태와 달라졌습니다.

해결책: 콘솔 페이지를 새로고침하여 활성 정책 세부정보 와 etag를 가져온 후 수정사항을 저장합니다. REST API를 사용하는 경우 먼저 GET 요청을 실행하여 활성 "etag" 값을 가져오고 PATCH 요청 페이로드에 포함합니다.

정책에서 마지막 규칙을 삭제할 수 없음

오류 메시지:

  • 콘솔 UI: "이 규칙을 삭제할 수 없습니다. '기본 정책'에는 규칙이 하나 이상 있어야 합니다. 이 규칙을 삭제하려면 대신 정책을 삭제하세요." 또는 "<정책 이름>의 마지막 규칙입니다. 이 규칙을 삭제하면 정책도 삭제되고 연결된 모든 바인딩이 영구적으로 삭제되어 리소스에 대한 에이전트 액세스에 영향을 미칠 수 있습니다."

원인: 규칙이 없는 IAM UAP는 저장할 수 없습니다.

해결책: 정책에서 유일한 규칙을 삭제하려면 전체 정책을 삭제합니다. 정책 자체를 삭제하기 전에 정책을 참조하는 모든 정책 바인딩을 삭제해야 합니다.

고급 탭에 보관된 커스텀 CEL 표현식

오류 메시지:

  • 콘솔 UI: "커스텀 CEL 표현식을 표준 UI 선택 항목으로 변환할 수 없습니다. 표현식은 고급 탭에 보관됩니다.'

원인: 표준 조건 빌더의 간소화된 드롭다운 선택기로 매핑할 수 없는 복잡한 CEL 조건 또는 함수를 조건 편집기 (고급 탭)에 입력했습니다.

해결책: 이 메시지는 정보 제공을 위한 알림입니다. 커스텀 CEL 조건이 유효하며 보관됩니다. 조건 편집기 탭 내에서 직접 수정 작업을 계속합니다.

다음 단계