AI 에이전트 인증

Cloud Run에 에이전트를 배포할 때 API 및 기타 에이전트와 통신할 때 안전하게 인증할 수 있는 ID를 부여할 수 있습니다.

Google Cloud API, 기타 에이전트, 도구에 인증

Cloud Run 워크로드가 agent-identity ID 유형으로 구성되면 다음과 같은 형식의 시스템 관리 ID가 수신됩니다.

principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/run/projects/PROJECT_NUMBER/locations/REGION/services/SERVICE_NAME

조직이 없는 프로젝트의 경우 형식은 프로젝트 번호를 사용합니다.

principal://agents.global.project-PROJECT_NUMBER.system.id.goog/resources/run/projects/PROJECT_NUMBER/locations/REGION/services/SERVICE_NAME

이 ID를 사용하여 Google Cloud API, 다른 에이전트 또는 도구와 통신할 때 에이전트를 안전하게 인증할 수 있습니다.

Google Cloud API에 인증

에이전트는 할당된 에이전트 ID를 사용하여 Cloud Run 메타데이터 서버에서 가져온 액세스 토큰을 통해 Vertex AI, Cloud Storage, 기타Google Cloud 제품과 같은Google Cloud API에 인증할 수 있습니다.

  1. 에이전트의 주 구성원에 적절한 IAM 역할을 부여합니다. 예를 들면 다음과 같습니다.

    • Vertex AI 액세스 권한 부여:

      gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="AGENT_PRINCIPAL" \
    --role="roles/aiplatform.user"

    • 다른 Google Cloud API에 대한 액세스 권한 부여:

      타겟 리소스에 필요한 역할을 AGENT_PRINCIPAL에 부여합니다(예: Cloud Storage 버킷의 roles/storage.objectViewer). 자세한 내용은 애플리케이션 기본 사용자 인증 정보로 인증을 참고하세요.

    다음을 바꿉니다.

    • PROJECT_ID: Google Cloud 프로젝트 ID입니다.
    • AGENT_PRINCIPAL: 에이전트의 ID입니다(예: principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/run/projects/PROJECT_NUMBER/locations/REGION/services/AGENT_NAME).

  2. 에이전트 애플리케이션 코드에서 표준 Google Cloud 클라이언트 라이브러리를 사용합니다. 클라이언트 라이브러리는 애플리케이션 기본 사용자 인증 정보 (ADC)를 사용하여 메타데이터 서버에서 단기 액세스 토큰을 자동으로 가져옵니다.

    또는 컨테이너 내의 메타데이터 서버에서 액세스 토큰을 수동으로 가져올 수 있습니다.

    curl -s -H "Metadata-Flavor: Google" \
"http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token"

Cloud Run의 다른 에이전트에 인증

에이전트가 Cloud Run에서 호스팅되는 다른 에이전트(예: A2A 에이전트)를 호출해야 하는 경우 Cloud Run의 기본 roles/run.invoker IAM 검사로 검증된 JSON 웹 토큰(JWT) ID 토큰을 사용하여 인증합니다.

  1. 호출자 에이전트의 ID에 타겟 Cloud Run 서비스에 대한 roles/run.invoker 역할을 부여합니다.

    gcloud run services add-iam-policy-binding TARGET_SERVICE_NAME \
    --member="CALLER_AGENT_PRINCIPAL" \
    --role="roles/run.invoker" \
    --region=REGION

    다음을 바꿉니다.

    • TARGET_SERVICE_NAME: 대상 Cloud Run 에이전트 서비스의 이름입니다.
    • CALLER_AGENT_PRINCIPAL: 호출 에이전트의 ID입니다.
    • REGION: 대상 서비스의 Google Cloud 리전

토큰 검증 옵션

Cloud Run은 두 가지 ID 토큰 검증 방법을 지원합니다.

  • 바인딩되지 않은 토큰: 메타데이터 서버에서 생성된 표준 잠재고객 바인딩 ID 토큰입니다. 이는 서비스 간 및 에이전트 간 인증의 기본 메커니즘입니다.

  • 바운드 토큰: mTLS를 사용하여 토큰과 워크로드의 인증서 간에 암호화 바인딩을 제공합니다. 바운드 토큰을 사용하려면 호출 클라이언트가 요청에 리프 인증서 체인을 제공합니다.

    mTLS 바인딩 토큰을 사용하여 ingress=internal로 구성된 Cloud Run 리소스를 호출할 수 있습니다. 이렇게 하면 VPC 네트워크 없이 에이전트 또는 MCP 서버에 대한 공개 인터넷 액세스를 제한할 수 있습니다.

