범위가 지정된 사용자 인증 정보로 에이전트 권한 제한

조정자 에이전트가 원격 Agent2Agent(A2A) 에이전트를 호출할 때 사용자 인증 정보의 범위를 지정하면 원격 에이전트가 해당 요청에 필요한 권한만 받도록 할 수 있습니다. 에이전트 레지스트리에서 에이전트를 검색한 후 제한된 OAuth 범위 또는 Cloud Storage의 사용자 인증 정보 액세스 경계와 함께 에이전트 아이덴티티 인증 관리자를 사용하여 사용자의 사용자 인증 정보를 포함하거나 범위가 지정된 토큰을 생성할 수 있습니다.

시작하기 전에

A2A 호출에 대해 범위가 지정된 사용자 인증 정보로 에이전트 권한을 제한하기 전에 다음 단계를 완료하세요.

  1. Agent Registry 설정

  2. 단일 프로젝트 설정의 경우 Agent Registry가 사용 설정된 거버넌스 프로젝트의 프로젝트 ID를 가져옵니다. 여러 프로젝트에 대해 관리 경계를 구성한 경우 경계 전체 검색 및 등록에 관리 프로젝트 ID를 사용하거나 단일 프로젝트 작업에 구성원 프로젝트 ID를 지정합니다.

  3. Cloud Storage 토큰을 제한하려면 프로젝트에서 Security Token Service API(sts.googleapis.com)를 사용 설정합니다.

  4. google-auth 및 requests Python 라이브러리를 설치합니다.

    pip install --upgrade google-auth requests

  5. 로컬 개발을 위해 애플리케이션 기본 사용자 인증 정보(ADC)를 구성합니다. 그렇지 않으면 서비스 계정 또는 워크로드 아이덴티티 제휴 사용자 인증 정보 구성을 연결합니다.

    gcloud auth application-default login

필요한 역할

로컬 개발에 사용자 계정을 사용하거나 오케스트레이터 에이전트의 서비스 계정 또는 에이전트 보안 주체를 사용하여 등록된 에이전트를 검색하고 대상 A2A 에이전트를 호출할 수 있습니다. 사용자 계정, 서비스 계정 또는 에이전트 주 구성원에 이러한 작업을 완료할 수 있는 적절한 역할이 있어야 합니다.

사용자 계정, 서비스 계정 또는 에이전트 보안 주체에 Agent Registry에서 A2A 에이전트를 검색하고 대상 A2A 에이전트를 호출하는 데 필요한 권한이 있는지 확인하려면 관리자에게 사용자 계정, 서비스 계정 또는 에이전트 보안 주체에 다음 IAM 역할을 부여해 달라고 요청하세요.

  • Agent Registry에서 에이전트를 검색하려면 Agent Registry가 사용 설정된 거버넌스 프로젝트에 대한 Agent Registry API 뷰어(roles/agentregistry.viewer) 역할이 필요합니다.
  • 런타임에 대상 A2A 에이전트를 호출하려면 대상 에이전트를 호스팅하는 서비스의 런타임 또는 게이트웨이 역할이 필요합니다. 예를 들어 대상 에이전트가 Cloud Run에서 실행되는 경우 계정 또는 주 구성원에 Cloud Run 호출자 역할(roles/run.invoker)이 있어야 합니다.

역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

관리자는 커스텀 역할이나 다른 사전 정의된 역할을 통해 사용자 계정, 서비스 계정 또는 에이전트 보안 주체에 필요한 권한을 부여할 수도 있습니다.

에이전트 간 사용자 인증 정보 전달 방식

