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

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를 사용하여 API Google Cloud , 다른 에이전트 또는 도구와 통신할 때 에이전트를 안전하게 인증할 수 있습니다.

API에 인증 Google Cloud

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

에이전트의 주 구성원에 적절한 IAM 역할을 부여합니다. 예를 들면 다음과 같습니다.
- Vertex AI에 대한 액세스 권한 부여:
```
gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="AGENT_PRINCIPAL" \
    --role="roles/aiplatform.user"
```
- 다른 API에 대한 액세스 권한 부여 Google Cloud :
  
  타겟 리소스에 필요한 역할을 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입니다.
에이전트 애플리케이션 코드에서 표준 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 토큰을 사용하여 인증합니다.

호출자 에이전트의 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를 사용하여 토큰과 워크로드의 인증서 간에 암호화 바인딩을 제공합니다. 바인딩된 토큰을 사용하려면 호출 클라이언트가 요청에 리프 인증서 체인을 제공해야 합니다.

바인딩되지 않은 ID 토큰 가져오기

호출 에이전트 컨테이너 내에서 대상 서비스의 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)로 바꿉니다.
Authorization 헤더의 토큰으로 대상 서비스에 요청을 보냅니다.
```
curl -H "Authorization: Bearer $TOKEN" \
  TARGET_SERVICE_URL/endpoint
```

바인딩된 ID 토큰 가져오기 (mTLS)

호출 에이전트 컨테이너 내에서 리프 인증서 체인을 읽고 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")

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 인증 관리자를 구성합니다.

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