Membangun Agen AI yang bertindak Atas Nama pengguna dengan Identity Agen dan Auth Manager

1. Pengantar

Agen dengan kredensialnya sendiri yang memiliki izin luas dapat melihat data semua orang. Dalam codelab ini, Anda akan membangun agen yang memanggil API pihak ketiga dengan kredensial pengguna yang login, sehingga agen tersebut hanya melihat apa yang dapat dilihat oleh orang tersebut dan tidak lebih.

Anda akan membangunnya dengan Google Agent Development Kit (ADK) dan Gemini Enterprise.

Secara khusus, Anda akan mempelajari cara mendesain arsitektur identitas ganda dengan:

  1. Agen bertindak atas namanya sendiri (Identitas Agen): Dengan menggunakan Identitas Agen yang didukung SPIFFE, agen memanggil Auth Manager, menyimpan telemetri, dan memanggil Google Cloud API.
  2. Agen bertindak atas nama pengguna (Identitas yang Didelegasikan Pengguna): Untuk mengakses resource eksternal seperti GitHub, agen memicu alur izin OAuth 3-legged (3LO) untuk mengkueri alat secara aman menggunakan kredensial pengguna.

Arsitektur Identitas Ganda

Untuk mencapai hal ini, Anda akan mempelajari cara:

  1. Membangun Agen ADK yang terhubung ke server Model Context Protocol (MCP) GitHub.
  2. Perbarui alat agen dari PAT (token akses pribadi) GitHub statis ke alur OAuth 3-legged (3LO) menggunakan Google Cloud Auth Manager.
  3. Men-deploy agen dengan aman ke Agent Runtime dan menyediakan Agent Identity.
  4. Konfigurasikan peran IAM untuk memberikan akses identitas agen ke token vault atas nama pengguna.
  5. Memahami alur 3LO menyeluruh untuk Auth Manager di Google Cloud.

Prasyarat

Sebelum memulai, pastikan Anda memiliki:

  • Project Google Cloud dengan penagihan yang diaktifkan.
  • Google Cloud SDK (gcloud CLI) diinstal dan diautentikasi ke project Anda di komputer lokal. Diperlukan versi 586.0.0 atau yang lebih baru — jalankan gcloud components update.
  • Python 3.10 hingga 3.13 yang diinstal secara lokal.
  • Pengelola paket uv diinstal (pip install uv).
  • Akun GitHub untuk mendaftarkan aplikasi OAuth dan membuat token. Jika tidak memiliki akun GitHub, Anda dapat menggantinya dengan server MCP pihak ketiga yang mendukung OAuth 2.0 three-legged.

2. Penyiapan Project

1. Melakukan autentikasi ke Google Cloud

Lakukan autentikasi ke Google Cloud dari command line lokal untuk memastikan lingkungan Anda memiliki izin yang diperlukan untuk men-deploy ke Agent Runtime, menyediakan Agent Identity, dan mengonfigurasi Auth Manager selama lab ini.

Jalankan perintah berikut untuk login ke akun Google Cloud Anda, tetapkan project aktif Anda (ganti YOUR_PROJECT_ID dengan ID project Google Cloud Anda), dan konfigurasikan Kredensial Default Aplikasi (ADC):

gcloud auth login
gcloud config set project YOUR_PROJECT_ID
gcloud auth application-default login

2. Mengaktifkan Layanan Google Cloud yang Diperlukan

Aktifkan API yang diperlukan di project Google Cloud Anda untuk menjalankan lab ini. Jalankan perintah berikut di terminal.

gcloud services enable \
    agentidentity.googleapis.com \
    agentregistry.googleapis.com \
    aiplatform.googleapis.com \
    apphub.googleapis.com

Perintah ini mungkin memerlukan waktu satu menit untuk dieksekusi; setelah selesai, perintah ini akan kembali ke command prompt yang mengonfirmasi bahwa API aktif.

3. Menginstal Agents CLI dan menyiapkan project

