1. Giới thiệu
Một nhân viên hỗ trợ có thông tin xác thực riêng và có quyền truy cập rộng sẽ thấy dữ liệu của mọi người. Trong lớp học lập trình này, bạn sẽ xây dựng một tác nhân gọi API bên thứ ba bằng thông tin đăng nhập của chính người dùng đã đăng nhập, nhờ đó, tác nhân này sẽ thấy chính xác những gì người đó có thể thấy và không thấy gì khác.
Bạn sẽ xây dựng tác nhân này bằng Bộ công cụ phát triển tác nhân (ADK) của Google và Gemini Enterprise.
Cụ thể, bạn sẽ tìm hiểu cách thiết kế một cấu trúc danh tính kép, trong đó:
- Tác nhân hành động thay mặt cho chính mình (Danh tính tác nhân): Sử dụng Danh tính tác nhân do SPIFFE hỗ trợ, tác nhân sẽ gọi Trình quản lý xác thực, lưu trữ dữ liệu đo từ xa và gọi Cloud APIs của Google.
- Tác nhân hành động thay mặt người dùng (Danh tính do người dùng uỷ quyền): Để truy cập vào các tài nguyên bên ngoài như GitHub, tác nhân sẽ kích hoạt quy trình đồng ý OAuth 3 bên (3LO) để truy vấn các công cụ một cách an toàn bằng thông tin xác thực của người dùng.