A2A 클라이언트 또는 조정자 에이전트가 원격 에이전트에 메시지를 전송하면 다운스트림 서비스는 요청이 인증되는 방식에 따라 권한을 확인합니다.

  • 사용자 대신: 사용자가 조정자 에이전트에 로그인하면 조정자 에이전트가 사용자 승인 OAuth 2.0 토큰 또는 인증 관리자에서 관리하는 토큰을 원격 A2A 에이전트에 전달합니다. Google Cloud API는 토큰을 확인하고 사용자의 Identity and Access Management(IAM) 권한을 확인하므로 원격 에이전트는 사용자가 액세스할 수 없는 리소스에 액세스할 수 없습니다.
  • 에이전트 자체 ID 사용: 조정자 에이전트가 로그인한 사용자 없이 실행되면 자체 에이전트 ID 또는 서비스 계정으로 인증합니다. 다운스트림 서비스는 해당 에이전트의 주 구성원(principal://), 일치하는 주 구성원 집합(principalSet://) 또는 서비스 계정에 부여된 역할을 확인합니다.
  • 외부 또는 크로스 클라우드 워크로드에서:Google Cloud 외부에서 실행되는 에이전트는 워크로드 아이덴티티 제휴를 통해 외부 ID 공급업체의 토큰을 교환하여 제휴 Google Cloud 액세스 토큰을 가져온 후 대상 A2A Agent Endpoint를 호출합니다.

토큰이 원격 에이전트에 부여하는 권한을 제한하려면 서드 파티 또는 SaaS A2A 에이전트에 대해 바인딩을 사용하여 OAuth 토큰의 범위를 제한하면 됩니다.

사용자 인증 정보 액세스 경계를 사용하여 Cloud Storage 토큰을 제한하여 Google Cloud 액세스 토큰을 특정 Cloud Storage 버킷 또는 객체로 제한할 수도 있습니다. 사용자 인증 정보 액세스 경계는 Cloud Storage(storage.googleapis.com) 권한만 지원합니다. 다른 Google Cloud API 및 A2A 에이전트 호출의 경우 인증 관리자 바인딩, IAM 허용 및 거부 정책이 있는 최소 권한 에이전트 ID 또는 Agent Gateway를 통해 액세스 범위를 지정합니다.

이러한 옵션이 사용 사례에 적합하지 않고 조정자 에이전트가 서비스 계정으로 인증하는 경우 서비스 계정 가장을 사용하여 특정 태스크에 필요한 역할만 있는 전용 서비스 계정의 단기 토큰을 요청할 수도 있습니다.

바인딩을 사용하여 OAuth 토큰 범위 지정

2-legged 또는 3-legged OAuth 2.0을 사용하는 서드 파티 또는 SaaS A2A 에이전트를 호출할 때는 인증 관리자에서 인증 제공업체를 만들고 원격 에이전트에 필요한 OAuth scopes만 나열하는 에이전트 레지스트리에 Binding 리소스를 연결합니다. 에이전트 개발 키트(ADK)가 get_remote_a2a_agent()를 사용하여 원격 에이전트를 검색하면 해당 바인딩의 범위로 제한된 토큰을 요청합니다. 설정 단계는 도구 및 리소스에 인증 및 바인딩 관리를 참조하세요.

Cloud Storage 토큰 제한

오케스트레이터 에이전트가 Cloud Storage 데이터를 읽거나 쓰는 에이전트 또는 도구에 OAuth 2.0 액세스 토큰을 전달하는 경우 토큰의 권한을 줄여 특정 버킷 또는 객체 프리픽스에 대한 액세스만 허용할 수 있습니다. 요청을 보내기 전에 Security Token Service를 사용하여 사용자 인증 정보 액세스 경계를 적용합니다.

import google.auth
from google.auth import downscoped
from google.auth.transport.requests import Request

source_creds, _ = google.auth.default(
    scopes=["https://www.googleapis.com/auth/cloud-platform"]
)

access_boundary_rule = downscoped.AccessBoundaryRule(
    available_resource=(
        "//storage.googleapis.com/projects/_/buckets/BUCKET_NAME"
    ),
    available_permissions=["inRole:roles/storage.objectViewer"],
)
cab = downscoped.CredentialAccessBoundary(rules=[access_boundary_rule])

downscoped_creds = downscoped.Credentials(
    source_credentials=source_creds,
    credential_access_boundary=cab,
)
downscoped_creds.refresh(Request())

BUCKET_NAME을 원격 에이전트가 읽을 수 있는 Cloud Storage 버킷 이름으로 바꿉니다.

추가 보안 제어

사용자 인증 정보 범위 지정을 네트워크 정책 및 프롬프트 검사와 결합할 수 있습니다.

  • 네트워크 액세스 정책: Agent Gateway를 통해 A2A 호출을 라우팅하여 등록된 Agent 리소스에 IAP(Identity-Aware Proxy) 통합 액세스 정책(UAP)을 적용합니다.
  • 프롬프트 및 대답 검사: Agent Gateway와 Model Armor 통합 및 서비스 확장 프로그램 바인딩을 구성하여 지원되는 A2A 프롬프트 및 대답에서 프롬프트 인젝션 및 민감한 정보 노출을 검사합니다.

다음 단계