agents-cli adalah alat command line yang digunakan untuk membuat scaffold, mengelola, menguji, dan men-deploy agen ADK ke Gemini Enterprise. Instal secara lokal:

uvx google-agents-cli setup

Verifikasi penginstalan Anda:

agents-cli --help

Anda akan melihat menu bantuan CLI yang menampilkan perintah yang tersedia (seperti deploy, run, dan status).

Membuat scaffolding project awal. Anda akan memulai dengan prototipe lokal dan meningkatkannya nanti untuk deployment Agent Runtime:

agents-cli create secure-agent-demo --prototype --yes

Tindakan ini akan membuat direktori secure-agent-demo yang berisi kode agen dasar, dependensi, dan file pengujian Anda.

4. Menambahkan tambahan ADK yang diperlukan

Tambahkan dua tambahan yang tidak ada di pyproject.toml yang dihasilkan: mcp untuk toolset GitHub, dan agent-identity untuk Auth Manager yang digunakan nanti di lab. Buka secure-agent-demo/pyproject.toml dan ganti seluruh

google-adk

dependency line dengan:

"google-adk[agent-identity,gcp,mcp,otel-gcp]>=2.5.0,<3.0.0",

Kemudian instal:

cd secure-agent-demo
agents-cli install

3. Membangun dan menguji agen

1. Membuat agen

Di dalam project Anda, ganti kode di secure-agent-demo/app/agent.py dengan kode berikut:

# 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",
)

File ini menentukan tiga komponen utama agen:

  • System Instruction (INSTRUCTION): Menetapkan persona, membatasi asisten pada triase GitHub, dan menerapkan aturan keamanan yang ketat (seperti akses hanya baca dan memandu pengguna untuk melakukan autentikasi jika terjadi error).
  • Konfigurasi Agen (root_agent): Membuat instance Agent ADK menggunakan model gemini-3.8-flash, mengonfigurasi logika percobaan ulang HTTP, dan melengkapi agen dengan toolset GitHub.
  • App Wrapper (app): Mengenkapsulasi agen root ke dalam container App ADK, sehingga dapat di-deploy ke Agent Runtime.

2. Menambahkan Alat MCP GitHub

Agen terhubung ke GitHub menggunakan Model Context Protocol (MCP). Buat file baru di secure-agent-demo/app/tools.py untuk mendaftarkan parameter koneksi gateway MCP. Salin dan tempel kode berikut:

# 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",
            },
        )
    )

Fungsi ini membuat alat yang memanggil server MCP GitHub:

  • MCP Toolset (McpToolset): Menemukan dan mendaftarkan kemampuan GitHub secara dinamis sebagai alat agen yang dapat dipanggil.
  • Connection Parameters (StreamableHTTPConnectionParams): Mengarahkan toolset ke gateway MCP publik GitHub.
  • Header Otorisasi: Memasukkan GITHUB_TOKEN sebagai token Bearer dan menerapkan mode hanya baca (X-MCP-Readonly: true) langsung di lapisan transpor.

3. Menguji Secara Lokal dengan PAT (Personal Access Token) GitHub

Untuk menjalankan agen secara lokal dengan kredensial statis:

  1. Buat Fine-grained personal access token di halaman Personal Access Tokens GitHub:
    • Klik Generate new token dan beri nama token Anda.
    • Di bagian Repository access, pilih All repositories (atau pilih repositori tertentu yang ingin Anda uji).
    • Di bagian Permissions > Repositories, klik +Add permissions, lalu pilih Contents, Issues, dan Pull requests ke Read-only (Metadata otomatis ditetapkan ke Read-only).
    • Klik Generate token, lalu salin nilai token yang dibuat. (Atau, jika Anda menggunakan Personal access token (classic), pilih cakupan repo.)
  2. Tetapkan di lingkungan Anda:
    export GITHUB_TOKEN="your_github_pat_here"
    
  3. Buka folder secure-agent-demo (jika Anda belum berada di dalamnya) dan mulai playground lokal:
    cd secure-agent-demo
    agents-cli playground
    
  4. Buka antarmuka playground dan pilih folder app dari menu drop-down. Di kotak chat, coba perintah yang ditargetkan seperti "Get the last 2 GitHub issues reported against my name" atau "List my 3 most recently updated repositories", dan pastikan agen memanggil toolset MCP GitHub dan menampilkan data GitHub Anda. Untuk menguji apakah agen benar-benar menggunakan token PAT Anda untuk mengambil tindakan atas nama Anda, coba tanyakan tentang repositori atau kontribusi pribadi Anda.

