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

상담사의 자체 ID를 사용하여 Google Cloud에 인증

에이전트는 자체 ID를 사용하여 Google Cloud API 및 기타 리소스에 액세스할 수 있습니다. Google은 다른 Google Cloud 서비스와 상호작용하기 위해 Google Cloud 에 호스팅된 에이전트에 이 방법을 사용하는 것이 좋습니다.

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

Google Cloud

시작하기 전에

필요한 역할

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

에이전트에 액세스 권한을 부여하려면 다음 안내를 따르세요.
- 프로젝트 IAM 관리자 (roles/resourcemanager.projectIamAdmin)
- 보안 관리자 (roles/iam.securityAdmin)
에이전트 ID에 권장되는 역할:
- 에이전트 컨텍스트 편집자 (roles/aiplatform.agentContextEditor)
- 에이전트 기본 액세스 (roles/aiplatform.agentDefaultAccess)
- Vertex AI 사용자 (roles/aiplatform.user)
- 서비스 사용량 소비자 (roles/serviceusage.serviceUsageConsumer)
- 브라우저 (roles/browser)
- 스토리지 객체 뷰어 (roles/storage.objectViewer)

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

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

에이전트에 액세스 권한 부여

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

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

에이전트에 리소스 액세스 권한을 부여하려면 Google Cloud 콘솔 또는 gcloud CLI를 사용하세요.

콘솔

콘솔 Google Cloud 에서 액세스 권한을 부여할 리소스 의 IAM 페이지로 이동합니다.
- 프로젝트의 경우 IAM 페이지로 이동합니다.
  IAM 페이지로 이동
- 다른 리소스의 경우 해당 리소스의 페이지로 이동하여 권한 또는 IAM 탭을 클릭합니다.
액세스 권한 부여 를 클릭합니다.
새 주 구성원 필드에 부여할 액세스 수준과 일치하는 주 구성원 식별자를 입력합니다.
- 단일 에이전트: 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/*
역할 선택 필드에서 부여할 역할을 검색하여 선택합니다.
저장 을 클릭합니다.

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)를 사용하여 에이전트 아이덴티티 사용자 인증 정보를 수동으로 사용하여 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)을 적용합니다. 또한 이 정책은 Agent Gateway에 액세스하기 위해 상호 TLS (mTLS)를 요구합니다. 이 요구사항은 Cloud Run 컨테이너 또는 Google Kubernetes Engine (GKE) 포드와 같은 의도된 신뢰할 수 있는 런타임 환경만 인증서 바인딩 토큰을 사용할 수 있도록 합니다. 이 보안 기준은 도난당한 사용자 인증 정보를 재생할 수 없도록 하여 사용자 인증 정보 도용 및 계정 탈취 (ATO)를 방지하는 데 도움이 됩니다.

인증서 바인딩은 다음 두 가지 유형의 에이전트 사용자 인증 정보를 보호하는 데 도움이 됩니다.

Google Cloud 액세스 토큰: API 및 기타 리소스 (*.googleapis.com)에 대한 요청을 인증하는 수명이 짧은 OAuth 2.0 액세스 토큰입니다. Google Cloud
OpenID Connect (OIDC) ID 토큰: 외부 서비스 및 Cloud Run (*.mtls.run.app) 또는 GKE와 같은 런타임에 호스팅된 Google Cloud 도구 및 서비스에 대한 요청을 인증하는 JSON 웹 토큰 (JWT)입니다.

모든 액세스 및 ID 토큰의 바인딩 선택 해제

런타임 환경 전반에서 기본 컨텍스트 인식 액세스 정책 및 인증서 바인딩 토큰을 선택 해제하는 것은 권장되지 않습니다. GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN=false를 설정하면 토큰 바인딩 보호 가 삭제되어 액세스 토큰과 OIDC ID 토큰 모두 Google Cloud 에 대해 수명이 짧은 토큰이 도용 또는 재생 공격에 취약해집니다.

하지만 다음과 같은 드문 경우에 런타임 환경 전반에서 선택 해제할 수 있습니다.

에이전트 간에 특정 토큰 공유 요구사항이 있습니다.
토큰을 요청 헤더에 직접 삽입해야 합니다.
에이전트가 인증할 수 없고 401 UNAUTHENTICATED 오류를 반환합니다.

런타임 환경 전반에서 선택 해제하려면 에이전트를 배포할 때 다음 환경 변수를 설정합니다.

config={
  "env_vars": {
    "GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN": "false",
  }
}

개별 ID 토큰 요청 선택 해제

기본적으로 지원되는 Google Auth 클라이언트 라이브러리는 토큰의 cnf (x5t#S256) 클레임에 인증서 지문을 포함하여 OIDC ID 토큰을 에이전트의 고유한 X.509 인증서에 암호화 방식으로 바인딩합니다.

Cloud Run과 같은 일부 서비스는 cnf 클레임이 있는 경우 인증서 바인딩을 적용합니다. 에이전트가 표준 *.run.app URL과 같은 비 mTLS 엔드포인트를 통해 이러한 서비스를 호출하거나 대상 엔드포인트에 인증서 바인딩이 필요하지 않은 경우 개별 ID 토큰 요청을 선택 해제할 수 있습니다. 이 설정은 해당 요청에만 영향을 미치며 Google Cloud 액세스 토큰의 인증서 바인딩을 사용 중지하지 않습니다.

Python

Python google-auth 라이브러리(2.61.0 이상(GKE) 및 2.62.0 이상(Cloud Run))에서 bind_id_token=False를 설정합니다.

from google.auth.transport.requests import AuthorizedSession
from google.auth.transport.requests import Request
from google.oauth2 import id_token

target_audience = "https://TARGET_SERVICE_URL"

# Option 1: Use AuthorizedSession with IDTokenCredentials
credentials = id_token.fetch_id_token_credentials(
    audience=target_audience,
    bind_id_token=False,
)
authed_session = AuthorizedSession(credentials)
response = authed_session.get(target_audience)

# Option 2: Fetch a raw ID token directly
token = id_token.fetch_id_token(
    Request(),
    audience=target_audience,
    bind_id_token=False,
)

TARGET_SERVICE_URL을 에이전트가 호출하는 수신 서비스의 대상 URI 또는 URL로 바꿉니다.

에이전트 배포

에이전트를 Google Cloud배포할 때는 에이전트 ID가 사용 설정되어 있는지 확인합니다. Gemini Enterprise Agent Platform의 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]"],
    },
)