바인드되지 않은 ID 토큰 가져오기
  1. 호출 에이전트 컨테이너 내에서 대상 서비스의 URL을 대상으로 사용하여 ID 토큰을 가져옵니다. 
    TOKEN=$(curl -s -H "Metadata-Flavor: Google" \
  "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience=TARGET_SERVICE_URL")
     TARGET_SERVICE_URL을 대상 Cloud Run 서비스의 URL(예: https://target-agent-1234567890.us-central1.run.app)로 바꿉니다.
  2. Authorization 헤더에 토큰을 포함하여 타겟 서비스에 요청을 보냅니다. 
    curl -H "Authorization: Bearer $TOKEN" \
  TARGET_SERVICE_URL/endpoint
바인딩된 ID 토큰 가져오기 (mTLS)
  1. 호출 에이전트 컨테이너 내에서 리프 인증서 체인을 읽고 POST 요청을 사용하여 메타데이터 서버에서 바운드 토큰을 요청합니다. 
    CERT_PATH="/var/run/secrets/workload-spiffe-credentials/certificates.pem"
JSON_PAYLOAD=$(jq -n --arg certs "$(cat $CERT_PATH)" '{"certificate_chain": $certs}')

TOKEN=$(curl -s -X POST \
    -H "Metadata-Flavor: Google" \
    -H "Content-Type: application/json" \
    -d "$JSON_PAYLOAD" \
  "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience=TARGET_SERVICE_MTLS_URL")
  2. TLS 핸드셰이크 중에 워크로드 인증서를 표시하여 타겟 서비스의 mTLS 엔드포인트를 호출합니다. 
    KEY_PATH="/var/run/secrets/workload-spiffe-credentials/private_key.pem"

curl --cert $CERT_PATH \
    --key $KEY_PATH \
    -H "Authorization: Bearer $TOKEN" \
  TARGET_SERVICE_MTLS_URL/endpoint
Python 예시

Python 기반 에이전트 코드를 작성하는 경우 인증서가 있으면 표준 Google Cloud 클라이언트 라이브러리는 기본적으로 바인딩된 토큰을 자동으로 요청합니다. 수동 HTTP 요청을 해야 하는 경우 다음 단계를 따르세요.

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

# Target agent's mTLS URL
target_mtls_url = "TARGET_SERVICE_MTLS_URL"

# 1. Fetch the ID token.
# google-auth automatically requests a bound ID token via POST because
# the platform configures the workload certificate environment variables.
auth_req = Request()
token = id_token.fetch_id_token(auth_req, target_mtls_url)

# 2. Make the HTTP call over mTLS, presenting the workload certificates.
cert_path = "/var/run/secrets/workload-spiffe-credentials/certificates.pem"
key_path = "/var/run/secrets/workload-spiffe-credentials/private_key.pem"

response = requests.get(
    target_mtls_url,
    headers={"Authorization": f"Bearer {token}"},
    cert=(cert_path, key_path)
)
print(response.text)

TARGET_SERVICE_MTLS_URL을 대상 Cloud Run 서비스의 mTLS URL(예: https://target-agent-12345.us-central1.mtls.run.app)로 바꿉니다.

Cloud Run의 MCP 서버 인증

Cloud Run에서 호스팅되는 MCP 서버 또는 도구에 연결하려면 --functional-type=mcp-server 식별자를 사용하여 Agent Registry에서 MCP 서버의 자동 등록을 사용 설정하세요.

MCP 서버가 Cloud Run에서 실행되는 다른 에이전트에 의해서만 액세스되는 경우 기본 제공 IAM 호출자 확인을 사용합니다. 상담사가 표준 실행 호출자 정책을 사용하여 기본적으로 통신하도록 허용합니다.

gcloud run services add-iam-policy-binding MCP_SERVICE_NAME \
    --member="CALLING_AGENT_PRINCIPAL" \
    --role="roles/run.invoker" \
    --region=REGION

다음을 바꿉니다.

  • MCP_SERVICE_NAME: MCP 서버를 호스팅하는 대상 Cloud Run 서비스의 이름입니다.
  • CALLING_AGENT_PRINCIPAL: MCP 서버를 호출하는 에이전트의 주 구성원 ID입니다. 예를 들면 serviceAccount:my-agent@my-project.iam.iam.gserviceaccount.com입니다.
  • REGION: MCP 서버가 배포된 Google Cloud 리전입니다.

run.invoker 역할을 부여한 후 호출 에이전트는 토큰 검증 옵션 섹션에 설명된 대로 ID 토큰을 가져올 수 있습니다.

CLI 및 프로그래매틱 SDK 액세스를 위한 IAP로 MCP 서버를 보호하는 방법을 알아보려면 MCP 서버 인증을 참고하세요.

사용자를 대신하여 인증

에이전트가 사용자를 대신하여 외부 도구 및 서비스에 액세스하는 경우 프로비저닝된 에이전트 ID를 사용하여 MCP 서버 및 외부 엔드포인트와의 인증을 관리할 수 있습니다.

3단계 OAuth(3LO) 동의, 2단계 OAuth (2LO), API 키와 같은 복잡한 승인 워크플로를 안전하게 처리하려면 에이전트 ID 인증 관리자를 구성하세요.

이러한 인증 관리자를 도구 모음에 바인딩하는 방법은 도구 및 리소스에 인증을 참고하세요.