4. Mengonfigurasi Auth Manager

Meskipun hardcoding kredensial statis (seperti PAT) memudahkan pembuatan prototipe, hal ini membuat aplikasi produksi rentan terhadap kebocoran kredensial, periode nonaktif akibat pembaruan token manual, dan kurangnya kontrol akses berbasis cloud.

Untuk mengatasi hal ini, Google Cloud menyediakan Pengelola Autentikasi Agent Identity. Pengelola autentikasi Agent Identity adalah vault kredensial yang dirancang untuk membantu melindungi kredensial. Dengan begitu, agen dapat melakukan autentikasi menggunakan kunci API atau client ID dan rahasia OAuth, atau atas nama pengguna melalui delegasi OAuth menggunakan token akses pengguna akhir.

Dalam Auth Manager, Anda mengonfigurasi penyedia autentikasi yang menentukan jenis autentikasi dan kredensial untuk aplikasi pihak ketiga tertentu. Penyedia autentikasi bersifat regional, dan region-nya harus cocok dengan region tempat Anda men-deploy agen. Alur kerja Auth Manager end-to-end beroperasi sebagai berikut:

Alur Kerja Auth Manager

  1. Dynamic Consent Interception: Saat agen mencoba menjalankan alat atas nama pengguna, ADK akan memeriksa Auth Manager untuk menemukan kredensial valid yang ada. Jika tidak ada, Auth Manager akan menampilkan URL otorisasi untuk memulai alur izin OAuth 3-legged (3LO).
  2. Penyimpanan Vault yang Aman: Setelah pengguna akhir memberikan otorisasi kepada aplikasi, Auth Manager akan otomatis menangkap callback OAuth dan menyimpan token akses dan token refresh pengguna yang dihasilkan di vault kredensial yang aman dan dikelola Google.
  3. Siklus Proses Token Otomatis: Auth Manager sepenuhnya mengelola masa berlaku dan rotasi token di latar belakang, sehingga tidak memerlukan logika pembaruan token manual atau periode nonaktif.
  4. Eksekusi Alat Tanpa Rahasia: Untuk tindakan berikutnya, agen (yang melakukan autentikasi melalui SPIFFE Agent Identity-nya) secara dinamis meminta token akses yang didelegasikan pengguna dari Pengelola Autentikasi saat runtime, sehingga kode klien dan agen sepenuhnya bebas rahasia.

Langkah A: Konfigurasi GitHub sebagai Penyedia Auth

Jalankan perintah gcloud berikut untuk membuat penyedia autentikasi GitHub di project Google Cloud Anda. Anda akan memberikan client ID dan rahasia klien nanti: GitHub tidak akan menerbitkannya sebelum mengetahui URL callback penyedia ini.

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"

Deskripsikan penyedia untuk mengambil URL pengalihan OAuth yang dihasilkan:

gcloud agent-identity auth-providers describe github-oauth-provider \
    --project="YOUR_PROJECT_ID" \
    --location="us-central1"

Kolomnya adalah redirectUrl, bertingkat di bawah authProviderTypeParams.threeLeggedOauth. Untuk membacanya secara langsung:

gcloud agent-identity auth-providers describe github-oauth-provider \
    --project="YOUR_PROJECT_ID" --location="us-central1" \
    --format="value(authProviderTypeParams.threeLeggedOauth.redirectUrl)"

Sepertinya https://agentidentitycredentials.googleapis.com/v1/projects/YOUR_PROJECT_ID/locations/us-central1/authProviders/github-oauth-provider/oauthcallback.

