에이전트 자체 권한을 사용하여 인증

에이전트는 자체 권한을 사용하여 Google Cloud API 및 기타 리소스에 액세스할 수 있습니다. Google Cloud에서 호스팅되는 에이전트가 다른 Google Cloud 서비스와 상호작용하는 데 이 방법을 사용하는 것이 좋습니다.

에이전트가 자체 권한으로 작동하는 경우 기본 SPIFFE ID를 사용하여 Google Cloud 액세스 토큰을 요청합니다.

시작하기 전에

  1. 올바른 인증 방법을 선택했는지 확인합니다.
  2. 에이전트 ID가 사용 설정된 에이전트를 만들고 배포합니다.
  3. 이 작업을 완료하는 데 필요한 역할이 있는지 확인합니다.

필요한 역할

에이전트가 Google Cloud 서비스에 액세스할 수 있는 권한을 부여하는 데 필요한 권한을 얻으려면 관리자에게 대상 리소스에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.

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

커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.

상담사에게 액세스 권한 부여

에이전트가 Google Cloud 서비스에 액세스하도록 허용하려면 대상 리소스에 대한 필수 역할을 에이전트의 ID에 부여해야 합니다.

IAM 허용 정책에서 에이전트 ID는 주 구성원 식별자를 사용합니다.

에이전트가 리소스에 액세스할 수 있도록 하려면 Google Cloud 콘솔 또는 gcloud CLI를 사용하세요.

콘솔

  1. Google Cloud 콘솔에서 액세스 권한을 부여할 리소스의 IAM 페이지로 이동합니다.
    • 프로젝트의 경우 IAM 페이지로 이동합니다.

      IAM 페이지로 이동

    • 다른 리소스의 경우 해당 리소스의 페이지로 이동하여 권한 또는 IAM 탭을 클릭합니다.
  2. 액세스 권한 부여를 클릭합니다.
  3. 새 주 구성원 필드에 부여할 액세스 수준과 일치하는 주 구성원 식별자를 입력합니다.
    • 단일 에이전트: principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID
    • 프로젝트의 모든 상담사: principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER
    • 조직의 모든 상담사: principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/*
  4. 역할 선택 필드에서 부여할 역할을 검색하여 선택합니다.
  5. 저장을 클릭합니다.

Google Cloud CLI

에이전트가 리소스에 액세스할 수 있도록 허용하려면 다음 명령어를 실행합니다. 
gcloud SERVICE add-iam-policy-binding RESOURCE_NAME \
    --member="PRINCIPAL_IDENTIFIER" \
    --role="ROLE"

다음을 바꿉니다.

  • SERVICE: Google Cloud 서비스 (예: storage 또는 bigquery)
  • RESOURCE_NAME: 리소스의 이름입니다 (예: 버킷 이름 또는 데이터 세트 ID).
  • PRINCIPAL_IDENTIFIER: 부여하려는 액세스 수준과 일치하는 주 구성원 식별자입니다.
    • 단일 상담사: principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID
    • 프로젝트의 모든 상담사: principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER
    • 조직의 모든 상담사: principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/*
  • ORGANIZATION_ID: Google Cloud 조직 ID입니다.
  • PROJECT_NUMBER: Google Cloud 프로젝트 번호.
  • LOCATION: 에이전트의 위치입니다(예: us-central1). 단일 에이전트 액세스에만 필요합니다.
  • ENGINE_ID: 추론 엔진의 ID입니다. (단일 상담사 액세스에만 필요)
  • ROLE: 부여할 IAM 역할입니다.

코드에서 에이전트 ID 참조

Google Cloud 클라이언트 라이브러리는 에이전트가 지원되는 Google Cloud 환경에 배포되면 에이전트 ID를 자동으로 사용합니다.

다음 Python 스니펫은 에이전트 개발 키트 (ADK)를 사용하여 에이전트 ID 사용자 인증 정보를 수동으로 사용하여 Cloud Vision API를 호출하는 방법을 보여줍니다.

from google.cloud import vision
from google.auth import default
from google.adk.tools import tool

@tool
def analyze_image_from_gcs(gcs_uri: str) -> dict:
    # Application default credentials automatically retrieve the
    # Agent Identity token from the metadata server.
    agent_identity_credentials, project_id = default()

    client = vision.ImageAnnotatorClient(
        credentials=agent_identity_credentials,
        project=project_id
    )

    # Prepare the image object with the Cloud Storage URI.
    image = vision.Image()
    image.source.image_uri = gcs_uri

    # Perform label detection on the image.
    response = client.label_detection(image=image)

    # Check for any errors returned by the API.
    if response.error.message:
        return {"status": "failure", "error_message": response.error.message}

    labels = response.label_annotations
    return {"status": "success", "labels": [label.description for label in labels]}

선택사항: 컨텍스트 인식 액세스 선택 해제하기

기본 Google 관리 컨텍스트 인식 액세스 정책은 에이전트 ID 사용자 인증 정보를 보호하는 데 도움이 됩니다. 에이전트 게이트웨이 외에도 정책은 에이전트의 액세스 토큰을 인증하여 입증 가능한 소유 증명 (DPoP)을 시행합니다. 또한 이 정책은 mTLS를 사용하여 에이전트 게이트웨이에 액세스하도록 강제합니다. 이렇게 하면 인증서 바인딩 토큰이 의도된 신뢰할 수 있는 런타임 환경 (예: Cloud Run 컨테이너)에서만 사용될 수 있습니다. 이 보안 기준을 통해 도난된 사용자 인증 정보가 재생되지 않으므로 사용자 인증 정보 도용 및 계정 탈취 (ATO)를 방지할 수 있습니다.

상담사 간의 특정 토큰 공유 요구사항과 같은 드문 경우에 헤더에 토큰을 직접 삽입해야 하거나 상담사가 401 UNAUTHENTICATED 오류로 인증할 수 없는 경우 기본 컨텍스트 인식 액세스 정책을 선택 해제할 수 있습니다. 선택 해제하면 토큰 바인딩 보호가 삭제되어 이러한 단기 액세스 토큰이 도난이나 재사용 공격에 취약해집니다. 따라서 선택 해제는 권장되지 않습니다.

선택 해제하려면 에이전트를 배포할 때 다음 환경 변수를 설정하세요.

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

에이전트 배포

에이전트를 Google Cloud에 배포할 때는 에이전트 ID가 사용 설정되어 있어야 합니다. Agent Runtime에 배포하는 경우 identity_type=AGENT_IDENTITY 플래그를 사용합니다.

import vertexai
from vertexai import types
from vertexai.agent_engines import AdkApp

# Initialize the Vertex AI client with v1beta1 API for Agent Identity support
client = vertexai.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options=dict(api_version="v1beta1")
)

# Use the proper wrapper class for your Agent Framework (e.g., AdkApp)
app = AdkApp(agent=agent)

# Deploy the agent with Agent Identity enabled
remote_app = client.agent_engines.create(
    agent=app,
    config={
        "identity_type": types.IdentityType.AGENT_IDENTITY,
        "requirements": ["google-cloud-aiplatform[agent_engines,adk]"],
    },
)

다음 단계