1. 소개
광범위한 권한이 있는 자체 사용자 인증 정보가 있는 에이전트는 모든 사용자의 데이터를 볼 수 있습니다. 이 Codelab에서는 로그인한 사용자의 사용자 인증 정보로 서드 파티 API를 호출하는 에이전트를 빌드하여 해당 사용자가 볼 수 있는 것만 정확하게 볼 수 있도록 합니다.
Google 에이전트 개발 키트 (ADK)와 Gemini Enterprise를 사용하여 빌드합니다.
특히 다음과 같은 이중 ID 아키텍처를 설계하는 방법을 알아봅니다.
- 에이전트가 자체적으로 작동 (에이전트 아이덴티티): SPIFFE 지원 에이전트 아이덴티티를 사용하여 에이전트가 Auth Manager를 호출하고, 원격 분석을 저장하고, Google Cloud API를 호출합니다.
- 에이전트가 사용자를 대신하여 작업 (사용자 위임 ID): GitHub와 같은 외부 리소스에 액세스하기 위해 에이전트는 3-legged OAuth (3LO) 동의 흐름을 트리거하여 사용자의 사용자 인증 정보를 사용해 도구를 안전하게 쿼리합니다.

이를 위해 다음을 수행하는 방법을 알아봅니다.
- GitHub의 모델 컨텍스트 프로토콜 (MCP) 서버에 연결하는 ADK 에이전트를 빌드합니다.
- Google Cloud Auth Manager를 사용하여 에이전트의 도구를 정적 GitHub PAT (개인 액세스 토큰)에서 3-legged OAuth (3LO) 흐름으로 업데이트합니다.
- 에이전트를 Agent Runtime에 안전하게 배포하고 에이전트 ID를 프로비저닝합니다.
- 사용자를 대신하여 에이전트의 ID에 토큰 저장소에 대한 액세스 권한을 제공하도록 IAM 역할을 구성합니다.
- Google Cloud에서 인증 관리자의 엔드 투 엔드 3LO 흐름을 이해합니다.
기본 요건
시작하기 전에 다음 사항을 확인하세요.
- 결제가 사용 설정된 Google Cloud 프로젝트
- 로컬 머신에서 프로젝트에 설치되고 인증된 Google Cloud SDK (
gcloudCLI) 버전 586.0.0 이상이 필요합니다.gcloud components update를 실행하세요. - Python 3.10~3.13이 로컬에 설치되어 있어야 합니다.
uv패키지 관리자가 설치되어 있습니다 (pip install uv).- OAuth 애플리케이션을 등록하고 토큰을 만들기 위한 GitHub 계정 GitHub 계정이 없는 경우 3-legged OAuth 2.0을 지원하는 서드 파티 MCP 서버로 대체할 수 있습니다.
2. 프로젝트 설정
1. Google Cloud에 인증
로컬 명령줄에서 Google Cloud에 인증하여 이 실습 중에 Agent Runtime에 배포하고, Agent Identity를 프로비저닝하고, Auth Manager를 구성하는 데 필요한 권한이 환경에 있는지 확인합니다.
다음 명령어를 실행하여 Google Cloud 계정에 로그인하고, 활성 프로젝트를 설정하고(YOUR_PROJECT_ID를 Google Cloud 프로젝트 ID로 바꿈), 애플리케이션 기본 사용자 인증 정보 (ADC)를 구성합니다.
gcloud auth login
gcloud config set project YOUR_PROJECT_ID
gcloud auth application-default login
2. 필수 Google Cloud 서비스 사용 설정
이 실습을 실행하려면 Google Cloud 프로젝트에서 필요한 API를 사용 설정합니다. 터미널에서 다음 명령어를 실행합니다.
gcloud services enable \
agentidentity.googleapis.com \
agentregistry.googleapis.com \
aiplatform.googleapis.com \
apphub.googleapis.com
이 명령어를 실행하는 데 1분 정도 걸릴 수 있습니다. 완료되면 API가 활성 상태임을 확인하는 명령 프롬프트로 돌아갑니다.
3. Agents CLI 설치 및 프로젝트 설정
agents-cli는 ADK 에이전트를 스캐폴딩, 관리, 테스트하고 Gemini Enterprise에 배포하는 데 사용되는 명령줄 도구입니다. 로컬에 설치합니다.
uvx google-agents-cli setup
설치를 확인합니다.
agents-cli --help
사용 가능한 명령어 (예: deploy, run, status)를 표시하는 CLI의 도움말 메뉴가 표시됩니다.
초기 프로젝트 스캐폴딩을 생성합니다. 로컬 프로토타입으로 시작하여 나중에 Agent Runtime 배포를 위해 개선합니다.
agents-cli create secure-agent-demo --prototype --yes
이렇게 하면 기본 에이전트 코드, 종속 항목, 테스트 파일이 포함된 secure-agent-demo 디렉터리가 생성됩니다.
4. 필수 ADK 추가 항목 추가
생성된 pyproject.toml에 누락된 두 가지 추가 항목을 추가합니다. GitHub 도구 모음의 경우 mcp, 실습 후반부에서 사용되는 인증 관리자의 경우 agent-identity입니다. secure-agent-demo/pyproject.toml를 열고 전체
google-adk
종속 항목 줄을 다음으로 바꿉니다.
"google-adk[agent-identity,gcp,mcp,otel-gcp]>=2.5.0,<3.0.0",
그런 다음 설치합니다.
cd secure-agent-demo
agents-cli install
3. 에이전트 빌드 및 테스트
1. 에이전트 만들기
프로젝트 내에서 secure-agent-demo/app/agent.py의 코드를 다음으로 바꿉니다.
# app/agent.py
from google.adk.agents import Agent
from google.adk.apps import App
from google.adk.models import Gemini
from google.genai import types
from app.tools import github_toolset
import os
import google.auth
_, project_id = google.auth.default()
os.environ["GOOGLE_CLOUD_PROJECT"] = project_id
os.environ["GOOGLE_CLOUD_LOCATION"] = "global"
os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "True"
INSTRUCTION = """You are the DevOps Assistant. You help developers list and triage their GitHub issues and pull requests.
Your capabilities: You have a GitHub MCP toolset that you can use to perform actions that the user requests.
Rules:
- NEVER write, update, or delete. You are only allowed read access.
- Act on behalf of the signed-in user.
- If a tool returns an authentication or authorization error, guide the user to sign in.
- NEVER fabricate information. Only report real issues returned by tools.
"""
root_agent = Agent(
name="root_agent",
model=Gemini(
model="gemini-3.8-flash",
retry_options=types.HttpRetryOptions(attempts=3),
),
instruction=INSTRUCTION,
tools=[github_toolset()],
)
app = App(
root_agent=root_agent,
name="app",
)
이 파일은 에이전트의 세 가지 핵심 구성요소를 정의합니다.
- 시스템 요청 사항 (
INSTRUCTION): 퍼소나를 설정하고, 어시스턴트의 범위를 GitHub 분류로 지정하고, 엄격한 안전 규칙 (예: 읽기 전용 액세스, 오류 발생 시 사용자에게 인증 안내)을 적용합니다. - 에이전트 구성 (
root_agent):gemini-3.8-flash모델을 사용하여 ADKAgent를 인스턴스화하고, HTTP 재시도 로직을 구성하고, 에이전트에 GitHub 도구 모음을 제공합니다. - 앱 래퍼 (
app): 루트 에이전트를 ADKApp컨테이너로 캡슐화하여 Agent Runtime에 배포할 수 있도록 합니다.
2. GitHub MCP 도구 추가
에이전트는 모델 컨텍스트 프로토콜 (MCP)을 사용하여 GitHub에 연결합니다. secure-agent-demo/app/tools.py에서 새 파일을 만들어 MCP 게이트웨이 연결 매개변수를 등록합니다. 다음 코드를 복사하여 붙여넣습니다.
# app/tools.py
from __future__ import annotations
import os
from google.adk.tools.mcp_tool import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams
GITHUB_MCP_URL = "https://api.githubcopilot.com/mcp/"
GITHUB_TOKEN = os.environ.get("GITHUB_TOKEN", "")
def github_toolset() -> McpToolset:
"""Returns the McpToolset connecting to the public GitHub Copilot MCP gateway."""
return McpToolset(
connection_params=StreamableHTTPConnectionParams(
url=GITHUB_MCP_URL,
headers={
"Authorization": f"Bearer {GITHUB_TOKEN}",
"X-MCP-Toolsets": "all",
"X-MCP-Readonly": "true",
},
)
)
이 함수는 GitHub의 MCP 서버를 호출하는 도구를 만듭니다.
- MCP 도구 모음 (
McpToolset): GitHub 기능을 동적으로 검색하고 호출 가능한 에이전트 도구로 등록합니다. - 연결 매개변수 (
StreamableHTTPConnectionParams): 도구 모음이 GitHub의 공개 MCP 게이트웨이를 가리키도록 합니다. - 승인 헤더:
GITHUB_TOKEN를 Bearer 토큰으로 삽입하고 전송 계층에서 직접 읽기 전용 모드 (X-MCP-Readonly: true)를 적용합니다.
3. GitHub PAT (개인 액세스 토큰)를 사용하여 로컬에서 테스트
정적 사용자 인증 정보로 에이전트를 로컬에서 실행하려면 다음 안내를 따르세요.
- GitHub 개인 액세스 토큰 페이지에서 세분화된 개인 액세스 토큰을 만듭니다.
- Generate new token을 클릭하고 토큰 이름을 지정합니다.
- 저장소 액세스에서 모든 저장소를 선택하거나 테스트할 특정 저장소를 선택합니다.
- 권한 > 저장소에서 +권한 추가를 클릭하고 콘텐츠, 문제, pull 요청을 읽기 전용으로 선택합니다(메타데이터는 자동으로 읽기 전용으로 설정됨).
- 토큰 생성을 클릭하고 생성된 토큰 값을 복사합니다. (또는 개인 액세스 토큰 (기존)을 사용하는 경우
repo범위를 선택합니다.)
- 환경에서 설정합니다.
export GITHUB_TOKEN="your_github_pat_here" secure-agent-demo폴더로 이동하여 (아직 없는 경우) 로컬 플레이그라운드를 시작합니다.cd secure-agent-demo agents-cli playground- 플레이그라운드 인터페이스를 열고 드롭다운에서
app폴더를 선택합니다. 채팅 상자에서"Get the last 2 GitHub issues reported against my name"또는"List my 3 most recently updated repositories"와 같은 타겟팅된 프롬프트를 시도하고 에이전트가 GitHub MCP 도구 세트를 호출하고 GitHub 데이터를 반환하는지 확인합니다. 에이전트가 실제로 PAT 토큰을 사용하여 사용자를 대신해 작업을 수행하는지 테스트하려면 비공개 저장소나 기여에 대해 질문해 보세요.
4. 인증 관리자 구성
정적 사용자 인증 정보 (예: PAT)를 하드코딩하는 것은 프로토타입 제작에 편리하지만, 프로덕션 애플리케이션이 사용자 인증 정보 유출, 수동 토큰 새로고침 다운타임, 클라우드 네이티브 액세스 제어 부족에 노출됩니다.
이를 해결하기 위해 Google Cloud는 에이전트 아이덴티티 인증 관리자를 제공합니다. 에이전트 아이덴티티 인증 관리자는 사용자 인증 정보를 보호하도록 설계된 사용자 인증 정보 저장소입니다. 이를 통해 에이전트는 API 키 또는 OAuth 클라이언트 ID 및 보안 비밀번호를 사용하거나 최종 사용자 액세스 토큰을 사용하는 OAuth 위임을 통해 사용자를 대신하여 인증할 수 있습니다.
인증 관리자 내에서 특정 서드 파티 애플리케이션의 인증 유형과 사용자 인증 정보를 정의하는 인증 제공업체를 구성합니다. 인증 제공업체는 리전별로 다르며, 리전은 에이전트를 배포하는 리전과 일치해야 합니다. 엔드 투 엔드 인증 관리자 워크플로는 다음과 같이 작동합니다.

