כדי לנהל את הרשאות הגישה של סוכנים שנפרסו ב-Gemini Enterprise Agent Platform, צריך להגדיר אימות והרשאה גם לסוכן שניגש למשאבים חיצוניים וגם ללקוחות חיצוניים שניגשים לסוכן. במאמר הזה מוסבר על שיטות האימות הזמינות, כולל זהות הסוכן, חשבונות שירות, מפתחות API ולקוחות OAuth.
יש סוגים שונים של שיטות אימות שזמינות למצבי גישה שונים:
| שיטת אימות | תרחיש לדוגמה | מידע על שיטת האימות הזו |
|---|---|---|
| Agent Identity (גרסת טרום-השקה) | לגשת למקורות נתונים ישירות מתוך סוכן. | סוכן שנפרס עם Agent Identity יכול לגשת למשאבים בהתאם להרשאות ה-IAM שאתם נותנים לו. |
| חשבונות שירות | לגשת למקורות נתונים ישירות מתוך הסוכן. | לסוכנים שנפרסו יש גישה לכל המשאבים שלחשבון השירות שלהם יש הרשאה לגשת אליהם. |
| מפתחות API | שליחת בקשות לנקודות קצה (endpoints) באמצעות מפתחות API מתוך נציג. | לכן כדאי לוודא שממשק ה-API שבו תרצו להשתמש תומך במפתחות API, לפני שתשתמשו בשיטת האימות הזו. |
| מזהה לקוח ב-OAuth | לטפל בחשבונות משתמשים, ברישום, בהתחברות או בהרשאה של משתמשי הקצה של הנציג. | הסוכן צריך לבקש ולקבל הסכמה מהמשתמש. |
זהות הסוכן
אם השתמשתם בזהות של הנציג כדי להגדיר את הזהות וההרשאות של הנציג, קראו את המאמר שימוש בזהות של הנציג עם Agent Runtime כדי ללמוד איך לנהל את בקרת הגישה למשאבים.
חשבונות שירות
אם השתמשתם בחשבונות שירות כדי להגדיר את הזהות וההרשאות של הסוכן, סוכנים שאתם פורסים ב-Agent Runtime פועלים באמצעות סוכן השירות של פלטפורמת AI מנוע חשיבה רציונלית או באמצעות חשבון השירות בהתאמה אישית.
סוכן שירות של מנוע החשיבה הרציונלית בפלטפורמת AI
חשבון השירות AI Platform Reasoning Engine Service Agent משתמש בפורמט service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com.
לחשבון השירות יש תפקיד סוכן שירות של מנוע החשיבה הרציונלית ב-Gemini Enterprise Agent Platform (roles/aiplatform.reasoningEngineServiceAgent) שמעניק את הרשאות ברירת המחדל שנדרשות לסוכנים שנפרסו. הרשימה המלאה של הרשאות ברירת המחדל מופיעה במסמכי התיעוד של IAM.
הצגת רשימת התפקידים של נציג שנפרס
המסוף
נכנסים לדף IAM.
בוחרים את הפרויקט שתואם לפרויקט ב- Google Cloud .
מוצאים את חשבון המשתמש שתואם לחשבון השירות שמשמש כזהות של הסוכן.
התפקידים של הסוכן שנפרס מופיעים בעמודה Role.
gcloud
קודם מתקינים ומפעילים את ה-CLI של gcloud. ואז מריצים את הפקודה הבאה:
gcloud projects get-iam-policy PROJECT_ID_OR_NUMBER \
--flatten="bindings[].members" \
--filter="bindings.members:serviceAccount:PRINCIPAL" \
--format="value(bindings.role)"כאשר
-
PROJECT_ID_OR_NUMBERהוא המזהה או המספר של הפרויקט, ו- -
PRINCIPALמבוסס על חשבון השירות ששימש לפריסת הסוכן ב-Runtime.
לפרטים נוספים, קראו את המסמכים של IAM ואת ההפניות ל-CLI.
Python
קודם מתקינים את ספריית הלקוח באמצעות הפקודה הבאה:
pip install google-api-python-clientלאחר מכן מאמתים את הזהות ומריצים את הפקודה הבאה כדי להציג את רשימת התפקידים של הסוכן שנפרס:
from google.cloud import resourcemanager_v3
from google.iam.v1 import iam_policy_pb2
project_id = "PROJECT_ID"
principal = "PRINCIPAL"
crm_service = resourcemanager_v3.ProjectsClient()
policy = crm_service.get_iam_policy(iam_policy_pb2.GetIamPolicyRequest(
resource=f"projects/{project_id}"
))
for binding in policy.bindings:
for member in binding.members:
if principal in member:
print(binding.role)
כאשר PRINCIPAL מבוסס על חשבון השירות ששימש לפריסת הנציג ב-Runtime.
הקצאת תפקידים לנציג שנפרס
Console (מומלץ)
נכנסים לדף IAM.
בוחרים את הפרויקט שמתאים לפרויקט ב- Google Cloud .
מוצאים את חשבון המשתמש שתואם לחשבון השירות שמשמש כזהות של הנציג.
מוסיפים את התפקידים הנדרשים לחשבון הראשי: לוחצים על כפתור העריכה, מוסיפים את התפקידים ולוחצים על כפתור השמירה.
gcloud
קודם מתקינים ומפעילים את ה-CLI של gcloud. ואז מריצים את הפקודה הבאה:
gcloud projects add-iam-policy-binding PROJECT_ID --member=PRINCIPAL --role=ROLE_NAMEכאשר
-
PRINCIPALמבוסס על חשבון השירות ששימש לפריסת הסוכן ב-Runtime. -
ROLE_NAME: שם התפקיד שרוצים לתת. רשימה של תפקידים מוגדרים מראש מופיעה במאמר הסבר על תפקידים.
לפרטים נוספים, קראו את המסמכים של IAM ואת ההפניות ל-CLI.
Python
לא מומלץ לכתוב קוד Python משלכם כדי להקצות או לבטל תפקידים לסוכנים שנפרסו. במקום זאת, מומלץ להשתמש במסוף Google Cloud או ב-gcloud לפעולות חד-פעמיות, או ב-Terraform לניהול פרוגרמטי של בקרת הגישה ב-IAM. אם אתם רוצים או צריכים לעשות את זה ב-Python, תוכלו להיעזר במסמכי התיעוד של ספריית הלקוח של IAM.
ביטול תפקידים של נציג פרוס
Console (מומלץ)
נכנסים לדף IAM.
בוחרים את הפרויקט שתואם לפרויקט ב- Google Cloud .
מוצאים את חשבון המשתמש שתואם לחשבון השירות שמשמש כזהות של הסוכן.
כדי לבטל את התפקידים של המשתמש, לוחצים על כפתור העריכה, מסירים את התפקידים הרלוונטיים ולוחצים על כפתור השמירה.
gcloud
קודם מתקינים ומפעילים את ה-CLI של gcloud. ואז מריצים את הפקודה הבאה:
gcloud projects remove-iam-policy-binding PROJECT_ID --member=PRINCIPAL --role=ROLE_NAMEכאשר
-
PRINCIPALמבוסס על חשבון השירות ששימש לפריסת הסוכן ב-Runtime. -
ROLE_NAME: שם התפקיד שרוצים לבטל. רשימה של תפקידים מוגדרים מראש מופיעה במאמר הסבר על תפקידים.
לפרטים נוספים, קראו את המסמכים של IAM ואת ההפניות ל-CLI.
Python
לא מומלץ לכתוב קוד Python משלכם כדי להקצות או לבטל תפקידים לסוכנים שנפרסו. במקום זאת, מומלץ להשתמש במסוף Google Cloud או ב-gcloud לפעולות חד-פעמיות, או ב-Terraform לניהול פרוגרמטי של בקרת הגישה ב-IAM. אם אתם רוצים או צריכים לעשות את זה ב-Python, תוכלו להיעזר במסמכי התיעוד של ספריית הלקוח של IAM.
מפתחות API
מפתחות API משתמשים בסודות, שמכילים גרסה אחת או יותר של סוד, יחד עם מטא-נתונים כמו תוויות ומידע על שכפול. המטען הייעודי (payload) בפועל של סוד מאוחסן בגרסת סוד. הסודות מנוהלים (באמצעות Secret Manager) ברמת הפרויקט, ואפשר לשתף אותם בין הסוכנים שנפרסו. כדי להציג את הסודות שמתאימים לנציג ב-Secret Manager, אפשר להוסיף תוויות ולהשתמש בהן לסינון.
יצירת סוד
המסוף
נכנסים לדף Secret Manager.
בדף Secret Manager, לוחצים על Create Secret.
בשדה Name, מזינים שם לסוד (לדוגמה,
my-secret).אופציונלי: כדי להוסיף גם גרסת סוד כשיוצרים את הסוד הראשוני, בשדה Secret value מזינים ערך לסוד (לדוגמה,
abcd1234).עוברים אל תוויות ולוחצים על הוספת תווית.
כדי ליצור תווית, מזינים מפתח ואת הערך המתאים לו.
לוחצים על Create secret.
gcloud
קודם מתקינים ומפעילים את ה-CLI של gcloud. ואז מריצים את הפקודות הבאות:
gcloud secrets create SECRET_ID --replication-policy="automatic"gcloud secrets versions add SECRET_ID --data-file="FILE_PATH"
כאשר
-
SECRET_IDהוא המזהה של הסוד או המזהה המלא של הסוד. -
FILE_PATHהוא הנתיב המלא (כולל שם הקובץ) לקובץ שמכיל את פרטי הגרסה.
פרטים נוספים זמינים במסמכי התיעוד של Secret Manager ליצירת סוד וגרסת סוד, או במאמרי העזרה של ה-CLI ליצירת סוד וגרסת סוד בהתאמה.
Python
קודם מתקינים את ספריית הלקוח באמצעות הפקודה הבאה:
pip install google-cloud-secret-managerלאחר מכן מאמתים את הזהות ומריצים את הפקודה הבאה:
from google.cloud import secretmanager
import google_crc32c
client = secretmanager.SecretManagerServiceClient()
secret = client.create_secret(request={
"parent": "projects/PROJECT_ID",
"secret_id": "SECRET_ID",
"secret": { # google.cloud.secretmanager_v1.types.Secret
# Required. The replication policy cannot be changed after the Secret has been created.
"replication": {"automatic": {}},
# Optional. Labels to associate with the secret.
"labels": {"type": "api_key", "provider": "anthropic"},
# Optional. The secret's time-to-live in seconds with format (e.g.,
# "900s" for 15 minutes). If specified, the secret versions will be
# automatically deleted upon reaching the end of the TTL period.
"ttl": "TTL",
},
})
anthropic_api_key = "API_KEY" # The secret to be stored.
payload_bytes = anthropic_api_key.encode("UTF-8")
# Optional. Calculate payload checksum.
crc32c = google_crc32c.Checksum()
crc32c.update(payload_bytes)
version = client.add_secret_version(request={
"parent": secret.name,
"payload": {
"data": payload_bytes,
"data_crc32c": int(crc32c.hexdigest(), 16), # Optional.
},
})
print(f"Added secret version: {version.name}")
קבלת סוד
המסוף
נכנסים לדף Secret Manager.
בדף Secret Manager, לוחצים על השם של הסוד שרוצים לתאר.
בדף Secret detail מופיע מידע על הסוד.
gcloud
קודם מתקינים ומפעילים את ה-CLI של gcloud. ואז מריצים את הפקודה הבאה:
gcloud secrets versions describe VERSION_ID --secret=SECRET_IDכאשר
-
VERSION_IDהוא המזהה של גרסת הסוד, ו- -
SECRET_IDהוא המזהה של הסוד או המזהה המלא של הסוד.
פרטים נוספים זמינים במסמכי התיעוד של Secret Manager או בחומר העזר בנושא CLI.
Python
קודם מתקינים את ספריית הלקוח באמצעות הפקודה הבאה:
pip install google-cloud-secret-managerלאחר מכן מאמתים את הזהות ומריצים את הפקודה הבאה:
from google.cloud import secretmanager
client = secretmanager.SecretManagerServiceClient()
name = client.secret_path("PROJECT_ID", "SECRET_ID")
response = client.get_secret(request={"name": name})
הצגת רשימת הסודות
המסוף
נכנסים לדף Secret Manager.
בטבלה Secrets, לוחצים על השדה Filter.
בוחרים מאפיין סינון ואת הערך המתאים לו, לדוגמה
Location:asia-east1.הטבלה מסוננת באופן אוטומטי על סמך הערכים שהוזנו.
(אופציונלי) כדי לסנן גרסאות של סודות: בוחרים סוד כדי לגשת לגרסאות שלו, ואז משתמשים באפשרות Filter בטבלה Versions.
gcloud
קודם מתקינים ומפעילים את ה-CLI של gcloud.
כדי להציג את כל הסודות של פרויקט, מריצים את הפקודה הבאה:
gcloud secrets list --filter="FILTER"כאשר FILTER הוא מחרוזת (למשל name:asecret OR name:bsecret) או ביטויים רגולריים (למשל name ~ "secret_ab.*").
כדי להציג את כל הגרסאות של סוד, מריצים את הפקודה הבאה:
gcloud secrets versions list SECRET_IDכאשר SECRET_ID הוא המזהה של הסוד או המזהה המלא של הסוד.
לפרטים נוספים, אפשר לעיין במסמכי התיעוד של Secret Manager בנושא סינון סודות והצגת רשימה של גרסאות סודיות, או במאמרי העזרה של ה-CLI בנושא הצגת רשימה של סודות וגרסאות סודיות בהתאמה.
Python
קודם מתקינים את ספריית הלקוח באמצעות הפקודה הבאה:
pip install google-cloud-secret-managerלאחר מכן מאמתים את הזהות ומריצים את הפקודה הבאה:
from google.cloud import secretmanager
client = secretmanager.SecretManagerServiceClient()
for secret in client.list_secrets(request={
"parent": "projects/PROJECT_ID",
"filter": "FILTER", # e.g. "labels.provider=anthropic"
}):
print(f"Found secret: {secret.name}")
עדכון סוד
המסוף
נכנסים לדף Secret Manager.
בדף Secret Manager, מסמנים את התיבה לצד שם הסוד.
אם החלונית Info Panel סגורה, לוחצים על Show Info Panel כדי להציג אותה.
בחלונית המידע, לוחצים על הכרטיסייה תוויות.
לוחצים על הוספת תווית ומזינים מפתח וערך לתווית.
לוחצים על Save.
gcloud
קודם מתקינים ומפעילים את ה-CLI של gcloud. ואז מריצים את הפקודה הבאה:
gcloud secrets update SECRET_ID --update-labels=KEY=VALUEכאשר
-
SECRET_IDהוא המזהה של הסוד או המזהה המלא של הסוד, -
KEYהוא מפתח התווית, ו- -
VALUEהוא הערך התואם של התווית.
פרטים נוספים זמינים במאמרי העזרה של Secret Manager או במאמרי העזרה של CLI.
Python
קודם מתקינים את ספריית הלקוח באמצעות הפקודה הבאה:
pip install google-cloud-secret-managerלאחר מכן מאמתים את הזהות ומריצים את הפקודה הבאה:
from google.cloud import secretmanager
client = secretmanager.SecretManagerServiceClient()
name = client.secret_path("PROJECT_ID", "SECRET_ID")
response = client.update_secret(request={
"secret": {
"name": name,
"labels": {"type": "api_key", "provider": "anthropic"}, # updated labels
},
"update_mask": {"paths": ["labels"]},
})
print(f"Updated secret: {response.name}")
מחיקת סוד
המסוף
נכנסים לדף Secret Manager.
בדף Secret Manager, בעמודה Actions של הסוד, לוחצים על View more.
בתפריט, לוחצים על מחיקה.
בתיבת הדו-שיח Delete secret, מזינים את שם הסוד.
לוחצים על הכפתור Delete secret.
gcloud
קודם מתקינים ומפעילים את ה-CLI של gcloud.
כדי למחוק גרסה של סוד, מריצים את הפקודה הבאה:
gcloud secrets versions destroy VERSION_ID --secret=SECRET_IDכאשר
-
VERSION_IDהוא שם המשאב של גרסת הסוד, ו- -
SECRET_IDהוא המזהה של הסוד או המזהה המלא של הסוד.
כדי למחוק סוד ואת כל הגרסאות שלו, מריצים את הפקודה הבאה:
gcloud secrets delete SECRET_IDכאשר SECRET_ID הוא המזהה של הסוד או המזהה המלא של הסוד
לפרטים נוספים, קראו את המאמרים בנושא מחיקת סוד והשמדת גרסת סוד במסמכי התיעוד של Secret Manager, או את המאמרים בנושא מחיקת סוד והשמדת גרסת סוד במסמכי העזרה של CLI.
Python
קודם מתקינים את ספריית הלקוח באמצעות הפקודה הבאה:
pip install google-cloud-secret-managerלאחר מכן מאמתים את הזהות ומריצים את הפקודה הבאה:
from google.cloud import secretmanager
client = secretmanager.SecretManagerServiceClient()
name = client.secret_path("PROJECT_ID", "SECRET_ID")
client.delete_secret(request={"name": name})
לקוחות ופרטי כניסה של OAuth
מזהה הלקוח משמש לזיהוי של נציג אחד בשרתי OAuth של Google. אם הנציג פועל בכמה פלטפורמות, לכל פלטפורמה צריך להיות מזהה לקוח משלה. באופן כללי, כדי לשלב נציג שמבוסס על OAuth, צריך לבצע את הפעולות הבאות:
יוצרים לקוח OAuth ופרטי כניסה.
שומרים את מזהה הלקוח והסוד ב-Secret Manager. (יצירת סוד).
במהלך הפיתוח, ניגשים לסוד בנציג.
יצירת פרטי כניסה של לקוח OAuth
במסוף Google Cloud , נכנסים לדף Google Auth Platform > Clients.
(אם צריך) אם במסך מופיעה ההודעה Google Auth Platform not configured yet, לוחצים על Get Started וממלאים את Project Configurations. (אפשר לעדכן אותם מאוחר יותר). פרטים נוספים על מוכנות לייצור זמינים במאמר תאימות למדיניות OAuth 2.0.
לוחצים על Create Client.
מגדירים את Application type ל-
Web application.מגדירים את השם של לקוח ה-OAuth בתור
OAUTH_CLIENT_DISPLAY_NAME.בקטע Authorized redirect URIs, מוסיפים את ה-URI של
REDIRECT_URI.בקטע "סודות לקוח", לוחצים על הכפתור "הורדת JSON". קובץ
client_secret.jsonיורד עם התוכן הבא:
{'web': {
'client_id': "CLIENT_ID",
'client_secret': "CLIENT_SECRET",
'project_id': "PROJECT_ID",
'redirect_uris': [REDIRECT_URIs],
'auth_uri': 'https://accounts.google.com/o/oauth2/auth',
'token_uri': 'https://www.googleapis.com/oauth2/v3/token',
'auth_provider_x509_cert_url': 'https://www.googleapis.com/oauth2/v1/certs',
'javascript_origins': "JAVASCRIPT_ORIGINS", # Optional.
}}
- מאחסנים את מזהה הלקוח ואת הסוד ב-Secret Manager, לדוגמה:
from google.cloud import secretmanager
import google_crc32c
import json
client = secretmanager.SecretManagerServiceClient()
secret = client.create_secret(request={
"parent": "projects/PROJECT_ID",
"secret_id": "OAUTH_SECRET_ID", # e.g. "oauth-client-demo"
"secret": {
"labels": {"type": "oauth_client"},
"replication": {"automatic": {}},
},
})
payload_bytes = json.dumps(cred).encode("UTF-8")
crc32c = google_crc32c.Checksum()
crc32c.update(payload_bytes)
client.add_secret_version(request={
"parent": secret.name,
"payload": {
"data": payload_bytes,
"data_crc32c": int(crc32c.hexdigest(), 16),
},
})
הצגת רשימה של לקוחות OAuth
במסוף Google Cloud , נכנסים לדף Google Auth Platform > Clients, שבו מופיעים פרטי הכניסה של לקוחות OAuth.
מחיקת לקוח OAuth
במסוף Google Cloud , נכנסים לדף Google Auth Platform > Clients.
בוחרים את פרטי הכניסה של לקוח OAuth שרוצים למחוק ולוחצים על "מחיקה".
מפתחות הצפנה בניהול הלקוח (CMEK)
כברירת מחדל, Google Cloud מצפין באופן אוטומטי נתונים במצב מנוחה באמצעות מפתחות הצפנה שמנוהלים על ידי Google. אם יש לכם דרישות ספציפיות של תאימות או רגולציה שקשורות למפתחות שמגנים על הנתונים שלכם, אתם יכולים להשתמש במפתחות הצפנה בניהול הלקוח (CMEK) בשביל הנציגים שפרסתם.
במאמר CMEK ל-Gemini Enterprise Agent Platform מפורטות הדרישות הכלליות והנחיות לשימוש ב-CMEK עם Gemini Enterprise Agent Platform, כולל:
- הגדרת הפרויקט (חיוב וממשקי API מופעלים)
- יצירת אוספי מפתחות ומפתחות
- ההרשאות שנדרשות
כדי להפעיל את CMEK לנציג, צריך לציין את encryption_spec עם המפתח של Cloud Key Management Service כשיוצרים מכונה של Agent Platform. דוגמאות קוד מופיעות במאמר הגדרת מפתחות הצפנה בניהול הלקוח.
מגבלות
המגבלות הבאות חלות כשמשתמשים ב-CMEK עם Agent Runtime:
אי אפשר להשתמש במפתחות במספר אזורים: יש תמיכה רק במפתחות באזור יחיד. האזור של אוסף המפתחות והמפתח צריך להיות זהה לאזור של המכונה של Agent Platform.
אי אפשר לעדכן את מפתח ההצפנה במכונות CMEK: אחרי שפורסים סוכן עם מפתח CMEK, אי אפשר לשנות את מפתח ההצפנה של הפריסה הזו. כדי להשתמש במפתח חדש, צריך לפרוס מכונה חדשה של Agent Platform.
מטא-נתונים מסוימים ונתונים תפעוליים לא מוצפנים באמצעות המפתח שלכם: CMEK מצפין את נתוני הליבה של הנציג במצב מנוחה. עם זאת, מטא-נתונים מסוימים ונתונים תפעוליים של זמן ריצה לא מוצפנים באמצעות המפתח שלכם. במקום זאת, הם מוצפנים באמצעות הצפנת ברירת המחדל של Google. למשל:
- מטא-נתונים של הסוכן:
- השמות המוצגים
- תיאורים
- נתונים תפעוליים של זמן ריצה:
- כתובות אימייל של חשבונות שירות
- שמות של שיטות מחלקת אובייקטים של נציגים
- משתני סביבה
- מטא-נתונים של הסוכן:
VPC Service Controls (VPC-SC)
כדי לחזק את אבטחת המידע ולצמצם את הסיכונים לזליגת נתונים, Agent Runtime תומך ב-VPC Service Controls.
כשמגדירים את VPC Service Controls, לסוכן שנפרס יש גישה מאובטחת ל-Google APIs ולשירותים של Google, כמו BigQuery API, Cloud SQL Admin API ו-Agent Platform API, כדי לוודא שהפעולה מתבצעת בצורה חלקה בתוך גבולות הגזרה שהגדרתם. חשוב לציין ש-VPC Service Controls חוסם ביעילות את כל הגישה לאינטרנט הציבורי, מגביל את תנועת הנתונים לגבולות הרשת המורשית ומשפר משמעותית את מצב האבטחה של הארגון.
אפשרויות הפריסה הזמינות מפורטות במאמר פריסת סוכן. בהתאם לאפשרות הפריסה, צריך להגדיר את כללי הכניסה הבאים:
- בפריסות שמבוססות על pickle, צריך גישה לשירות
storage.googleapis.comולשירותartifactregistry.googleapis.com. - בפריסות שמבוססות על מקור, בפריסות שמבוססות על Git ובפריסות של קובצי Docker בהתאמה אישית (BYOD), צריך כניסה לשירות
artifactregistry.googleapis.com. - בפריסות של Bring Your Own Container (BYOC), לא נדרש כלל כניסה נוסף.
מגבלות
VPC Service Controls לא נתמך ב-Agent Gateway.
עם זאת, אתם יכולים להשתמש באילוצים מותאמים אישית של מדיניות הארגון כדי להגביל את השערים שאפשר לשייך לסוכנים. מידע נוסף מופיע במאמר ניתוב תנועה דרך Agent Gateway.