Langkah B: Daftarkan Aplikasi OAuth di GitHub

  1. Buka halaman GitHub Developer Settings, pilih OAuth Apps di sidebar kiri, lalu klik New OAuth App (atau Register a new application jika Anda belum pernah membuatnya).
  2. Isi kolom formulir aplikasi OAuth:
    • Application name: Masukkan nama untuk aplikasi Anda (misalnya, secure-agent-demo).
    • Homepage URL: Masukkan URL aplikasi frontend Anda (http://localhost:8501 untuk pembuatan prototipe lokal; Anda dapat memperbaruinya ke URL yang di-deploy dalam produksi).
    • Application description: Opsional (Anda dapat mengosongkannya).
    • Authorization callback URL (URI Pengalihan): Tempel redirectUrl yang diambil di Langkah A.
    • Enable Device Flow: Biarkan tidak dicentang.
  3. Klik Register application.
  4. Di halaman aplikasi yang dihasilkan, salin Client ID, lalu klik Generate a new client secret dan salin Client secret yang dihasilkan. Simpan kedua nilai tersebut — Anda akan menggunakannya sebagai YOUR_GITHUB_CLIENT_ID dan YOUR_GITHUB_CLIENT_SECRET di langkah berikutnya.

Langkah C: Tambahkan kredensial GitHub ke penyedia autentikasi

Ganti YOUR_PROJECT_ID, YOUR_GITHUB_CLIENT_ID, dan YOUR_GITHUB_CLIENT_SECRET dengan nilai Anda, lalu jalankan perintah ini:

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"

Perintah ini akan menampilkan kembali penyedia dengan clientId yang terlihat; rahasianya tidak ditampilkan.

👉 Setelah langkah ini selesai, Google Cloud Auth Manager Anda kini telah sepenuhnya dikonfigurasi dengan kredensial aplikasi OAuth GitHub Anda, sehingga Google Cloud dapat bertindak sebagai vault aman yang menangani izin dan siklus proses token.

5. Mengalihkan token PAT ke Auth Manager

Setelah Auth Manager dikonfigurasi sepenuhnya, langkah berikutnya adalah mengupdate kode alat agen. Ganti konten secure-agent-demo/app/tools.py dengan kode berikut.

👉 Ganti project ID dan lokasi dalam variabel OAUTH_PROVIDER_NAME di bawah.

# 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,
    )

Memahami Kode Alat

Perubahan utamanya adalah auth_scheme. Dengan melampirkannya ke toolset, setiap kali agen memanggil GitHub, ADK akan terlebih dahulu meminta token pengguna tersebut kepada Auth Manager. Jika belum ada, ADK akan meminta pengguna untuk login, bukan gagal. GITHUB_TOKEN hardcode telah dihapus sepenuhnya.

6. Men-deploy Agen ke Agent Runtime

Setelah kita mengupdate alat MCP GitHub untuk menggunakan Auth Manager, langkah berikutnya adalah men-deploy agen ke Agent Runtime. Men-deploy-nya dengan Identitas Agen yang diaktifkan akan menyediakan ID SPIFFE unik untuk agen.

Lakukan inisialisasi konfigurasi deployment untuk project. Pastikan terminal Anda berada di direktori root project secure-agent-demo, lalu jalankan:

agents-cli scaffold enhance . --deployment-target agent_runtime --prototype --yes

Perintah ini memeriksa struktur project Anda untuk kompatibilitas ADK, menyiapkan konfigurasi paket container yang mendasarinya, dan membuat file agents-cli-manifest.yaml di root project Anda yang telah diisi otomatis dengan setelan deployment default.

👉 Buka file agents-cli-manifest.yaml yang baru dibuat dan verifikasi atau perbarui kolom region ke us-central1 untuk memastikan agen Anda di-deploy di region yang sama dengan penyedia autentikasi Anda:

region: "us-central1"

Men-deploy Agen dengan Identitas Agen