- 동적 동의 가로채기: 에이전트가 사용자를 대신하여 도구를 실행하려고 하면 ADK는 인증 관리자에서 기존의 유효한 사용자 인증 정보를 확인합니다. 없으면 인증 관리자가 승인 URL을 반환하여 3LO (3-legged OAuth) 동의 흐름을 시작합니다.
- 보안 Vault 저장소: 최종 사용자가 애플리케이션을 승인하면 Auth Manager가 자동으로 OAuth 콜백을 가로채고 결과 사용자 액세스 및 갱신 토큰을 Google에서 관리하는 보안 사용자 인증 정보 Vault에 저장합니다.
- 자동화된 토큰 수명 주기: Auth Manager는 백그라운드에서 토큰 만료 및 순환을 완전히 관리하므로 수동 토큰 새로고침 로직이나 다운타임이 필요하지 않습니다.
- 보안 비밀 없는 도구 실행: 후속 작업의 경우 에이전트 (SPIFFE 에이전트 아이덴티티를 통해 인증)가 런타임에 인증 관리자로부터 사용자의 위임된 액세스 토큰을 동적으로 요청하여 클라이언트와 에이전트 코드 모두에 보안 비밀이 없도록 유지합니다.
A단계: GitHub를 인증 제공업체로 구성
다음 gcloud 명령어를 실행하여 Google Cloud 프로젝트에서 GitHub 인증 제공업체를 만듭니다. 클라이언트 ID와 보안 비밀번호는 나중에 제공합니다. GitHub는 이 제공업체의 콜백 URL을 알기 전까지는 이를 발급하지 않습니다.
gcloud agent-identity auth-providers create github-oauth-provider \
--project="YOUR_PROJECT_ID" \
--location="us-central1" \
--three-legged-oauth-authorization-url="https://github.com/login/oauth/authorize" \
--three-legged-oauth-token-url="https://github.com/login/oauth/access_token"
생성된 OAuth 리디렉션 URL을 검색하도록 공급업체를 설명합니다.
gcloud agent-identity auth-providers describe github-oauth-provider \
--project="YOUR_PROJECT_ID" \
--location="us-central1"
필드는 redirectUrl이며 authProviderTypeParams.threeLeggedOauth 아래에 중첩되어 있습니다. 직접 읽으려면 다음 단계를 따르세요.
gcloud agent-identity auth-providers describe github-oauth-provider \
--project="YOUR_PROJECT_ID" --location="us-central1" \
--format="value(authProviderTypeParams.threeLeggedOauth.redirectUrl)"
https://agentidentitycredentials.googleapis.com/v1/projects/YOUR_PROJECT_ID/locations/us-central1/authProviders/github-oauth-provider/oauthcallback과 같이 표시됩니다.
B단계: GitHub에 OAuth 앱 등록
- GitHub 개발자 설정 페이지로 이동하여 왼쪽 사이드바에서 OAuth 앱을 선택하고 새 OAuth 앱을 클릭합니다(이전에 만든 적이 없는 경우 새 애플리케이션 등록).
- OAuth 애플리케이션 양식 입력란을 작성합니다.
- 애플리케이션 이름: 애플리케이션 이름을 입력합니다 (예:
secure-agent-demo). - 홈페이지 URL: 프런트엔드 애플리케이션의 URL을 입력합니다(로컬 프로토타입 제작의 경우
http://localhost:8501, 프로덕션에서 배포된 URL로 업데이트할 수 있음). - 애플리케이션 설명: 선택사항입니다 (비워 둘 수 있음).
- 승인 콜백 URL (리디렉션 URI): A단계에서 가져온
redirectUrl를 붙여넣습니다. - 기기 흐름 사용 설정: 선택하지 않은 상태로 둡니다.
- 애플리케이션 이름: 애플리케이션 이름을 입력합니다 (예:
- 애플리케이션 등록을 클릭합니다.
- 표시되는 애플리케이션 페이지에서 클라이언트 ID를 복사한 다음 새 클라이언트 보안 비밀번호 생성을 클릭하고 생성된 클라이언트 보안 비밀번호를 복사합니다. 두 값을 모두 저장합니다. 다음 단계에서
YOUR_GITHUB_CLIENT_ID및YOUR_GITHUB_CLIENT_SECRET로 사용합니다.
C단계: 인증 제공업체에 GitHub 사용자 인증 정보 추가
YOUR_PROJECT_ID, YOUR_GITHUB_CLIENT_ID, YOUR_GITHUB_CLIENT_SECRET을 원하는 값으로 바꾸고 다음 명령어를 실행합니다.
gcloud agent-identity auth-providers update github-oauth-provider \
--project="YOUR_PROJECT_ID" \
--location="us-central1" \
--three-legged-oauth-client-id="YOUR_GITHUB_CLIENT_ID" \
--three-legged-oauth-client-secret="YOUR_GITHUB_CLIENT_SECRET"
이 명령어는 clientId가 표시된 상태로 제공업체를 다시 에코합니다. 보안 비밀은 에코되지 않습니다.
👉 이 단계를 완료하면 Google Cloud Auth Manager가 GitHub OAuth 애플리케이션 사용자 인증 정보로 완전히 구성되어 Google Cloud가 동의 및 토큰 수명 주기를 처리하는 보안 저장소 역할을 하도록 설정됩니다.
5. PAT 토큰을 인증 관리자로 전환
이제 인증 관리자가 완전히 구성되었으므로 다음 단계는 에이전트의 도구 코드를 업데이트하는 것입니다. secure-agent-demo/app/tools.py의 내용을 다음 코드로 바꿉니다.
👉 아래 OAUTH_PROVIDER_NAME 변수에서 프로젝트 ID와 위치를 바꿉니다.
# app/tools.py
from __future__ import annotations
import os
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider, GcpAuthProviderScheme
from google.adk.tools.mcp_tool import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams
# 1. Register the GCP Auth Provider in the global Credential Manager
CredentialManager.register_auth_provider(GcpAuthProvider())
# 2. Replace YOUR_PROJECT_ID with your project ID.
OAUTH_PROVIDER_NAME = "projects/YOUR_PROJECT_ID/locations/us-central1/authProviders/github-oauth-provider"
# 3. The frontend callback URL where the user is redirected after authorizing GitHub. Resolved from the environment variable.
OAUTH_CONTINUE_URI = os.environ.get(
"OAUTH_CONTINUE_URI",
"http://localhost:8501/validateUserId"
)
def github_toolset() -> McpToolset:
"""Returns the McpToolset using 3LO credentials retrieved via GCP Auth Manager."""
auth_scheme = GcpAuthProviderScheme(
name=OAUTH_PROVIDER_NAME,
# Required to read private repositories. Auth Manager currently supports a
# single scope for GitHub.
scopes=["repo"],
continue_uri=OAUTH_CONTINUE_URI,
)
return McpToolset(
connection_params=StreamableHTTPConnectionParams(
url="https://api.githubcopilot.com/mcp/",
headers={
"X-MCP-Toolsets": "all",
"X-MCP-Readonly": "true",
},
),
auth_scheme=auth_scheme,
)
도구 코드 이해하기
주요 변경사항은 auth_scheme입니다. 도구 모음에 연결하면 에이전트가 GitHub를 호출할 때마다 ADK가 먼저 인증 관리자에게 해당 사용자의 토큰을 요청합니다. 토큰이 아직 없으면 실패하는 대신 사용자에게 로그인하라는 메시지를 표시합니다. 하드코딩된 GITHUB_TOKEN가 완전히 사라졌습니다.
6. Agent Runtime에 에이전트 배포
이제 GitHub MCP 도구를 업데이트하여 Auth Manager를 사용하도록 설정했으므로 다음 단계는 에이전트를 Agent Runtime에 배포하는 것입니다. 에이전트 아이덴티티를 사용 설정하여 배포하면 에이전트에 고유한 SPIFFE ID가 프로비저닝됩니다.
프로젝트의 배포 구성을 초기화합니다. 터미널이 secure-agent-demo 프로젝트 루트 디렉터리에 있는지 확인한 후 다음을 실행합니다.
agents-cli scaffold enhance . --deployment-target agent_runtime --prototype --yes
이 명령어는 ADK 호환성을 위해 프로젝트 구조를 검사하고, 기본 컨테이너 패키징 구성을 준비하고, 기본 배포 설정이 자동으로 입력된 프로젝트 루트에 agents-cli-manifest.yaml 파일을 생성합니다.
👉 새로 생성된 agents-cli-manifest.yaml 파일을 열고 region 필드를 us-central1로 확인하거나 업데이트하여 에이전트가 인증 제공업체와 동일한 리전에 배포되었는지 확인합니다.
region: "us-central1"
에이전트 ID로 에이전트 배포
adk deploy agent_engine으로 배포합니다. 이렇게 하면 에이전트에 자체 에이전트 ID가 프로비저닝됩니다. 이는 이 배포에 속하는 고유한 SPIFFE 지원 암호화 ID로, 에이전트가 인증 관리자 및 기타 Google Cloud 서비스에 인증하는 데 사용됩니다.
👉 secure-agent-demo 디렉터리에서 YOUR_PROJECT_ID를 바꾸고 다음 명령어를 실행합니다.
# Write a config file inside the `app/` folder instructing Agent Runtime to provision a SPIFFE-backed `AGENT_IDENTITY` for this deployment.
echo '{ "identity_type": "AGENT_IDENTITY" }' > app/.agent_engine_config.json
# Generate the dependency list the build will install
uv export --no-emit-workspace --no-hashes --format requirements.txt \
--output-file app/requirements.txt
uv run adk deploy agent_engine app \
--project="YOUR_PROJECT_ID" \
--region="us-central1"
배포에서 컨테이너를 빌드하고 업로드하는 데 몇 분 정도 걸립니다. 완료되면 CLI가 배포된 리소스 이름을 출력합니다. 에이전트를 승인하고 UI 클라이언트를 가리키는 데 필요하므로 reasoningEngines/ENGINE_ID 값을 기록해 둡니다.
에이전트 ID 승인
이제 에이전트가 클라우드에서 실행되므로 Auth Manager에 저장된 사용자 인증 정보에 액세스할 수 있는 권한이 필요합니다. 기본적으로 에이전트의 SPIFFE ID는 외부 클라우드 리소스에 액세스할 수 없습니다.
다음 gcloud 명령어를 실행하여 인증 제공업체 리소스에서 에이전트의 ID에 roles/agentidentity.user 역할을 부여합니다. 이렇게 하면 에이전트가 Vault에서 사용자 토큰을 요청하는 데 필요한 정확한 권한을 부여받게 되며, 그 이상의 권한은 부여되지 않습니다.
# Get YOUR_ORG_ID
gcloud projects get-ancestors $(gcloud config get-value project) \
--filter="type=organization" \
--format="value(id)"
# Get YOUR_PROJECT_NUMBER
gcloud projects describe $(gcloud config get-value project) \
--format="value(projectNumber)"
그런 다음 인증 제공업체에 IAM 정책을 바인딩합니다(YOUR_PROJECT_ID 및 --member 주 구성원 대체).
gcloud agent-identity auth-providers add-iam-policy-binding github-oauth-provider \
--project="YOUR_PROJECT_ID" \
--location="us-central1" \
--role="roles/agentidentity.user" \
--member="principal://agents.global.org-YOUR_ORG_ID.system.id.goog/resources/aiplatform/projects/YOUR_PROJECT_NUMBER/locations/us-central1/reasoningEngines/YOUR_ENGINE_ID"
👉 Google Cloud 콘솔에서 배포된 에이전트의 전체 --member="principal://..." 값을 가져올 수도 있습니다. Agent Runtime 콘솔로 이동하여 배포된 에이전트를 선택하고 ID 탭으로 이동한 후 전체 principal://... 문자열을 직접 복사합니다.
이제 공급업체에서 내 계정에 동일한 역할을 부여합니다. 다음 단계에서 실행하는 UI 클라이언트는 애플리케이션 기본 사용자 인증 정보로 사용자 인증 정보 완료 API를 호출하므로, 이 역할이 없으면 동의 흐름이 agentidentity.authProviders.retrieveCredentials에서 403 오류로 실패합니다.
gcloud agent-identity auth-providers add-iam-policy-binding github-oauth-provider \
--project="YOUR_PROJECT_ID" \
--location="us-central1" \
--role="roles/agentidentity.user" \
--member="user:YOUR_EMAIL_ADDRESS"
7. 3LO 동의 흐름 이해하기
이제 에이전트가 보안 에이전트 ID를 사용하여 Agent Runtime에 배포되었으므로 다음 단계는 사용자가 에이전트와 채팅할 수 있는 맞춤 프런트엔드 인터페이스를 제공하는 것입니다. 더 중요한 것은 Google Cloud 인증 관리자가 인증 루프를 완료하려면 클라이언트 애플리케이션 콜백 핸들러가 필요하다는 점입니다.
Google Cloud Auth Manager는 Vault 내에서 사용자 인증 정보를 안전하게 관리하지만 자체적으로 OAuth 토큰 교환을 완료할 수는 없습니다. 3LO 핸드셰이크는 클라이언트 애플리케이션을 사용하여 간극을 메웁니다.
- 사용자가 GitHub 앱을 승인하면 GitHub는 사용자를 에이전트 ID 인증 제공업체 의
redirectUrl로 다시 리디렉션합니다. - 그런 다음 인증 관리자는 사용자의 브라우저 팝업을 클라이언트 측 콜백 URL (
continue_uri)로 다시 리디렉션합니다. - 이 리디렉션을 가로채고 브라우저의 쿠키에서 nonce를 읽고 Google Cloud의
credentials:finalize엔드포인트를 호출하여 핸드셰이크를 완료하는 것은 클라이언트 애플리케이션의 책임입니다. - 클라이언트가 교환을 완료하면 Google Cloud는 토큰을 인증 제공업체의 Vault에 안전하게 저장하여 에이전트가 GitHub 도구를 호출할 수 있도록 합니다.
콜백 엔드포인트를 호스팅하는 이 커스텀 클라이언트가 없으면 핸드셰이크가 완료되지 않고 Vault에서 사용자 인증 정보를 저장할 수 없습니다.
대화형 OAuth 3LO 흐름은 여러 레이어에 걸쳐 있습니다. 다음은 도구 요청의 전체 실행 수명 주기입니다. 아래 설명과 다음 단계에서 자세히 살펴보겠습니다.
👉 이미지를 클릭하면 확대됩니다.
핸드셰이크에서 클라이언트의 핵심 책임
- 동의 확인 전달 (5~6단계): 에이전트가 동의 URL과 일회용 nonce가 포함된
adk_request_credential를 전송합니다. 클라이언트가 팝업을 열고 nonce를 쿠키로 저장합니다. - 리디렉션 콜백 호스팅 (10~11단계):
/validateUserId. 인증 관리자가 동의 후 팝업을 전송합니다. - 토큰 완료 (12~14단계): 리디렉션의 유효성 검사 상태를 캐시된 nonce와 결합하고
credentials:finalize를 호출하여 토큰을 Vault에 저장합니다.
자체 클라이언트 빌드
실습을 위해 이 클라이언트를 작성할 필요는 없습니다. 다음 단계에서 사전 빌드된 클라이언트를 실행합니다. 자체 애플리케이션에서 이를 구현할 때 다음 두 가지 참조를 사용합니다.
- Auth Manager 문서의 클라이언트 측 애플리케이션 업데이트: 동의 확인 처리 및
credentials:finalize호출을 다룹니다. - 실행 가능한 adk-python 저장소의 샘플 클라이언트 위의 세 가지 책임에 대한 완전하고 작동하는 구현은
main.py에서 확인하세요.
8. 로컬에서 UI 클라이언트 실행
3LO 동의 흐름 시퀀스 다이어그램에 표시된 것처럼 인증 관리자는 브라우저 창을 클라이언트 측 콜백 엔드포인트로 다시 리디렉션합니다. adk-python 저장소의 샘플 클라이언트는 /validateUserId에서 해당 엔드포인트를 호스팅합니다. 다음 단계에 따라 로컬에서 다운로드하고 실행합니다.
클라이언트 파일 다운로드
adk-python의 contributing/samples/integrations/gcp_auth/client 디렉터리에는 세 가지 주요 애셋이 포함되어 있습니다.
main.py: 배포된 에이전트 엔진에 연결하고/validateUserId콜백 엔드포인트를 호스팅하여 OAuth 토큰을 완료하는 FastAPI 백엔드입니다.static/: 브라우저 채팅 UI의 HTML 및 JavaScript 파일입니다.requirements.txt: 클라이언트 서버를 실행하는 데 필요한 Python 패키지입니다.
adk-python는 대규모 저장소이므로 Git의 스파스 체크아웃 기능을 사용하여 contributing/samples/integrations/gcp_auth/client 폴더만 다운로드합니다.
- 먼저
secure-agent-demo에서 한 디렉터리 위로 이동하여 클라이언트를 동위 폴더에 클론합니다.cd .. - 다음 명령어를 실행하여 모든 파일을 다운로드하지 않고 저장소 메타데이터를 클론하고 (
--no-checkout), 체크아웃 경로를contributing/samples/integrations/gcp_auth/client로 제한하고, 해당 폴더만 체크아웃합니다.git clone --filter=blob:none --no-checkout https://github.com/google/adk-python.git cd adk-python git sparse-checkout init --cone git sparse-checkout set contributing/samples/integrations/gcp_auth/client git checkout
클라이언트 실행
- 방금 입력한
adk-python디렉터리 내에서client폴더로 이동합니다.cd contributing/samples/integrations/gcp_auth/client - Python 가상 환경을 만들고 활성화한 다음
requirements.txt에서 클라이언트의 종속 항목을 설치합니다.uv venv --python 3.13 .venv source .venv/bin/activate uv pip install --python .venv/bin/python -r requirements.txt - 클라이언트가 Google Cloud 프로젝트, 리전 (
us-central1), 배포된 Agent Engine ID (YOUR_ENGINE_ID)를 가리키도록 환경 변수를 설정한 다음 포트8501에서 로컬 FastAPI 서버를 시작합니다.export GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID export GOOGLE_CLOUD_LOCATION=us-central1 export AGENT_ID=YOUR_ENGINE_ID .venv/bin/uvicorn main:app --port 8501 - 서버가 성공적으로 시작되었고
http://localhost:8501에서 수신 대기 중인지 확인합니다.
9. OAuth 흐름 테스트
이제 모든 서비스가 배포되고, IAM 바인딩이 구성되고, 환경 변수가 설정되었으므로 안전한 엔드 투 엔드 사용자 위임 승인 흐름을 테스트할 준비가 되었습니다.
A단계: 도구 실행 시작
- 브라우저 탭을 열고 클라이언트 URL(
http://localhost:8501)로 이동합니다. - 구성 설정 아래의 왼쪽 창에서 에이전트 유형을
Remote Agent (Vertex AI)(또는Remote Agent Engine)로 설정합니다. - Google Cloud 프로젝트 ID 및 위치 (
us-central1)를 입력한 다음 원격 에이전트 로드를 클릭합니다. 이렇게 하면 프로젝트에 배포된 에이전트가 로드됩니다. - 엔진 선택 드롭다운에서 배포된
app에이전트를 선택하고 설정 저장 및 적용을 클릭합니다. - 채팅 상자에 타겟팅된 쿼리 (예: 최근 문제 또는 저장소 가져오기)를 입력합니다.
(또는Get the last 2 GitHub issues reported against my name"List my 3 most recently updated repositories")를 입력하고 Enter 키를 누릅니다. - 채팅 UI를 확인합니다. 에이전트에 아직 사용자 세션의 사용자 인증 정보가 없으므로 인증 확인을 수신하고 대화 대화목록에 인증 필요 카드를 표시합니다.
B단계: 3-Legged OAuth 동의 완료하기
- 별도의 브라우저 팝업 창이 열리고 Google Cloud의 인증 관리자를 통해 GitHub OAuth 승인 페이지로 리디렉션됩니다.
- 요청된 권한을 검토하고 승인을 클릭합니다.
- GitHub에서 Google Cloud로 다시 리디렉션되고, Google Cloud는 팝업을
localhost콜백 URL/validateUserId로 리디렉션합니다. - 콜백 서비스는 사용자 인증 정보 핸드셰이크를 처리하고 완료합니다.
C단계: 재개
- 팝업 창이 닫히면 상위 채팅 탭에서 자동으로 닫힘을 감지합니다.
- 프런트엔드가 재개 페이로드를 에이전트에 다시 전송합니다.
- 에이전트는 Google Cloud Auth Manager에서 새로 교환된 토큰을 안전하게 가져오고, 사용자를 대신하여 GitHub MCP 도구를 호출하며, GitHub 데이터를 채팅 창으로 직접 스트리밍합니다. 이 데이터는 에이전트가 자체적으로 액세스할 수 없는 데이터입니다.
D단계: Cloud Logging 로그 검사
토큰 교환 및 완료가 안전하게 처리되었는지 확인하려면 다음 단계를 따르세요.
- Google Cloud 콘솔 로그 탐색기로 이동합니다.
- nonce 추출 및 성공적인 검증을 확인하는 서버 로그를 찾습니다.
INFO:secure-agent-client:Caching consent nonce for session_id: session-xxxxxxx INFO:secure-agent-client:Successfully finalized auth provider credentials. - Agent Runtime 로그 검사: 또는 Agent Platform 콘솔 내에서 직접 실행 로그를 볼 수 있습니다.
- Agent Runtime 콘솔로 이동합니다.
- 목록에서 배포된 에이전트를 클릭합니다.
- Playground 탭으로 전환합니다. 그러면 하단 창에 실시간 에이전트 로그가 표시되어 에이전트의 추론 루프, 도구 실행 세부정보, 토큰 검색 수명 주기가 실시간으로 표시됩니다.
10. 삭제
Google Cloud에서 지속적인 요금이 청구되지 않도록 배포된 리소스를 삭제합니다.
# Follow the instructions here to delete the deployed Agent Runtime resource
# https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale/runtime/manage-deployed-agents#console_3
# Delete the auth provider
gcloud agent-identity auth-providers delete github-oauth-provider \
--project=YOUR_PROJECT_ID --location=us-central1
# Note: deleted providers sit in soft-delete for 30 days, and the name is not
# reusable until roughly a day after that. Pick a fresh name if you repeat this lab.
# Optionally, you could also delete your Google Cloud Project
gcloud projects delete YOUR_PROJECT_ID
# Optionally, delete the GitHub PAT Token and the OAuth app:
# https://github.com/settings/personal-access-tokens
로컬 파일 정리
필요한 경우 로컬 환경을 완전히 삭제하려면 다음 안내를 따르세요.
- 실행 중인 터미널에서 Ctrl+C를 눌러 로컬 uvicorn 서버를 중지합니다.
- 이 실습 중에 만든 프로젝트 디렉터리를 삭제합니다.
# cd to the correct folder
rm -rf secure-agent-demo client adk-python
11. 수고하셨습니다
로그인한 사용자를 대신하여 작동하는 에이전트를 성공적으로 빌드하고 보호했습니다.
학습한 내용:
- 에이전트 시스템 ID: 에이전트가 자체 계정 ID로 작동하여 GCP 인프라와 안전하게 상호작용하고, 원격 분석 로그를 관리하고, 사용자 인증 정보 완료 API를 호출하는 방법입니다.
- 사용자 위임 ID: 에이전트가 3LO (3-legged OAuth) 동의 흐름을 트리거하여 외부 플랫폼 (예: GitHub)에서 사용자를 대신하여 작업할 수 있는 승인을 요청하는 방법입니다.
- 보안 도구 통합: 하드코딩된 보안 비밀을 사용하는 대신 Google Cloud Auth Manager를 사용하여 사용자 토큰을 동적으로 가져오는 방식으로 ADK 에이전트를 모델 컨텍스트 프로토콜 (MCP) 서버에 연결하는 방법
- IAM 정책 구성: 인증 제공업체에서 Agent Runtime ID와 자체 계정을 모두 승인하도록 세분화된 권한 바인딩을 설정하는 방법입니다.
추가 자료
- 에이전트 아이덴티티 인증 관리자: 인증 흐름 구성 및 범위를 이해합니다.
- Agent Runtime 개요
- ADK 문서
- 모델 컨텍스트 프로토콜
