1. מבוא
סוכן עם פרטי כניסה משלו והרשאה רחבה רואה את הנתונים של כולם. ב-Codelab הזה תבנו סוכן ששולח קריאה ל-API של צד שלישי עם פרטי הכניסה של המשתמש המחובר, כך שהוא רואה בדיוק את מה שהאדם הזה יכול לראות ולא יותר.
אתם תיצרו אותו באמצעות הערכה לפיתוח סוכנים (ADK) של Google ו-Gemini Enterprise.
באופן ספציפי, תלמדו איך לתכנן ארכיטקטורה של זהות כפולה שבה:
- הנציג פועל בשם עצמו (זהות הנציג): באמצעות זהות נציג שמגובה ב-SPIFFE, הנציג מפעיל את Auth Manager, מאחסן נתוני טלמטריה וקורא ל-Google Cloud APIs.
- הנציג פועל בשם המשתמש (זהות שהוקצתה למשתמש): כדי לגשת למשאבים חיצוניים כמו GitHub, הנציג מפעיל תהליך הסכמה של OAuth עם 3 רגליים (3LO) כדי לשלוח שאילתות לכלים בצורה מאובטחת באמצעות פרטי הכניסה של המשתמש.

כדי לעשות את זה, תלמדו איך:
- איך יוצרים סוכן ADK שמתחבר לשרת Model Context Protocol (MCP) של GitHub.
- מעדכנים את הכלי של הנציג מ-PAT (טוקן גישה אישי) סטטי של GitHub לתהליך OAuth עם 3 רגליים (3LO) באמצעות Google Cloud Auth Manager.
- פורסים את הסוכן בצורה מאובטחת ב-Agent Runtime ומקצים זהות לסוכן.
- מגדירים תפקידי IAM כדי לתת לזהות של הנציג גישה למאגר האסימונים בשם המשתמש.
- להבין את התהליך המלא של 3LO לניהול אימות ב-Google Cloud.
דרישות מוקדמות
לפני שמתחילים, חשוב לוודא שיש לכם:
- פרויקט ב-Google Cloud שהחיוב מופעל בו.
- Google Cloud SDK (
gcloudCLI) מותקן ומאומת לפרויקט במחשב המקומי. נדרשת גרסה 586.0.0 ואילך – מריצים אתgcloud components update. - Python בגרסאות 3.10 עד 3.13 מותקנת באופן מקומי.
uvהכלי לניהול חבילות מותקן (pip install uv).- חשבון GitHub כדי לרשום אפליקציית OAuth וליצור טוקנים. אם אין לכם חשבון GitHub, אתם יכולים להשתמש בכל שרת MCP של צד שלישי שתומך ב-OAuth 2.0 תלת-רגלי.
2. הגדרת הפרויקט
1. אימות ב-Google Cloud
במהלך שיעור ה-Lab הזה, תאמתו את הזהות שלכם ב-Google Cloud משורת הפקודה המקומית כדי לוודא שלסביבה שלכם יש את ההרשאות הנדרשות לפריסה ב-Agent Runtime, להקצאת Agent Identity ולהגדרת Auth Manager.
מריצים את הפקודות הבאות כדי להיכנס לחשבון Google Cloud, להגדיר את הפרויקט הפעיל (מחליפים את YOUR_PROJECT_ID במזהה הפרויקט ב-Google Cloud) ולהגדיר את Application Default Credentials (ADC):
gcloud auth login
gcloud config set project YOUR_PROJECT_ID
gcloud auth application-default login
2. הפעלת שירותי Google Cloud הנדרשים
כדי להריץ את שיעור ה-Lab הזה, צריך להפעיל את ממשקי ה-API הנדרשים בפרויקט בענן ב-Google Cloud. מריצים את הפקודה הבאה בטרמינל:
gcloud services enable \
agentidentity.googleapis.com \
agentregistry.googleapis.com \
aiplatform.googleapis.com \
apphub.googleapis.com
יכול להיות שהפקודה הזו תפעל במשך דקה. בסיום, היא תחזור לשורת הפקודה ותאשר שממשקי ה-API פעילים.
3. התקנת Agents CLI והגדרת הפרויקט
agents-cli הוא כלי שורת הפקודה שמשמש ליצירת פיגומים, לניהול, לבדיקה ולפריסה של סוכני ADK ב-Gemini Enterprise. מתקינים אותו באופן מקומי:
uvx google-agents-cli setup
מאמתים את ההתקנה:
agents-cli --help
תפריט העזרה של ה-CLI אמור להופיע ולהציג את הפקודות הזמינות (כמו deploy, run ו-status).
יצירת התבנית הראשונית של הפרויקט. תתחילו עם אב טיפוס מקומי ותשפרו אותו בהמשך לפריסה ב-Agent Runtime:
agents-cli create secure-agent-demo --prototype --yes
הפעולה הזו יוצרת את הספרייה secure-agent-demo שמכילה את קוד הסוכן הבסיסי, יחסי התלות וקובצי הבדיקה.
4. מוסיפים את התוספות הנדרשות ל-ADK
מוסיפים את שני הפרמטרים הנוספים החסרים בקובץ pyproject.toml שנוצר: mcp לערכת הכלים של GitHub, ו-agent-identity ל-Auth Manager שבו משתמשים בהמשך ה-Lab. פותחים את 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): יוצרת מופע של ADKAgentבאמצעות המודלgemini-3.8-flash, מגדירה לוגיקה של ניסיון חוזר של HTTP ומציידת את הסוכן בערכת הכלים של GitHub. - App Wrapper (
app): מכיל את הנציג ברמה הבסיסית (root) בקונטיינרAppשל ADK, כדי שאפשר יהיה לפרוס אותו ב-Agent Runtime.
2. הוספת כלי MCP של GitHub
הסוכן מתחבר ל-GitHub באמצעות Model Context Protocol (MCP). יוצרים קובץ חדש ב-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",
},
)
)
הפונקציה הזו יוצרת כלי שקורא לשרת ה-MCP של GitHub:
- ערכת הכלים של MCP (
McpToolset): מגלה ורושמת באופן דינמי יכולות של GitHub ככלים של סוכנים שניתן להפעיל. - Connection Parameters (
StreamableHTTPConnectionParams): מפנה את ערכת הכלים לשער ה-MCP הציבורי של GitHub. - כותרות הרשאה: הוספה של
GITHUB_TOKENכטוקן למוכ"ז ואכיפה של מצב קריאה בלבד (X-MCP-Readonly: true) ישירות בשכבת התעבורה.
3. בדיקה מקומית באמצעות GitHub PAT (טוקן גישה אישי)
כדי להריץ את הסוכן באופן מקומי עם פרטי כניסה סטטיים:
- יוצרים טוקן גישה אישי מפורט בדף Personal Access Tokens (טוקני גישה אישיים) ב-GitHub:
- לוחצים על יצירת טוקן חדש ונותנים שם לטוקן.
- בקטע Repository access, בוחרים באפשרות All repositories (או בוחרים מאגרים ספציפיים שרוצים לבדוק).
- בקטע Permissions > Repositories, לוחצים על +Add permissions ובוחרים באפשרויות Contents, Issues ו-Pull requests כדי להגדיר אותן כ-Read-only (האפשרות Metadata מוגדרת באופן אוטומטי כ-Read-only).
- לוחצים על Generate token (יצירת טוקן) ומעתיקים את ערך הטוקן שנוצר. (לחלופין, אם משתמשים בטוקן גישה אישי (קלאסי), בוחרים את ההיקף
repo.)
- מגדירים אותו בסביבה:
export GITHUB_TOKEN="your_github_pat_here" - עוברים לתיקייה
secure-agent-demo(אם אתם עדיין לא נמצאים בה) ומפעילים את סביבת הניסויים המקומית:cd secure-agent-demo agents-cli playground - פותחים את ממשק ה-Playground ובוחרים את התיקייה
appמהתפריט הנפתח. בתיבת הצ'אט, נסו הנחיה ממוקדת כמו"Get the last 2 GitHub issues reported against my name"או"List my 3 most recently updated repositories", וודאו שהנציג קורא לערכת הכלים של GitHub MCP ומחזיר את נתוני GitHub שלכם. כדי לבדוק אם הנציג באמת משתמש בטוקן ה-PAT שלכם כדי לבצע פעולות בשמכם, נסו לשאול אותו על המאגרים הפרטיים או על התרומות שלכם.
4. הגדרת Auth Manager
אמנם נוח להשתמש בפרטי כניסה סטטיים בתוך הקוד (כמו PAT) כשיוצרים אב טיפוס, אבל זה חושף את האפליקציות בסביבת הייצור לדליפה של פרטי כניסה, לזמן השבתה בגלל רענון ידני של טוקנים ולחוסר בבקרת גישה מבוססת-ענן.
כדי לפתור את הבעיה הזו, Google Cloud מספק את מנהל האימות של Agent Identity. מנהל האימות של Agent Identity הוא כספת פרטי כניסה שנועדה להגן על פרטי הכניסה. הוא מאפשר לסוכנים לבצע אימות באמצעות מפתח API או מזהה לקוח וסוד של OAuth, או בשם משתמש באמצעות הקצאת OAuth באמצעות אסימוני גישה של משתמשי קצה.
ב-Auth Manager, אתם מגדירים ספקי אימות שקובעים את סוג האימות ואת פרטי הכניסה לאפליקציות ספציפיות של צד שלישי. ספקי האימות הם אזוריים, והאזור חייב להתאים לאזור שבו אתם פורסים את הנציג. תהליך העבודה מקצה לקצה של Auth Manager פועל באופן הבא:

- יירוט דינמי של הסכמה: כשהנציג מנסה להפעיל כלי בשם המשתמש, ה-ADK בודק אם יש פרטי כניסה תקינים ב-Auth Manager. אם לא קיים טוקן, Auth Manager מחזיר כתובת URL להרשאה כדי להתחיל תהליך הסכמה של OAuth עם 3 רגליים (3LO).
- אחסון מאובטח בכספת: אחרי שמשתמש הקצה מאשר את האפליקציה, Auth Manager מיירט באופן אוטומטי את הקריאה החוזרת (callback) של OAuth ומאחסן את טוקני הגישה וטוקני הרענון של המשתמש בכספת מאובטחת של פרטי כניסה שמנוהלת על ידי Google.
- מחזור חיים אוטומטי של טוקנים: Auth Manager מנהל באופן מלא את התפוגה והרוטציה של הטוקנים ברקע, כך שאין צורך בלוגיקה ידנית לרענון הטוקנים או בזמן השבתה.
- הפעלת כלים ללא סודות: בפעולות הבאות, הנציג (שמאמת באמצעות זהות הנציג שלו ב-SPIFFE) מבקש באופן דינמי את טוקן הגישה שהמשתמש העניק לו מ-Auth Manager בזמן הריצה, וכך הקוד של הלקוח ושל הנציג נשארים ללא סודות בכלל.
שלב א': הגדרת GitHub כספק אימות
מריצים את הפקודה הבאה של gcloud כדי ליצור ספק אימות של GitHub בפרויקט בענן ב-Google Cloud. אתם מספקים את מזהה הלקוח והסוד מאוחר יותר: 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"
מתארים את הספק כדי לאחזר את כתובת ה-URL להפניה אוטומטית ב-OAuth שנוצרה:
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.
שלב ב': רישום אפליקציית OAuth ב-GitHub
- עוברים אל דף ההגדרות למפתחים ב-GitHub, בוחרים באפשרות OAuth Apps בסרגל הצד הימני ולוחצים על New OAuth App (או על Register a new application אם לא יצרתם אפליקציה בעבר).
- ממלאים את השדות בטופס הבקשה ל-OAuth:
- שם האפליקציה: מזינים שם לאפליקציה (לדוגמה,
secure-agent-demo). - כתובת ה-URL של דף הבית: מזינים את כתובת ה-URL של אפליקציית החזית (
http://localhost:8501ליצירת אב טיפוס מקומי. אפשר לעדכן אותה לכתובת ה-URL שנפרסה בסביבת הייצור). - תיאור האפליקציה: אופציונלי (אפשר להשאיר את השדה הזה ריק).
- כתובת URL להתקשרות חזרה לצורך הרשאה (URI להפניה אוטומטית): מדביקים את ה-
redirectUrlשאוחזר בשלב א'. - Enable Device Flow (הפעלת תהליך המכשיר): משאירים את התיבה לא מסומנת.
- שם האפליקציה: מזינים שם לאפליקציה (לדוגמה,
- לוחצים על Register application.
- בדף האפליקציה שמופיע, מעתיקים את מזהה הלקוח, לוחצים על יצירת סוד לקוח חדש ומעתיקים את סוד הלקוח שנוצר. שומרים את שני הערכים – תשתמשו בהם בתור
YOUR_GITHUB_CLIENT_IDו-YOUR_GITHUB_CLIENT_SECRETבשלב הבא.
שלב ג': הוספת פרטי הכניסה של 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 יוגדר באופן מלא עם פרטי הכניסה של אפליקציית GitHub OAuth, ו-Google Cloud יוגדר לפעול ככספת מאובטחת שמטפלת בהסכמה ובמחזורי החיים של האסימונים.
5. מעבר מאסימון PAT ל-Auth Manager
אחרי שמנהל האימות מוגדר במלואו, השלב הבא הוא לעדכן את קוד הכלי של הנציג. מחליפים את התוכן של secure-agent-demo/app/tools.py בקוד הבא.
👉 מחליפים את מזהה הפרויקט והמיקום במשתנה OAUTH_PROVIDER_NAME שבהמשך.
# 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 מבקש קודם מ-Auth Manager את הטוקן של המשתמש. אם עדיין אין טוקן, הוא מבקש מהמשתמש להיכנס לחשבון במקום להיכשל. ה-GITHUB_TOKEN שמוטמע בקוד נעלם לגמרי.
6. פריסת הסוכן ב-Agent Runtime
עכשיו, אחרי שעדכנו את כלי ה-MCP של GitHub כך שישתמש ב-Auth Manager, השלב הבא הוא לפרוס את הסוכן ב-Agent Runtime. כשפורסים את הסוכן עם Agent Identity, המערכת מקצה לו מזהה SPIFFE ייחודי.
מאתחלים את הגדרות הפריסה של הפרויקט. מוודאים שהטרמינל נמצא בתיקיית השורש של הפרויקט 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"
פריסת הסוכן עם Agent Identity
פריסה באמצעות adk deploy agent_engine. כך הסוכן מקבל זהות סוכן משלו – זהות קריפטוגרפית ייחודית שמגובה ב-SPIFFE ושייכת לפריסה הזו. הסוכן משתמש בזהות הזו כדי לאמת את עצמו מול Auth Manager ושירותים אחרים של 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 מדפיס את שם המשאב שנפרס. שימו לב לערך reasoningEngines/ENGINE_ID, כי תצטרכו אותו כדי לאשר את הסוכן ולכוון אליו את לקוח ממשק המשתמש.
אישור של Agent Identity
עכשיו, כשהסוכן פועל בענן, הוא צריך הרשאה כדי לגשת לאחסון פרטי הכניסה ששמורים ב-Auth Manager. כברירת מחדל, לזהות ה-SPIFFE של הנציג אין גישה למשאבי ענן חיצוניים.
מריצים את הפקודה הבאה של gcloud כדי להקצות את התפקיד roles/agentidentity.user לזהות של הנציג במשאב של ספק האימות. כך הסוכן מקבל בדיוק את ההרשאות שהוא צריך כדי לבקש אסימוני משתמשים מהכספת, ולא יותר מזה.
# 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"
👉 אפשר גם לקבל את הערך המלא של --member="principal://..." של הסוכן שנפרס ממסוף Google Cloud: נכנסים למסוף Agent Runtime, בוחרים את הסוכן שנפרס, עוברים לכרטיסייה Identity ומעתיקים את המחרוזת המלאה של principal://... ישירות.
עכשיו נותנים לחשבון שלכם את אותו תפקיד בספק. לקוח ממשק המשתמש שאתם מריצים בשלב הבא קורא ל-API של סיום תהליך האימות באמצעות Application Default Credentials, כך שבלי זה תהליך ההסכמה נכשל עם שגיאה 403 ב-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. הסבר על תהליך ההסכמה של 3LO
עכשיו, כשהסוכן פרוס ב-Agent Runtime עם Agent Identity מאובטח, השלב הבא הוא לספק ממשק קצה (frontend) מותאם אישית כדי שהמשתמשים יוכלו לשוחח איתו בצ'אט. חשוב מכך, מנהל האימות של Google Cloud דורש גורם מטפל בקריאה חוזרת של אפליקציית לקוח כדי להשלים את לולאת האימות.
למרות ש-Google Cloud Auth Manager מנהל באופן מאובטח את פרטי הכניסה של המשתמשים בתוך כספת, הוא לא יכול להשלים את החלפת האסימונים של OAuth בעצמו. לחיצת היד של 3LO מסתמכת על אפליקציית הלקוח כדי לגשר על הפער:
- כשהמשתמש מאשר את אפליקציית GitHub, GitHub מפנה אותו בחזרה אל של ספק האימות של Agent Identity
redirectUrl. - לאחר מכן, מנהל האימות מפנה את החלון הקופץ בדפדפן של המשתמש בחזרה אל כתובת URL להחזרה (callback) בצד הלקוח (
continue_uri). - אפליקציית הלקוח צריכה ליירט את ההפניה האוטומטית הזו, לקרוא את ה-nonce מקובצי ה-Cookie של הדפדפן ולקרוא לנקודת הקצה
credentials:finalizeשל Google Cloud כדי להשלים את לחיצת היד. - אחרי שהלקוח משלים את ההחלפה, Google Cloud שומרת את האסימון באופן מאובטח בכספת של ספק האימות, וכך מאפשרת לנציג לקרוא לכלי של GitHub.
בלי הלקוח המותאם אישית שמארח את נקודת הקצה (endpoint) של ה-callback, לחיצת היד לא תושלם והכספת לא תוכל לאחסן את פרטי הכניסה.
תהליך OAuth 3LO האינטראקטיבי כולל כמה שכבות. זהו מחזור החיים המלא של הביצוע של בקשת כלי. נפרט על כך בהסבר שבהמשך ובשלב הבא.
👉 כדי להגדיל את התמונה, לוחצים עליה.
תחומי האחריות העיקריים של הלקוח בתהליך לחיצת היד
- העברת אתגר ההסכמה (שלבים 5-6): הנציג שולח
adk_request_credentialשכולל את כתובת ה-URL של ההסכמה ופריט לשימוש חד-פעמי. הלקוח פותח את החלון הקופץ ושומר את הפריט לשימוש חד-פעמי כקובץ Cookie. - אירוח של קריאה חוזרת (callback) להפניה אוטומטית (שלבים 10-11):
/validateUserId, שבה מנהל האימות שולח את החלון הקופץ אחרי קבלת הסכמה. - סיום תהליך יצירת הטוקן (שלבים 12-14): משלבים את מצב האימות מההפניה האוטומטית עם המספר החד-פעמי שנשמר במטמון וקוראים ל-
credentials:finalize, שמאחסן את הטוקן בכספת.
יצירת לקוח משלכם
אין צורך לכתוב את הלקוח הזה בשביל ה-Lab – בשלב הבא מריצים לקוח מובנה מראש. כשמטמיעים את זה באפליקציה, אלה שני קובצי העזר שצריך לעבוד איתם:
- עדכון האפליקציה בצד הלקוח במסמכי התיעוד של Auth Manager, שכוללים טיפול באתגר ההסכמה וקריאה ל-
credentials:finalize. - הלקוח לדוגמה שניתן להפעלה במאגר adk-python. כדאי לקרוא את
main.pyכדי לראות הטמעה מלאה ופעילה של שלוש האחריויות שלמעלה.
8. הפעלת לקוח ממשק המשתמש באופן מקומי
כפי שמתואר בתרשים הרצף של תהליך ההסכמה של 3LO, מנהל האימות מפנה את חלון הדפדפן חזרה לנקודת קצה (endpoint) של קריאה חוזרת (callback) בצד הלקוח. הלקוח לדוגמה במאגר adk-python מארח את נקודת הקצה הזו בכתובת /validateUserId. כדי להוריד ולהריץ אותו באופן מקומי, פועלים לפי השלבים הבאים.
הורדת קובצי הלקוח
הספרייה contributing/samples/integrations/gcp_auth/client ב-adk-python מכילה שלושה נכסים עיקריים:
-
main.py: הקצה העורפי של FastAPI שמתחבר ל-Agent Engine שנפרס ומארח את נקודת הקצה (endpoint) של הקריאה החוזרת (callback) של/validateUserIdכדי להשלים את טוקני ה-OAuth. static/: קובצי ה-HTML וה-JavaScript של ממשק המשתמש של הצ'אט בדפדפן.-
requirements.txt: חבילות Python שנדרשות כדי להריץ את שרת הלקוח.
adk-python הוא מאגר גדול, לכן צריך להשתמש בתכונה sparse checkout של Git כדי להוריד רק את התיקייה contributing/samples/integrations/gcp_auth/client:
- קודם, עולים ספרייה אחת מחוץ ל-
secure-agent-demoכדי לשכפל את הלקוח לתיקייה מקבילה:cd .. - מריצים את הפקודות הבאות כדי לשכפל את המטא-נתונים של המאגר בלי להוריד את כל הקבצים (
--no-checkout), להגביל את נתיב ה-checkout ל-contributing/samples/integrations/gcp_auth/clientולבצע checkout רק לתיקייה הזו: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 שנפרס (YOUR_ENGINE_ID), ואז מפעילים את שרת FastAPI המקומי ביציאה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 - מוודאים שהשרת הופעל בהצלחה ומאזין ב-
http://localhost:8501.
9. בדיקת תהליך OAuth
עכשיו, אחרי שכל השירותים נפרסו, הקישורים של IAM הוגדרו ומשתני הסביבה הוגדרו, אתם מוכנים לבדוק את תהליך ההרשאה המאובטח מקצה לקצה שהוקצה למשתמשים.
שלב א': הפעלת הכלי
- פותחים כרטיסייה בדפדפן ועוברים לכתובת ה-URL של הלקוח:
http://localhost:8501. - בחלונית השמאלית, בקטע Configuration Settings, מגדירים את Agent Type לערך
Remote Agent (Vertex AI)(אוRemote Agent Engine). - מזינים את מזהה הפרויקט ואת המיקום (
us-central1) ב-Google Cloud, ואז לוחצים על טעינת סוכנים מרוחקים. הפעולה הזו טוענת את הנציגים שנפרסו בפרויקט. - בתפריט הנפתח Select Engine, בוחרים את סוכן
appשנפרס ולוחצים על Save & Apply Settings. - בתיבת הצ'אט, מקלידים שאילתה ייעודית (למשל, שליפת הבעיות או המאגרים האחרונים):
(אוGet the last 2 GitHub issues reported against my name"List my 3 most recently updated repositories") ומקישים על Enter. - בודקים את ממשק המשתמש של הצ'אט: לנציג עדיין אין פרטי כניסה לסשן של המשתמש, ולכן הוא מקבל אתגר אימות ומציג את הכרטיס "נדרש אימות" בשרשור השיחה.
שלב ב': השלמת ההסכמה ל-OAuth תלת-רגלי (3-legged OAuth)
- ייפתח חלון קופץ נפרד בדפדפן, שיפנה אתכם דרך Auth Manager של Google Cloud לדף ההרשאה של GitHub OAuth.
- בודקים את ההרשאות הנדרשות ולוחצים על אישור.
- מערכת GitHub תפנה חזרה אל Google Cloud, שתפנה את החלון הקופץ אל
localhostכתובת ה-URL להחזרה (callback)/validateUserId. - שירות הקריאה החוזרת מעבד את לחיצת היד של פרטי הכניסה ומשלים אותה.
שלב ג': המשך
- אחרי שהחלון הקופץ נסגר, כרטיסיית הצ'אט הראשית מזהה את הסגירה באופן אוטומטי.
- ממשק המשתמש שולח מטען ייעודי (payload) של המשך לנציג.
- הנציג מאחזר את האסימון החדש שהוחלף באופן מאובטח מ-Google Cloud Auth Manager, קורא לכלי ה-MCP של GitHub בשמכם ומעביר את נתוני GitHub ישירות לחלון הצ'אט – נתונים שהנציג לא היה יכול להגיע אליהם בעצמו.
שלב ד': בדיקת היומנים ב-Cloud
כדי לוודא שהחלפת האסימונים והשלמת התהליך בוצעו באופן מאובטח:
- נכנסים לדף Logs Explorer במסוף Google Cloud.
- מאתרים את יומני השרת שמאשרים את חילוץ המספר החד-פעמי ואת האימות המוצלח:
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
ניקוי קבצים מקומיים
אופציונלי: כדי לנקות לגמרי את הסביבה המקומית:
- עוצרים את שרת ה-uvicorn המקומי על ידי לחיצה על Ctrl+C בטרמינל שבו הוא פועל.
- מסירים את ספריות הפרויקט שנוצרו במהלך שיעור ה-Lab הזה:
# cd to the correct folder
rm -rf secure-agent-demo client adk-python
11. מעולה!
יצרתם ואבטחתם בהצלחה סוכן שפועל בשם המשתמש המחובר.
מה למדתם:
- זהות המערכת של הסוכן: איך הסוכן פועל במסגרת זהות החשבון שלו כדי להתממשק באופן מאובטח עם התשתית של GCP, לנהל את יומני הטלמטריה ולשלוח קריאות לממשקי API של השלמת פרטי הכניסה.
- זהות מואצלת של משתמש: איך הסוכן מבקש הרשאה לפעול בשם המשתמש בפלטפורמות חיצוניות (כמו GitHub) על ידי הפעלת תהליך הסכמה של OAuth עם 3 רגליים (3LO).
- שילוב כלים מאובטחים: איך מחברים סוכני ADK לשרתי Model Context Protocol (MCP) באמצעות Google Cloud Auth Manager כדי לאחזר באופן דינמי אסימוני משתמשים במקום להשתמש בסודות בתוך הקוד.
- הגדרת מדיניות IAM: איך מגדירים קישורי הרשאות מפורטים כדי לאשר גם את הזהות של Agent Runtime וגם את החשבון שלכם אצל ספק האימות.
קריאה נוספת
- מנהל האימות של Agent Identity כדי להבין את ההגדרות וההיקפים של תהליך האימות.
- סקירה כללית על Agent Runtime
- מסמכי תיעוד של ADK
- פרוטוקול הקשר מודלי