Deploy dengan adk deploy agent_engine. Tindakan ini akan menyediakan Identitas Agen-nya sendiri untuk agen, yaitu identitas kriptografis unik yang didukung SPIFFE milik deployment ini, yang digunakan agen untuk melakukan autentikasi ke Auth Manager dan layanan Google Cloud lainnya.

👉 Dari direktori secure-agent-demo, ganti YOUR_PROJECT_ID dan jalankan perintah berikut:

# 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"

Deployment memerlukan waktu beberapa menit untuk membangun dan mengupload container. Setelah selesai, CLI akan mencetak nama resource yang di-deploy. Catat nilai reasoningEngines/ENGINE_ID, karena Anda akan memerlukannya untuk mengizinkan agen dan mengarahkan klien UI ke agen tersebut.

Memberikan Otorisasi pada Identitas Agen

Setelah agen Anda berjalan di cloud, agen tersebut memerlukan izin untuk mengakses kredensial yang disimpan di Auth Manager. Secara default, identitas SPIFFE agen tidak memiliki akses ke resource cloud eksternal.

Jalankan perintah gcloud berikut untuk memberikan peran roles/agentidentity.user ke identitas agen Anda pada resource penyedia autentikasi. Tindakan ini akan memberikan izin yang tepat kepada agen Anda untuk meminta token pengguna dari vault, dan tidak lebih.

# 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)"