Để đạt được điều này, bạn sẽ tìm hiểu cách:
- Xây dựng một Tác nhân ADK kết nối với máy chủ Giao thức ngữ cảnh mô hình (MCP) của GitHub.
- Cập nhật công cụ của tác nhân từ PAT (mã truy cập cá nhân) tĩnh trên GitHub thành quy trình OAuth 3 bên (3LO) bằng Trình quản lý xác thực của Google Cloud.
- Triển khai tác nhân một cách an toàn cho Thời gian chạy của tác nhân và cấp Danh tính của tác nhân.
- Định cấu hình vai trò IAM để cấp cho danh tính của tác nhân quyền truy cập vào kho mã thông báo thay mặt cho người dùng.
- Tìm hiểu quy trình 3LO toàn diện cho Trình quản lý xác thực trong Google Cloud.
Điều kiện tiên quyết
Trước khi bắt đầu, hãy đảm bảo rằng bạn có:
- Một Dự án Google Cloud đã bật tính năng thanh toán.
- Google Cloud SDK (
gcloudCLI) được cài đặt và xác thực cho dự án trên máy cục bộ của bạn. Cần có phiên bản 586.0.0 trở lên – chạygcloud components update. - Python 3.10 đến 3.13 được cài đặt trên máy.
- Đã cài đặt
uvtrình quản lý gói (pip install uv). - Tài khoản GitHub để đăng ký ứng dụng OAuth và tạo mã thông báo. Nếu không có tài khoản GitHub, bạn có thể thay thế bằng bất kỳ máy chủ MCP bên thứ ba nào hỗ trợ OAuth 2.0 ba bên.
2. Thiết lập dự án
1. Xác thực với Google Cloud
Xác thực với Google Cloud từ dòng lệnh cục bộ để đảm bảo môi trường của bạn có các quyền cần thiết để triển khai cho Môi trường thời gian chạy của tác nhân, cấp Danh tính tác nhân và định cấu hình Trình quản lý xác thực trong phòng thí nghiệm này.
Chạy các lệnh sau để đăng nhập vào tài khoản Google Cloud, đặt dự án trên đám mây đang hoạt động (thay thế YOUR_PROJECT_ID bằng mã dự án Google Cloud của bạn) và định cấu hình Thông tin xác thực mặc định của ứng dụng (ADC):
gcloud auth login
gcloud config set project YOUR_PROJECT_ID
gcloud auth application-default login
2. Bật các dịch vụ Google Cloud bắt buộc
Bật các API cần thiết trong dự án Google Cloud để chạy bài thực hành này. Chạy lệnh sau trong dòng lệnh:
gcloud services enable \
agentidentity.googleapis.com \
agentregistry.googleapis.com \
aiplatform.googleapis.com \
apphub.googleapis.com
Lệnh này có thể mất một phút để thực thi; sau khi hoàn tất, lệnh này sẽ quay lại dấu nhắc lệnh xác nhận rằng các API đang hoạt động.
3. Cài đặt CLI của tác nhân và thiết lập dự án
agents-cli là công cụ dòng lệnh dùng để tạo khung, quản lý, kiểm thử và triển khai các tác nhân ADK cho Gemini Enterprise. Cài đặt cục bộ:
uvx google-agents-cli setup
Xác minh bản cài đặt:
agents-cli --help
Bạn sẽ thấy trình đơn trợ giúp của CLI hiển thị các lệnh có sẵn (chẳng hạn như deploy, run và status).
Tạo cấu trúc ban đầu cho dự án. Bạn sẽ bắt đầu bằng một nguyên mẫu cục bộ và cải thiện nguyên mẫu đó sau để triển khai Môi trường thời gian chạy của tác nhân:
agents-cli create secure-agent-demo --prototype --yes
Thao tác này sẽ tạo thư mục secure-agent-demo chứa mã tác nhân cơ bản, các phần phụ thuộc và tệp kiểm thử.
4. Thêm các tiện ích ADK bắt buộc
Thêm hai thành phần bổ sung còn thiếu trong pyproject.toml được tạo: mcp cho bộ công cụ GitHub và agent-identity cho Trình quản lý xác thực được dùng sau này trong lớp học lập trình. Mở secure-agent-demo/pyproject.toml và thay thế toàn bộ
google-adk
dependency line bằng:
"google-adk[agent-identity,gcp,mcp,otel-gcp]>=2.5.0,<3.0.0",
Sau đó, hãy cài đặt:
cd secure-agent-demo
agents-cli install
3. Tạo và thử nghiệm tác nhân
1. Tạo tác nhân
Trong dự án, hãy thay thế mã trong secure-agent-demo/app/agent.py bằng đoạn mã sau:
# 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",
)
Tệp này xác định 3 thành phần chính của tác nhân:
- Chỉ dẫn hệ thống (
INSTRUCTION): Đặt tính cách, đặt phạm vi cho trợ lý để phân loại GitHub và thực thi các quy tắc an toàn nghiêm ngặt (như quyền chỉ có thể đọc và hướng dẫn người dùng xác thực nếu xảy ra lỗi). - Agent Configuration (
root_agent): Tạo thực thể cho ADKAgentbằng mô hìnhgemini-3.8-flash, định cấu hình logic thử lại HTTP và trang bị cho tác nhân bộ công cụ GitHub. - Trình bao bọc tác nhân (
app): Đóng gói tác nhân gốc vào vùng chứa ADKApp, giúp triển khai tác nhân đó vào Môi trường thời gian chạy tác nhân.
2. Thêm công cụ MCP cho GitHub
Tác nhân kết nối với GitHub bằng Giao thức ngữ cảnh mô hình (MCP). Tạo một tệp mới tại secure-agent-demo/app/tools.py để đăng ký các tham số kết nối cổng MCP. Sao chép và dán mã sau:
# 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",
},
)
)
Hàm này tạo một công cụ gọi máy chủ MCP của GitHub:
- Bộ công cụ MCP (
McpToolset): Tự động khám phá và đăng ký các chức năng của GitHub dưới dạng công cụ tác nhân có thể gọi. - Tham số kết nối (
StreamableHTTPConnectionParams): Trỏ bộ công cụ đến cổng MCP công khai của GitHub. - Tiêu đề uỷ quyền: Chèn
GITHUB_TOKENlàm mã thông báo truy cập và thực thi chế độ chỉ có thể đọc (X-MCP-Readonly: true) ngay tại tầng truyền tải.
3. Kiểm thử cục bộ bằng PAT (Mã truy cập cá nhân) của GitHub
Cách chạy tác nhân trên máy bằng thông tin xác thực tĩnh:
- Tạo Mã truy cập cá nhân chi tiết trên trang Mã truy cập cá nhân của GitHub:
- Nhấp vào Tạo mã thông báo mới rồi đặt tên cho mã thông báo.
- Trong phần Repository access (Quyền truy cập vào kho lưu trữ), hãy chọn All repositories (Tất cả kho lưu trữ) (hoặc chọn kho lưu trữ cụ thể mà bạn muốn kiểm thử).
- Trong phần Permissions > Repositories (Quyền > Kho lưu trữ), hãy nhấp vào +Add permissions (+Thêm quyền) rồi chọn Contents (Nội dung), Issues (Vấn đề) và Pull requests (Yêu cầu lấy dữ liệu) thành Read-only (Chỉ đọc) (Metadata (Siêu dữ liệu) được tự động đặt thành Chỉ đọc).
- Nhấp vào Tạo mã thông báo rồi sao chép giá trị mã thông báo đã tạo. (Ngoài ra, nếu bạn sử dụng Mã truy cập cá nhân (cổ điển), hãy chọn phạm vi
repo.)
- Đặt biến này trong môi trường của bạn:
export GITHUB_TOKEN="your_github_pat_here" - Chuyển đến thư mục
secure-agent-demo(nếu bạn chưa ở trong thư mục đó) và bắt đầu chạy ứng dụng minh hoạ cục bộ:cd secure-agent-demo agents-cli playground - Mở giao diện sân chơi rồi chọn thư mục
apptrong trình đơn thả xuống. Trong hộp trò chuyện, hãy thử một câu lệnh có mục tiêu như"Get the last 2 GitHub issues reported against my name"hoặc"List my 3 most recently updated repositories", rồi xác minh rằng tác nhân gọi bộ công cụ MCP của GitHub và trả về dữ liệu GitHub của bạn. Để kiểm tra xem tác nhân có thực sự sử dụng mã thông báo PAT của bạn để thay mặt bạn hành động hay không, hãy thử hỏi tác nhân về các kho lưu trữ riêng tư hoặc nội dung đóng góp của bạn.
4. Định cấu hình Trình quản lý xác thực
Mặc dù việc cố định giá trị thông tin xác thực tĩnh (như PAT) trong mã rất thuận tiện cho việc tạo bản minh hoạ, nhưng việc này khiến các ứng dụng chính thức dễ bị rò rỉ thông tin xác thực, thời gian ngừng hoạt động để làm mới mã thông báo theo cách thủ công và thiếu các chế độ kiểm soát quyền truy cập gốc trên đám mây.
Để giải quyết vấn đề này, Google Cloud cung cấp Trình quản lý xác thực danh tính tác nhân. Trình quản lý xác thực danh tính của nhân viên hỗ trợ là một kho lưu trữ thông tin xác thực được thiết kế để giúp bảo vệ thông tin xác thực. Tính năng này cho phép tác nhân xác thực bằng khoá API hoặc mã ứng dụng khách OAuth và mật khẩu ứng dụng khách, hoặc thay mặt người dùng thông qua việc uỷ quyền OAuth bằng mã truy cập của người dùng cuối.
Trong Trình quản lý xác thực, bạn định cấu hình các nhà cung cấp dịch vụ xác thực để xác định loại xác thực và thông tin xác thực cho các ứng dụng cụ thể của bên thứ ba. Nhà cung cấp dịch vụ xác thực là theo khu vực và khu vực này phải khớp với khu vực bạn triển khai tác nhân. Quy trình toàn diện của Trình quản lý xác thực hoạt động như sau:

- Chặn đồng ý linh động: Khi tác nhân cố gắng thực thi một công cụ thay mặt cho người dùng, ADK sẽ kiểm tra Trình quản lý xác thực để tìm thông tin xác thực hợp lệ hiện có. Nếu không có mã thông báo nào, Trình quản lý xác thực sẽ trả về một URL uỷ quyền để bắt đầu quy trình đồng ý OAuth 3 bên (3LO).
- Lưu trữ an toàn trong kho lưu trữ: Sau khi người dùng cuối uỷ quyền cho ứng dụng, Trình quản lý xác thực sẽ tự động chặn lệnh gọi lại OAuth và lưu trữ mã truy cập cũng như mã làm mới của người dùng trong một kho lưu trữ thông tin xác thực an toàn do Google quản lý.
- Vòng đời mã thông báo tự động: Trình quản lý xác thực quản lý hoàn toàn việc hết hạn và xoay vòng mã thông báo ở chế độ nền, giúp bạn không cần phải dùng logic làm mới mã thông báo theo cách thủ công hoặc thời gian ngừng hoạt động.
- Thực thi công cụ không cần khoá bí mật: Đối với các hành động tiếp theo, tác nhân (xác thực thông qua Danh tính tác nhân SPIFFE) sẽ yêu cầu mã truy cập được uỷ quyền của người dùng từ Trình quản lý xác thực trong thời gian chạy, giúp cả mã ứng dụng khách và mã tác nhân hoàn toàn không cần khoá bí mật.
Bước A: Định cấu hình GitHub làm Nhà cung cấp dịch vụ xác thực
Chạy lệnh gcloud sau để tạo nhà cung cấp dịch vụ xác thực GitHub trong dự án trên đám mây của Google. Bạn sẽ cung cấp mã ứng dụng khách và mật khẩu ứng dụng khách sau: GitHub sẽ không cấp các thông tin này cho đến khi biết URL gọi lại của nhà cung cấp này.
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"
Mô tả nhà cung cấp để truy xuất URL chuyển hướng OAuth đã tạo:
gcloud agent-identity auth-providers describe github-oauth-provider \
--project="YOUR_PROJECT_ID" \
--location="us-central1"
Trường này là redirectUrl, được lồng trong authProviderTypeParams.threeLeggedOauth. Cách đọc trực tiếp:
gcloud agent-identity auth-providers describe github-oauth-provider \
--project="YOUR_PROJECT_ID" --location="us-central1" \
--format="value(authProviderTypeParams.threeLeggedOauth.redirectUrl)"
Có vẻ như https://agentidentitycredentials.googleapis.com/v1/projects/YOUR_PROJECT_ID/locations/us-central1/authProviders/github-oauth-provider/oauthcallback.
Bước B: Đăng ký ứng dụng OAuth trong GitHub
- Chuyển đến trang Cài đặt dành cho nhà phát triển GitHub, chọn OAuth Apps (Ứng dụng OAuth) trong thanh bên trái rồi nhấp vào New OAuth App (Ứng dụng OAuth mới) (hoặc Register a new application (Đăng ký ứng dụng mới) nếu bạn chưa từng tạo ứng dụng nào).
- Điền vào các trường trong biểu mẫu đăng ký OAuth:
- Tên ứng dụng: Nhập tên cho ứng dụng của bạn (ví dụ:
secure-agent-demo). - URL trang chủ: Nhập URL của ứng dụng giao diện người dùng (
http://localhost:8501để tạo nguyên mẫu cục bộ; bạn có thể cập nhật URL này thành URL đã triển khai trong phiên bản chính thức). - Nội dung mô tả ứng dụng: Không bắt buộc (bạn có thể để trống).
- Authorization callback URL (URL gọi lại uỷ quyền) (URI chuyển hướng): Dán
redirectUrlđã truy xuất ở Bước A. - Enable Device Flow (Bật quy trình thiết bị): Để trống.
- Tên ứng dụng: Nhập tên cho ứng dụng của bạn (ví dụ:
- Nhấp vào Register application (Đăng ký ứng dụng).
- Trên trang ứng dụng thu được, hãy sao chép Mã ứng dụng khách, sau đó nhấp vào Tạo khoá bí mật mới của ứng dụng khách rồi sao chép Khoá bí mật của ứng dụng khách đã tạo. Lưu cả hai giá trị — bạn sẽ sử dụng các giá trị này làm
YOUR_GITHUB_CLIENT_IDvàYOUR_GITHUB_CLIENT_SECRETtrong bước tiếp theo.
Bước C: Thêm thông tin đăng nhập GitHub vào nhà cung cấp dịch vụ xác thực
Thay thế YOUR_PROJECT_ID, YOUR_GITHUB_CLIENT_ID và YOUR_GITHUB_CLIENT_SECRET bằng các giá trị của bạn rồi chạy lệnh sau:
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"
Lệnh này sẽ lặp lại nhà cung cấp với clientId hiển thị; bí mật không được lặp lại.
👉 Sau khi hoàn tất bước này, Trình quản lý xác thực Google Cloud của bạn hiện đã được định cấu hình đầy đủ bằng thông tin xác thực ứng dụng OAuth của GitHub, thiết lập Google Cloud làm kho lưu trữ bảo mật xử lý sự đồng ý và vòng đời của mã thông báo.
5. Chuyển mã thông báo PAT sang Trình quản lý xác thực
Giờ đây, khi Trình quản lý xác thực đã được định cấu hình đầy đủ, bước tiếp theo là cập nhật mã công cụ của tác nhân. Thay thế nội dung của secure-agent-demo/app/tools.py bằng mã sau.
👉 Thay thế mã dự án và vị trí trong biến OAUTH_PROVIDER_NAME bên dưới.
# 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,
)
Tìm hiểu về mã công cụ
Thay đổi quan trọng là auth_scheme. Việc đính kèm mã thông báo vào bộ công cụ có nghĩa là bất cứ khi nào tác nhân gọi GitHub, ADK trước tiên sẽ yêu cầu Trình quản lý xác thực cung cấp mã thông báo của người dùng đó. Nếu chưa có mã thông báo, ADK sẽ nhắc người dùng đăng nhập thay vì báo lỗi. GITHUB_TOKEN được cố định giá trị trong mã đã hoàn toàn biến mất.
6. Triển khai tác nhân cho Môi trường thời gian chạy của tác nhân
Bây giờ, chúng ta đã cập nhật công cụ MCP của GitHub để sử dụng Trình quản lý xác thực, bước tiếp theo là triển khai tác nhân cho Thời gian chạy tác nhân. Khi triển khai tác nhân có bật Danh tính tác nhân, một mã SPIFFE duy nhất sẽ được cấp cho tác nhân đó.
Khởi chạy cấu hình triển khai cho dự án. Đảm bảo thiết bị đầu cuối của bạn nằm trong thư mục gốc của dự án secure-agent-demo, sau đó chạy:
agents-cli scaffold enhance . --deployment-target agent_runtime --prototype --yes
Lệnh này kiểm tra cấu trúc dự án của bạn để đảm bảo khả năng tương thích với ADK, chuẩn bị cấu hình đóng gói vùng chứa cơ bản và tạo tệp agents-cli-manifest.yaml trong thư mục gốc của dự án, được điền sẵn các chế độ cài đặt triển khai mặc định.
👉 Mở tệp agents-cli-manifest.yaml mới tạo, rồi xác minh hoặc cập nhật trường region thành us-central1 để đảm bảo tác nhân của bạn được triển khai ở cùng khu vực với nhà cung cấp dịch vụ xác thực:
region: "us-central1"
Triển khai tác nhân bằng danh tính tác nhân
Triển khai bằng adk deploy agent_engine. Thao tác này sẽ cung cấp cho tác nhân Danh tính tác nhân riêng — một danh tính mã hoá duy nhất, được SPIFFE hỗ trợ, thuộc về quá trình triển khai này. Tác nhân sẽ sử dụng danh tính này để xác thực với Trình quản lý xác thực và các dịch vụ khác của Google Cloud.
👉 Trong thư mục secure-agent-demo, hãy thay thế YOUR_PROJECT_ID và chạy các lệnh sau:
# 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"
Quá trình triển khai mất vài phút để tạo và tải vùng chứa lên. Sau khi hoàn tất, CLI sẽ in tên tài nguyên đã triển khai. Hãy ghi lại giá trị reasoningEngines/ENGINE_ID vì bạn cần giá trị này để uỷ quyền cho tác nhân và trỏ ứng dụng giao diện người dùng đến giá trị đó.
Uỷ quyền cho danh tính của tác nhân
Giờ đây, khi tác nhân của bạn đang chạy trên đám mây, tác nhân đó cần có quyền truy cập vào thông tin xác thực được lưu trữ trong Trình quản lý xác thực. Theo mặc định, danh tính SPIFFE của tác nhân không có quyền truy cập vào tài nguyên đám mây bên ngoài.
Chạy lệnh gcloud sau để cấp vai trò roles/agentidentity.user cho danh tính của tác nhân trên tài nguyên của nhà cung cấp dịch vụ xác thực. Thao tác này sẽ cấp cho tác nhân của bạn chính xác các quyền cần thiết để yêu cầu mã thông báo người dùng từ kho lưu trữ, chứ không có quyền nào khác.
# 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)"
Sau đó, liên kết chính sách IAM trên nhà cung cấp dịch vụ xác thực (thay thế YOUR_PROJECT_ID và --member chính):
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"
👉 Bạn cũng có thể lấy giá trị --member="principal://..." đầy đủ cho tác nhân đã triển khai từ Google Cloud Console: Chuyển đến bảng điều khiển Thời gian chạy của tác nhân, chọn tác nhân đã triển khai, chuyển đến thẻ Danh tính rồi sao chép trực tiếp chuỗi principal://... hoàn chỉnh.
Bây giờ, hãy cấp cho tài khoản của bạn vai trò tương tự trên nhà cung cấp. Ứng dụng khách giao diện người dùng mà bạn chạy ở bước tiếp theo sẽ gọi API hoàn tất thông tin xác thực bằng Thông tin xác thực mặc định của ứng dụng. Vì vậy, nếu không có thông tin này, quy trình đồng ý sẽ không thành công và trả về lỗi 403 trên 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. Tìm hiểu quy trình lấy sự đồng ý 3LO
Giờ đây, khi tác nhân đã được triển khai cho Môi trường thời gian chạy của tác nhân bằng Danh tính tác nhân bảo mật, bước tiếp theo là cung cấp giao diện người dùng tuỳ chỉnh để người dùng trò chuyện với tác nhân đó. Quan trọng hơn, Trình quản lý xác thực Google Cloud yêu cầu trình xử lý gọi lại ứng dụng khách để hoàn tất vòng lặp xác thực.
Mặc dù Google Cloud Auth Manager quản lý thông tin xác thực của người dùng một cách an toàn trong kho lưu trữ, nhưng công cụ này không thể tự hoàn tất quá trình trao đổi mã thông báo OAuth. Quá trình bắt tay 3LO dựa vào ứng dụng khách để thu hẹp khoảng cách:
- Khi người dùng uỷ quyền cho ứng dụng GitHub, GitHub sẽ chuyển hướng họ trở lại
redirectUrlcủa nhà cung cấp dịch vụ xác thực Danh tính tác nhân . - Sau đó, Trình quản lý xác thực sẽ chuyển hướng cửa sổ bật lên trên trình duyệt của người dùng trở lại URL gọi lại phía máy khách (
continue_uri). - Ứng dụng khách có trách nhiệm chặn lệnh chuyển hướng này, đọc số chỉ dùng một lần từ cookie của trình duyệt và gọi điểm cuối
credentials:finalizecủa Google Cloud để hoàn tất quá trình bắt tay. - Sau khi ứng dụng hoàn tất quá trình trao đổi, Google Cloud sẽ lưu mã thông báo một cách an toàn trong kho lưu trữ của nhà cung cấp dịch vụ xác thực, cho phép tác nhân gọi công cụ GitHub.
Nếu không có ứng dụng tuỳ chỉnh này lưu trữ điểm cuối gọi lại, thì quá trình bắt tay sẽ không hoàn tất và kho lưu trữ không thể lưu trữ thông tin xác thực.
Quy trình OAuth 3LO tương tác trải rộng trên nhiều lớp. Sau đây là toàn bộ vòng đời thực thi của một yêu cầu công cụ. Chúng tôi sẽ trình bày chi tiết về vấn đề này trong phần giải thích bên dưới và trong bước tiếp theo.
👉 Nhấp vào hình ảnh để phóng to.
Trách nhiệm cốt lõi của khách hàng trong quá trình bàn giao
- Chuyển tiếp yêu cầu xác minh sự đồng ý (Bước 5-6): tác nhân phát ra một
adk_request_credentialmang URL đồng ý và một số chỉ dùng một lần; ứng dụng mở cửa sổ bật lên và lưu trữ số chỉ dùng một lần dưới dạng cookie. - Lưu trữ lệnh gọi lại chuyển hướng (Bước 10-11):
/validateUserId, nơi Trình quản lý xác thực gửi cửa sổ bật lên sau khi có sự đồng ý. - Hoàn tất mã thông báo (Bước 12-14): kết hợp trạng thái xác thực từ lệnh chuyển hướng với số chỉ dùng một lần được lưu vào bộ nhớ đệm và gọi
credentials:finalizeđể lưu trữ mã thông báo trong kho bảo mật.
Tạo ứng dụng khách của riêng bạn
Bạn không cần phải viết ứng dụng này cho lớp học lập trình — bước tiếp theo sẽ chạy một ứng dụng được tạo sẵn. Khi bạn triển khai tính năng này trong ứng dụng của riêng mình, đây là hai tài liệu tham khảo để bạn thực hiện:
- Cập nhật ứng dụng phía máy khách trong tài liệu về Trình quản lý xác thực, trong đó có nội dung xử lý yêu cầu đồng ý và gọi
credentials:finalize. - Ứng dụng khách mẫu có thể chạy trong kho lưu trữ adk-python. Hãy đọc
main.pytại đó để biết cách triển khai hoàn chỉnh và hiệu quả cho ba trách nhiệm nêu trên.
8. Chạy ứng dụng giao diện người dùng trên máy
Như được theo dõi trong sơ đồ trình tự Quy trình đồng ý 3LO, Trình quản lý xác thực sẽ chuyển hướng cửa sổ trình duyệt trở lại điểm cuối gọi lại phía máy khách. Ứng dụng mẫu trong kho lưu trữ adk-python lưu trữ điểm cuối đó tại /validateUserId. Tải xuống và chạy cục bộ bằng cách làm theo các bước sau.
Tải tệp ứng dụng xuống
Thư mục contributing/samples/integrations/gcp_auth/client trong adk-python chứa 3 thành phần chính:
main.py: Phần phụ trợ FastAPI kết nối với Agent Engine đã triển khai và lưu trữ điểm cuối gọi lại/validateUserIdđể hoàn tất mã thông báo OAuth.static/: Các tệp HTML và JavaScript cho giao diện người dùng trò chuyện trên trình duyệt.requirements.txt: Các gói Python cần thiết để chạy máy chủ ứng dụng.
Vì adk-python là một kho lưu trữ lớn, hãy sử dụng tính năng kiểm xuất thưa của Git để chỉ tải thư mục contributing/samples/integrations/gcp_auth/client xuống:
- Trước tiên, hãy di chuyển lên một thư mục bên ngoài
secure-agent-demođể sao chép ứng dụng vào một thư mục đồng cấp:cd .. - Chạy các lệnh sau để sao chép siêu dữ liệu kho lưu trữ mà không cần tải tất cả tệp xuống (
--no-checkout), hạn chế đường dẫn thanh toán thànhcontributing/samples/integrations/gcp_auth/clientvà chỉ thanh toán thư mục đó: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
Chạy ứng dụng khách
- Trong thư mục
adk-pythonbạn vừa nhập, hãy chuyển đến thư mụcclient:cd contributing/samples/integrations/gcp_auth/client - Tạo và kích hoạt môi trường ảo Python, sau đó cài đặt các phần phụ thuộc của ứng dụng từ
requirements.txt:uv venv --python 3.13 .venv source .venv/bin/activate uv pip install --python .venv/bin/python -r requirements.txt - Đặt các biến môi trường trỏ ứng dụng khách đến dự án trên đám mây của bạn, vùng (
us-central1) và mã Công cụ tác nhân đã triển khai (YOUR_ENGINE_ID), sau đó khởi động máy chủ FastAPI cục bộ trên cổng8501: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 - Xác minh rằng máy chủ đã khởi động thành công và đang nghe trên
http://localhost:8501.
9. Kiểm thử quy trình OAuth
Giờ đây, khi tất cả dịch vụ đã được triển khai, các liên kết IAM đã được định cấu hình và các biến môi trường đã được thiết lập, bạn đã sẵn sàng kiểm thử quy trình uỷ quyền an toàn từ đầu đến cuối do người dùng uỷ quyền!
Bước A: Bắt đầu thực thi công cụ
- Mở một thẻ trình duyệt và chuyển đến URL của ứng dụng:
http://localhost:8501. - Trong ngăn bên trái, trong phần Configuration Settings (Cài đặt cấu hình), hãy đặt Agent Type (Loại tác nhân) thành
Remote Agent (Vertex AI)(hoặcRemote Agent Engine). - Nhập Mã dự án và Vị trí (
us-central1) trên Google Cloud, sau đó nhấp vào Load Remote Agents (Tải tác nhân từ xa). Thao tác này sẽ tải các tác nhân được triển khai cho dự án của bạn. - Chọn tác nhân
appđã triển khai trong trình đơn thả xuống Chọn công cụ rồi nhấp vào Lưu và áp dụng chế độ cài đặt. - Trong hộp trò chuyện, hãy nhập một truy vấn có mục tiêu (chẳng hạn như tìm nạp các vấn đề hoặc kho lưu trữ gần đây của bạn):
(Hoặc thửGet the last 2 GitHub issues reported against my name"List my 3 most recently updated repositories") rồi nhấn Enter. - Quan sát giao diện người dùng của cuộc trò chuyện: Vì nhân viên hỗ trợ chưa có thông tin xác thực cho phiên người dùng của bạn, nên nhân viên hỗ trợ sẽ nhận được một thử thách xác thực và hiển thị thẻ Yêu cầu xác thực trong chuỗi cuộc trò chuyện.
Bước B: Hoàn tất quy trình xin phép bằng OAuth 3 bên
- Một cửa sổ bật lên riêng biệt của trình duyệt sẽ mở ra, chuyển hướng bạn qua Trình quản lý xác thực của Google Cloud đến trang uỷ quyền OAuth của GitHub.
- Xem xét các quyền được yêu cầu rồi nhấp vào Uỷ quyền.
- GitHub sẽ chuyển hướng trở lại Google Cloud, sau đó chuyển hướng cửa sổ bật lên đến
localhostURL gọi lại/validateUserIdcủa bạn. - Dịch vụ gọi lại sẽ xử lý và hoàn tất quá trình bắt tay thông tin đăng nhập.
Bước C: Tiếp tục
- Sau khi cửa sổ bật lên đóng, thẻ trò chuyện gốc sẽ tự động phát hiện việc đóng cửa sổ.
- Giao diện người dùng gửi một tải trọng tiếp tục trở lại tác nhân.
- Tác nhân truy xuất mã thông báo mới trao đổi một cách an toàn từ Trình quản lý xác thực của Google Cloud, thay mặt bạn gọi các công cụ MCP của GitHub và truyền trực tuyến dữ liệu GitHub của bạn trở lại cửa sổ trò chuyện — dữ liệu mà tác nhân không thể tự truy cập.
Bước D: Kiểm tra Nhật ký trên đám mây
Cách xác minh rằng quá trình trao đổi và hoàn tất mã thông báo đã được xử lý một cách an toàn:
- Chuyển đến Trình khám phá nhật ký của Google Cloud Console.
- Tìm nhật ký máy chủ xác nhận việc trích xuất số dùng một lần và xác thực thành công:
INFO:secure-agent-client:Caching consent nonce for session_id: session-xxxxxxx INFO:secure-agent-client:Successfully finalized auth provider credentials. - Kiểm tra nhật ký thời gian chạy của tác nhân: Ngoài ra, bạn có thể xem nhật ký thực thi ngay trong Bảng điều khiển nền tảng tác nhân:
- Chuyển đến Bảng điều khiển thời gian chạy của tác nhân.
- Nhấp vào nhân viên hỗ trợ đã triển khai trong danh sách.
- Chuyển sang thẻ Playground; thao tác này sẽ hiển thị nhật ký tác nhân trực tiếp ở ngăn dưới cùng, cho bạn thấy vòng lặp lý luận của tác nhân, thông tin chi tiết về việc thực thi công cụ và vòng đời truy xuất mã thông báo theo thời gian thực.
10. Dọn dẹp
Để tránh bị tính phí liên tục trên Google Cloud, hãy dọn dẹp các tài nguyên đã triển khai:
# 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
Dọn dẹp tệp trên thiết bị
Nếu muốn, bạn có thể dọn dẹp hoàn toàn môi trường cục bộ:
- Dừng máy chủ uvicorn cục bộ bằng cách nhấn tổ hợp phím Ctrl+C trong dòng lệnh nơi máy chủ đang chạy.
- Xoá các thư mục dự án được tạo trong lớp học lập trình này:
# cd to the correct folder
rm -rf secure-agent-demo client adk-python
11. Xin chúc mừng!
Bạn đã xây dựng và bảo mật thành công một tác nhân thay mặt cho người dùng đã đăng nhập!
Kiến thức bạn học được:
- Danh tính hệ thống của tác nhân: Cách tác nhân hoạt động theo danh tính Tài khoản của chính tác nhân đó để giao tiếp an toàn với cơ sở hạ tầng của GCP, quản lý nhật ký đo từ xa và gọi các API hoàn tất thông tin xác thực.
- Danh tính được uỷ quyền của người dùng: Cách tác nhân yêu cầu uỷ quyền để thay mặt người dùng hành động trên các nền tảng bên ngoài (như GitHub) bằng cách kích hoạt quy trình đồng ý OAuth 3 bên (3LO).
- Tích hợp công cụ an toàn: Cách kết nối Tác nhân ADK với máy chủ Giao thức bối cảnh mô hình (MCP) bằng Trình quản lý xác thực của Google Cloud để tìm nạp mã thông báo người dùng một cách linh động thay vì sử dụng thông tin bí mật được mã hoá cứng.
- Cấu hình chính sách IAM: Cách thiết lập các liên kết quyền chi tiết để uỷ quyền cho cả danh tính của Thời gian chạy tác nhân và tài khoản của riêng bạn trên nhà cung cấp dịch vụ xác thực.
Tài liệu đọc thêm
- Trình quản lý xác thực danh tính của nhân viên hỗ trợ để tìm hiểu về cấu hình và phạm vi của quy trình xác thực.
- Tổng quan về thời gian chạy của tác nhân
- Tài liệu về ADK
- Giao thức ngữ cảnh mô hình