Kemudian, ikat kebijakan IAM pada penyedia autentikasi (mengganti YOUR_PROJECT_ID dan akun utama --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"

👉 Anda juga bisa mendapatkan nilai --member="principal://..." lengkap untuk agen yang di-deploy dari Konsol Google Cloud: Buka konsol Agent Runtime, pilih agen yang di-deploy, buka tab Identity, dan salin langsung string principal://... lengkap.

Sekarang, berikan akun Anda sendiri peran yang sama di penyedia. Klien UI yang Anda jalankan di langkah berikutnya akan memanggil API finalisasi kredensial dengan Kredensial Default Aplikasi Anda, sehingga tanpa kredensial ini, alur izin akan gagal dengan error 403 di agentidentity.authProviders.retrieveCredentials:

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. Memahami Alur Izin 3LO

Setelah agen di-deploy ke Agent Runtime dengan Identitas Agen yang aman, langkah berikutnya adalah menyediakan antarmuka frontend kustom bagi pengguna untuk melakukan chat dengannya. Yang lebih penting, Pengelola Autentikasi Google Cloud memerlukan handler callback aplikasi klien untuk menyelesaikan loop autentikasi.

Meskipun Google Cloud Auth Manager mengelola kredensial pengguna dengan aman di dalam vault, alat ini tidak dapat menyelesaikan pertukaran token OAuth sendiri. Handshake 3LO mengandalkan aplikasi klien untuk menjembatani kesenjangan:

  1. Saat pengguna memberikan otorisasi ke aplikasi GitHub, GitHub akan mengalihkan mereka kembali ke redirectUrl penyedia autentikasi Identitas Agen .
  2. Auth Manager kemudian mengalihkan pop-up browser pengguna kembali ke URL callback sisi klien (continue_uri).
  3. Aplikasi klien bertanggung jawab untuk menangkap pengalihan ini, membaca nonce dari cookie browser, dan memanggil endpoint credentials:finalize Google Cloud untuk menyelesaikan handshake.
  4. Setelah klien menyelesaikan pertukaran, Google Cloud akan menyimpan token dengan aman di vault penyedia autentikasi, sehingga agen dapat memanggil alat GitHub.

Tanpa klien kustom yang menghosting endpoint callback ini, handshake tetap tidak lengkap, dan vault tidak dapat menyimpan kredensial.

Alur OAuth 3LO interaktif mencakup beberapa lapisan. Berikut adalah siklus proses eksekusi lengkap dari permintaan alat. Kami akan menguraikannya dalam penjelasan di bawah dan di langkah berikutnya.

👉 Klik gambar untuk memperbesar.

Alur urutan OAuth 3 Pihak

Tanggung Jawab Inti Klien dalam Handshake

  • Meneruskan tantangan izin (Langkah 5-6): agen memunculkan adk_request_credential yang membawa URL izin dan nonce sekali pakai; klien membuka jendela pop-up dan menyimpan nonce sebagai cookie.
  • Menghosting callback pengalihan (Langkah 10-11): /validateUserId, tempat Pengelola Autentikasi mengirimkan jendela pop-up setelah izin diberikan.
  • Menyelesaikan token (Langkah 12-14): gabungkan status validasi dari pengalihan dengan nonce yang di-cache dan panggil credentials:finalize, yang menyimpan token di vault.

Membangun klien Anda sendiri

Anda tidak perlu menulis klien ini untuk lab — langkah berikutnya akan menjalankan klien yang sudah dibuat sebelumnya. Saat Anda menerapkan ini di aplikasi Anda sendiri, berikut adalah dua referensi yang dapat digunakan:

8. Menjalankan Klien UI Secara Lokal

Seperti yang dilacak dalam diagram urutan Alur Izin 3LO, Auth Manager mengalihkan jendela browser kembali ke endpoint callback sisi klien. Klien contoh di repositori adk-python menghosting endpoint tersebut di /validateUserId. Download dan jalankan secara lokal menggunakan langkah-langkah berikut.

Mendownload file klien

Direktori contributing/samples/integrations/gcp_auth/client di adk-python berisi tiga aset utama:

  • main.py: Backend FastAPI yang terhubung ke Agent Engine yang di-deploy dan menghosting endpoint callback /validateUserId untuk menyelesaikan token OAuth.
  • static/: File HTML dan JavaScript untuk UI chat browser.
  • requirements.txt: Paket Python yang diperlukan untuk menjalankan server klien.

Karena adk-python adalah repositori yang besar, gunakan fitur sparse checkout Git untuk mendownload folder contributing/samples/integrations/gcp_auth/client saja:

  1. Pertama, naik satu direktori dari secure-agent-demo agar Anda meng-clone klien ke folder yang setara:
    cd ..
    
  2. Jalankan perintah berikut untuk meng-clone metadata repositori tanpa mendownload semua file (--no-checkout), batasi jalur checkout ke contributing/samples/integrations/gcp_auth/client, dan checkout hanya folder tersebut:
    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
    

Menjalankan klien

  1. Dari dalam direktori adk-python yang baru saja Anda buka, buka folder client:
    cd contributing/samples/integrations/gcp_auth/client
    
  2. Buat dan aktifkan lingkungan virtual Python, lalu instal dependensi klien dari requirements.txt:
    uv venv --python 3.13 .venv
    source .venv/bin/activate
    uv pip install --python .venv/bin/python -r requirements.txt
    
  3. Tetapkan variabel lingkungan yang mengarahkan klien ke project Google Cloud, region (us-central1), dan ID Agent Engine yang di-deploy (YOUR_ENGINE_ID), lalu mulai server FastAPI lokal di port 8501:
    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
    
  4. Pastikan server berhasil dimulai dan memproses di http://localhost:8501.

9. Menguji Alur OAuth

Setelah semua layanan di-deploy, binding IAM dikonfigurasi, dan variabel lingkungan ditetapkan, Anda siap menguji alur otorisasi yang didelegasikan pengguna secara menyeluruh dan aman.

Langkah A: Memulai Eksekusi Alat

  1. Buka tab browser, lalu buka URL Klien Anda: http://localhost:8501.
  2. Di panel kiri di bagian Configuration Settings, tetapkan Agent Type ke Remote Agent (Vertex AI) (atau Remote Agent Engine).
  3. Masukkan Project ID dan Location (us-central1) Google Cloud Anda, lalu klik Load Remote Agents. Tindakan ini akan memuat agen yang di-deploy ke project Anda.
  4. Pilih agen app yang di-deploy dari menu drop-down Select Engine, lalu klik Save & Apply Settings.
  5. Di kotak chat, ketik kueri bertarget (seperti mengambil masalah atau repositori terbaru Anda):
    Get the last 2 GitHub issues reported against my name
    
    (Atau coba "List my 3 most recently updated repositories"), lalu tekan Enter.
  6. Amati UI chat: Karena agen belum memiliki kredensial untuk sesi pengguna Anda, agen akan menerima tantangan autentikasi dan menampilkan kartu Authentication Required di rangkaian percakapan.
  1. Jendela pop-up browser terpisah akan terbuka, yang mengalihkan Anda melalui Pengelola Auth Google Cloud ke halaman otorisasi OAuth GitHub.
  2. Tinjau izin yang diminta, lalu klik Authorize.
  3. GitHub akan mengalihkan kembali ke Google Cloud, yang mengalihkan pop-up ke URL callback localhost Anda /validateUserId.
  4. Layanan callback memproses dan menyelesaikan handshake kredensial.

Langkah C: Lanjutkan

  1. Setelah jendela pop-up ditutup, tab chat induk akan otomatis mendeteksi penutupan tersebut.
  2. Frontend mengirimkan payload resume kembali ke agen.
  3. Agen akan mengambil token yang baru ditukar dengan aman dari Google Cloud Auth Manager, memanggil alat MCP GitHub atas nama Anda, dan melakukan streaming data GitHub Anda langsung kembali ke jendela chat — data yang tidak dapat dijangkau oleh agen itu sendiri.

Langkah D: Memeriksa Log Cloud

Untuk memverifikasi bahwa pertukaran dan finalisasi token diproses dengan aman:

  1. Buka Logs Explorer di Konsol Google Cloud.
  2. Temukan log server yang mengonfirmasi ekstraksi nonce dan validasi yang berhasil:
    INFO:secure-agent-client:Caching consent nonce for session_id: session-xxxxxxx
    INFO:secure-agent-client:Successfully finalized auth provider credentials.
    
  3. Memeriksa Log Agent Runtime: Anda juga dapat melihat log eksekusi langsung di dalam Konsol Agent Platform:
    • Buka Agent Runtime Console.
    • Klik agen yang di-deploy dari daftar.
    • Beralihlah ke tab Playground; tab ini akan menampilkan log agen langsung di panel bawah, yang menunjukkan reasoning loop agen, detail eksekusi alat, dan siklus proses pengambilan token secara real time.

10. Pembersihan

Agar tidak dikenai biaya berkelanjutan di Google Cloud, hapus resource yang di-deploy:

# 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

Membersihkan File Lokal

Jika perlu, untuk membersihkan lingkungan lokal Anda sepenuhnya:

  1. Hentikan server uvicorn lokal dengan menekan Ctrl+C di terminal tempat server tersebut berjalan.
  2. Hapus direktori project yang dibuat selama lab ini:
# cd to the correct folder
rm -rf secure-agent-demo client adk-python

11. Selamat!

Anda telah berhasil membangun dan mengamankan agen yang bertindak atas nama pengguna yang login.

Hal yang telah Anda pelajari:

  • Identitas Sistem Agen: Cara agen beroperasi di bawah identitas Akunnya sendiri untuk berinteraksi secara aman dengan infrastruktur GCP, mengelola log telemetri, dan memanggil API finalisasi kredensial.
  • Identitas yang Didelegasikan Pengguna: Cara agen meminta otorisasi untuk bertindak atas nama pengguna di platform eksternal (seperti GitHub) dengan memicu alur izin OAuth 3-legged (3LO).
  • Integrasi Alat yang Aman: Cara menghubungkan Agen ADK ke server Model Context Protocol (MCP) menggunakan Google Cloud Auth Manager untuk mengambil token pengguna secara dinamis, bukan menggunakan secret hardcode.
  • Konfigurasi Kebijakan IAM: Cara menyiapkan binding izin terperinci untuk mengizinkan identitas Agent Runtime dan akun Anda sendiri di penyedia autentikasi.

Bacaan Lebih Lanjut