‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

האצלת הרשאות באמצעות Service Extensions

בדף הזה מוסבר איך להשתמש בתוספי שירות כדי להקצות הרשאות ל-Agent Gateway לשרת proxy לאימות זהויות (IAP), ל-Model Armor ולמנועי הרשאות אחרים בהתאמה אישית.

תוספים וכללי מדיניות של הרשאות

כללי מדיניות ההרשאה מאפשרים לאכוף כללי מדיניות מרכזיים של בקרת גישה ומשילות על תנועה שעוברת דרך נקודות קצה (endpoints) שפורסמו על ידי Agent Gateway. כדי לטפל בהחלטות מורכבות שקשורות לבקרת גישה, לבטיחות התוכן ולמשילות, Agent Gateway מאפשר להגדיר כללי מדיניות הרשאות באמצעות תוספים שמפנים לבדיקת הרשאות. התוספים האלה מאפשרים להקצות את ההחלטות לגבי הרשאות ובטיחות התוכן למנועי הרשאות ייעודיים לבחירתכם.

תוסף שמפנה לבדיקת הרשאות מיירט בקשות שעוברות דרך פריסה של Agent Gateway, ומבצע קריאת gRPC בזמן אמת לשירות ההרשאות הייעודי. כך השירות יכול לבדוק, לשנות או לחסום את התנועה לפני שהיא ממשיכה ליעד שלה. אתם יכולים להאציל הרשאות לשירותים של Google Cloud , כמו שרת proxy לאימות זהויות (IAP), הגנה מוגברת על המודל ומדיניות פיקוח בשפה טבעית, או לכל מנוע הרשאות בהתאמה אישית לבחירתכם.

מדיניות ההרשאות משתמשת בפרופילי מדיניות כדי לקבוע את סוג נתוני התנועה שנשלחים לתוסף שמפנה לבדיקת הרשאות:

הרשאה מבוססת-בקשה (REQUEST_AUTHZ): מעריכה את כותרות בקשות ה-HTTP לפני שמתבצע עיבוד של המטען הייעודי (payload) של האפליקציה. הפרופיל הזה משמש לאימות זהות ולבקרת גישה, כמו הקצאת הרשאה לשרת proxy לאימות זהויות.
הרשאה מבוססת-תוכן (CONTENT_AUTHZ): הערכה של נתוני המטען הייעודי (payload) המלאים של בקשות ותגובות HTTP. הפרופיל הזה משמש לבדיקת תוכן מעמיקה ולבטיחות ב-AI, כמו העברת בקשות להגנה מוגברת על המודל כדי לשמור על הבטיחות של ההנחיות והתשובות, או למדיניות פיקוח בשפה טבעית כדי לאכוף אילוצים בשפה טבעית.

מנועי הרשאות בהתאמה אישית יכולים להשתמש בתוספים של REQUEST_AUTHZ או CONTENT_AUTHZ, בהתאם לבדיקה של כותרות או של מטען ייעודי (payload) מלא של אפליקציות.

אתם יכולים להגדיר תוספים שמפנים לבדיקת הרשאות בנפרד למדיניות שמבוססת על בקשות ולמדיניות שמבוססת על תוכן, או לשלב את שניהם בשער כדי לקבל אבטחה מקיפה. להגדרות מומלצות, קראו את המאמר הגדרות מומלצות לתעבורת נתונים נכנסת ויוצאת.

למידע נוסף על מדיניות הרשאה, פרופילי מדיניות ותרחישים לדוגמה, ראו סקירה כללית של מדיניות הרשאה.

הגדרה מומלצת לתעבורת נתונים נכנסת ויוצאת

כדי להבטיח אבטחה מקיפה לאורך כל מחזור החיים של הנציג, מומלץ להשתמש בתבנית הארכיטקטורה הבאה של כמה שערים:

שערי כניסה מלקוח לסוכן: שערי כניסה מלקוח לסוכן (ingress) תומכים רק במדיניות CONTENT_AUTHZ אחת. כלומר, אי אפשר להשתמש ב"הגנה מוגברת על המודל" ובמדיניות פיקוח בשפה טבעית ביחד ב-ingress. אנחנו ממליצים מאוד להשתמש במדיניות של Model Armor‏ (CONTENT_AUTHZ) כדי להגן מפני מתקפות של החדרת פרומפטים. עם זאת, אם אתם רוצים להשתמש בתוסף מדיניות פיקוח בשפה טבעית, אתם צריכים לוודא שהשער לא מוגדר עם Model Armor. אין תמיכה בסוגים אחרים של תוספי שירות בשערי כניסה.
שערים מסוג Agent-to-Anywhere: שערים מסוג Agent-to-Anywhere (תעבורת נתונים יוצאת) תומכים בעד ארבעה כללי מדיניות הרשאה. שערי יציאה תומכים בפרופילי מדיניות גם של REQUEST_AUTHZ וגם של CONTENT_AUTHZ, ואפשר להגדיר כמה כללי מדיניות מכל סוג במסגרת המגבלה הזו.

אנחנו ממליצים על ההגדרות הבאות:
- מדיניות REQUEST_AUTHZ שמעבירה ל-Identity-Aware Proxy ‏ (IAP) את הסמכות לאשר את זהות הנציג.
- מדיניות אחת או יותר של CONTENT_AUTHZ שמעבירה החלטות נוספות ל-Model Armor או למדיניות פיקוח בשפה טבעית, כדי להגן מפני חשיפת נתונים רגישים ולאכוף אילוצים בשפה טבעית על קריאות ועל תשובות יוצאות של כלים.
למידע נוסף על האופן שבו כללי המדיניות נבדקים, קראו את המאמר בדיקת המדיניות לגבי תעבורת נתונים יוצאת.

הטופולוגיה הזו, שכוללת כמה שערים, מבטיחה שההגנה המוגברת על המודל תסנן את ההנחיות הנכנסות, ושהתשובות היוצאות יסוננו על ידי IAP, ההגנה המוגברת על המודל ומדיניות הפיקוח בשפה טבעית.

הערכת מדיניות לגבי תעבורת נתונים יוצאת (egress)

כשמגדירים כמה כללי מדיניות הרשאה בשער תעבורת נתונים יוצאת, הם נבדקים ברצף לפי סוג פרופיל המדיניות שלהם:

כללי מדיניות מסוג REQUEST_AUTHZ (מבוססי-כותרת): כללי המדיניות האלה נבדקים קודם. לדוגמה, תוסף IAP בודק את זהות ה-mTLS של הסוכן ששולח את הבקשה ומאמת את כללי מדיניות ההרשאה שלו ב-IAM לפני שתוכן כלשהו מעובד. אם הבקשה נכשלת בבדיקה הזו, היא נדחית באופן מיידי.
כללי מדיניות של CONTENT_AUTHZ (מבוססי-תוכן): סוגי כללי המדיניות האלה נבדקים בשלב הבא. אם הבקשה עוברת את הבדיקה שמבוססת על הכותרת, המטען הייעודי (payload) מועבר בסטרימינג לתוסף שמפנה לבדיקת הרשאות שמבוסס על תוכן (כמו Policy Engine של מדיניות הפיקוח בשפה טבעית) כדי לבדוק לעומק את התוכן ולהעריך את התאימות.

לפני שמתחילים

לפני שמתחילים, צריך לוודא שעומדים בדרישות הבאות:

‫Agent Gateway נפרס. איך מגדירים את Agent Gateway
כדי לצרף כללי מדיניות הרשאה ל-gateway, צריך הרשאת IAM מסוג networkservices.agentGateways.use במשאב Agent Gateway שנפרס.

הגדרת מדיניות הרשאות באמצעות תוספים

בקטע הזה מוסבר איך להגדיר כללי מדיניות הרשאה שמעבירים את ההחלטות לגבי הרשאות ובטיחות התוכן לשרת proxy לאימות זהויות (IAP), ל"הגנה מוגברת על המודל" ולשירותים מותאמים אישית אחרים.

הענקת הרשאה ל-IAP

אתם יכולים להגדיר תוסף שמפנה לבדיקת הרשאות כדי להעביר ל-IAP את ההחלטות לגבי גישה למדיניות הרשאות.

כך מגדירים תוסף שמפנה לבדיקת הרשאות עם מדיניות הרשאות למכונה של Agent Gateway:

לפני שמתחילים: משביתים את האכיפה של האילוץ Disable binding access policy to resource‏ (constraints/iam.managed.disableAccessPolicyBindings) במדיניות הארגון. כברירת מחדל, האילוץ הבוליאני הזה מופעל בארגונים חדשים ומונע קישור של מדיניות הגישה המאוחדת של IAM למשאב. מידע נוסף זמין במאמר עדכון כללי מדיניות באמצעות כללים בוליאניים.
יוצרים את כללי מדיניות ה-IAM הנדרשים לתעבורת נתונים יוצאת בשביל הסוכנים והכלים. מידע נוסף זמין במאמר יצירת מדיניות סוכנים ב-IAM.
כדי להפעיל את IAP כשיוצרים את Agent Gateway (באמצעות הפרמטר Access authorization), קראו את המאמר הגדרת Agent Gateway במצב Agent-to-Anywhere (תעבורת נתונים יוצאת).
מגדירים תוסף שמפנה לבדיקת הרשאות ב-IAP.
1. מגדירים את התוסף בקובץ YAML. משתמשים בערכים לדוגמה שסופקו. אם רוצים לפרוס את התוסף במצב הרצה (dry run) לביקורת בלבד, כדי לבדוק את מדיניות ההרשאות בלי לאכוף אותה, אפשר לציין את השדה iamEnforcementMode בתוך הבלוק metadata.
```
cat >iap-request-authz-extension.yaml <<EOF
name: my-iap-request-authz-ext
service: iap.googleapis.com
failOpen: false
timeout: 1s
metadata:
  iapPolicyVersion: "V2"
EOF
```
  אם רוצים לפרוס את התוסף במצב הרצה (dry run) לביקורת בלבד, כדי לבדוק את מדיניות ההרשאה בלי לאכוף אותה, אפשר לציין את השדה iamEnforcementMode בתוך הבלוק metadata. כך תוכלו לאמת את המדיניות ולצמצם את הסיכון לשיבוש בתנועה בגלל שגיאות בהגדרות:
```
cat >iap-request-authz-extension.yaml <<EOF
name: my-iap-request-authz-ext
service: iap.googleapis.com
failOpen: false
timeout: 1s
metadata:
  iapPolicyVersion: "V2"
  iamEnforcementMode: "DRY_RUN"
EOF
```
  כשתהיו מוכנים להתחיל לאכוף את כללי המדיניות, הסירו את השדה iamEnforcementMode: "DRY_RUN" מהבלוק metadata.
  
  הערה: מומלץ מאוד להשתמש במדיניות בקרת הגישה המאוחדת (iapPolicyVersion: "V2") כדי ליהנות מבקרת גישה מתקדמת, מפורטת וגמישה. כדי להחליף מדיניות הרשאות מדור קודם (iapPolicyVersion: "V1") בשער קיים, עוברים לממשק המשתמש של המדיניות ומגדירים מחדש באופן ידני את הכללים בכרטיסייה UAP. מידע נוסף זמין במאמר יצירת כללי מדיניות של סוכני IAM.
2. מייבאים את התוסף שמפנה לבדיקת הרשאות. משתמשים בפקודה gcloud service-extensions authz-extensions import עם ערכי הדוגמה הבאים.
```
gcloud service-extensions authz-extensions import my-iap-request-authz-ext \
    --source=iap-request-authz-extension.yaml \
    --location=LOCATION
```

באותו פרויקט, מגדירים מדיניות הרשאה שמעבירה את ההחלטה לתוסף.

מגדירים מדיניות הרשאה שמשייכת את התוסף my-iap-request-authz-ext לשער. משתמשים בערכים לדוגמה שסופקו.

cat >iap-request-authz-policy.yaml <<EOF
name: my-iap-request-authz-policy
target:
  resources:
    - "projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME"
policyProfile: REQUEST_AUTHZ
action: CUSTOM
customProvider:
  authzExtension:
    resources:
      - "projects/PROJECT_ID/locations/LOCATION/authzExtensions/my-iap-request-authz-ext"
EOF

מחליפים את PROJECT_ID במזהה הפרויקט.

מייבאים את מדיניות ההרשאות לפרויקט. משתמשים בפקודה gcloud network-security authz-policies import עם ערכי הדוגמה הבאים.
```
gcloud network-security authz-policies import my-iap-request-authz-policy \
    --source=iap-request-authz-policy.yaml \
    --location=LOCATION
```

הענקת הרשאה ל-Model Armor

אתם יכולים להגדיר תוסף שמפנה לבדיקת הרשאות כדי להעביר את ההחלטות לגבי אבטחת התוכן של מדיניות ההרשאות אל Model Armor. התבניות של Model Armor יכולות להיות באותו פרויקט של Agent Gateway והסוכן, או בפרויקט נפרד, כמו פרויקט אבטחה או פיקוח מרכזי.

בדוגמה הבאה מוסבר איך להגדיר תוסף כזה עם מדיניות הרשאה ל-Agent Gateway.

המסוף

כדי להפעיל את Model Armor ל-Agent Gateway באמצעות מסוף Google Cloud :

יוצרים את התבניות הנדרשות של Model Armor.
כדי להפעיל את Model Armor כשיוצרים את Agent Gateway, צריך לסמן את התיבה Enable Model Armor (הפעלה של Model Armor) כמו שמוסבר במאמר הגדרת Agent Gateway. התבניות של Model Armor נתמכות גם במצב "לקוח לסוכן" וגם במצב "סוכן לכל מקום".
כשמשתמשים ב-Model Armor, צריך לתת לחשבון השירות של Agent Gateway את ההרשאות שנדרשות כדי להשתמש בתבניות של Model Armor. חשבון השירות הוא בפורמט service-PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com, כאשר PROJECT_NUMBER הוא מספר הפרויקט שבו יצרתם את השער.

צריך לבצע את השלב הזה גם אם השער והתבניות נמצאים באותו פרויקט. מקצים את התפקידים הבאים:
- התפקידים roles/modelarmor.calloutUser ו-roles/serviceusage.serviceUsageConsumer בפרויקט שכולל את השער.
- התפקיד roles/modelarmor.user בפרויקט שמכיל את התבניות של Model Armor.
כדי להשלים את השלב הזה, צריך להשתמש ב-CLI של gcloud.
```
gcloud projects add-iam-policy-binding GATEWAY_PROJECT_ID \
    --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
    --role=roles/modelarmor.calloutUser
gcloud projects add-iam-policy-binding GATEWAY_PROJECT_ID \
    --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
    --role=roles/serviceusage.serviceUsageConsumer
gcloud projects add-iam-policy-binding MODEL_ARMOR_PROJECT_ID \
    --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
    --role=roles/modelarmor.user
```
מחליפים את מה שכתוב בשדות הבאים:
- ‫GATEWAY_PROJECT_ID: מזהה הפרויקט שבו יצרתם את השער.
- ‫GATEWAY_PROJECT_NUMBER: מספר הפרויקט שבו יצרתם את השער.
- ‫MODEL_ARMOR_PROJECT_ID: מזהה הפרויקט שמכיל את התבנית של Model Armor.
אם אתם משתמשים בשער ל-Agent Runtime, סוכן השירות של Agent Runtime צריך גם את ההרשאות האלה, כפי שמתואר במאמר ניתוב התנועה של Agent Runtime דרך Agent Gateway.

gcloud

יוצרים את התבניות הנדרשות של Model Armor.
כשמשתמשים ב-Model Armor, צריך לתת לחשבון השירות של Agent Gateway את ההרשאות שנדרשות כדי להשתמש בתבניות של Model Armor. חשבון השירות הוא בפורמט service-PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com, כאשר PROJECT_NUMBER הוא מספר הפרויקט שבו יצרתם את השער.

צריך לבצע את השלב הזה גם אם השער והתבניות נמצאים באותו פרויקט. מקצים את התפקידים הבאים:
- התפקידים roles/modelarmor.calloutUser ו-roles/serviceusage.serviceUsageConsumer בפרויקט שכולל את השער.
- התפקיד roles/modelarmor.user בפרויקט שמכיל את התבנית של Model Armor.
```
gcloud projects add-iam-policy-binding GATEWAY_PROJECT_ID \
    --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
    --role=roles/modelarmor.calloutUser
gcloud projects add-iam-policy-binding GATEWAY_PROJECT_ID \
    --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
    --role=roles/serviceusage.serviceUsageConsumer
gcloud projects add-iam-policy-binding MODEL_ARMOR_PROJECT_ID \
    --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
    --role=roles/modelarmor.user
```
מחליפים את מה שכתוב בשדות הבאים:
- ‫GATEWAY_PROJECT_ID: מזהה הפרויקט שבו יצרתם את השער.
- ‫GATEWAY_PROJECT_NUMBER: מספר הפרויקט שבו יצרתם את השער.
- ‫MODEL_ARMOR_PROJECT_ID: מזהה הפרויקט שמכיל את התבנית של Model Armor.

מגדירים את התוסף שמפנה לבדיקת הרשאות כך שיפנה אל Model Armor.

מגדירים את התוסף בקובץ YAML. משתמשים בערכים לדוגמה שסופקו.

cat >ma-content-authz-extension.yaml <<EOF
name: my-ma-content-authz-ext
service: modelarmor.LOCATION.rep.googleapis.com
metadata:
  model_armor_settings: '[
    {
    "response_template_id": "projects/MODEL_ARMOR_PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID",
    "request_template_id": "projects/MODEL_ARMOR_PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID"
    }
  ]'
failOpen: false
timeout: 1s
EOF

מייבאים את התוסף שמפנה לבדיקת הרשאות. משתמשים בפקודה gcloud service-extensions authz-extensions import עם ערכי הדוגמה הבאים.
```
gcloud service-extensions authz-extensions import my-ma-content-authz-ext \
   --source=ma-content-authz-extension.yaml \
   --location=LOCATION
```

מגדירים מדיניות הרשאה באמצעות התוסף.
1. מגדירים מדיניות הרשאה שמשייכת את התוסף my-ma-content-authz-ext ל-Agent Gateway.
  מסוכן לכל מקום
  cat >ma-content-authz-policy.yaml <<EOF name: my-ma-content-authz-policy target: resources: - "projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME" policyProfile: CONTENT_AUTHZ action: CUSTOM customProvider: authzExtension: resources: - "projects/PROJECT_ID/locations/LOCATION/authzExtensions/my-ma-content-authz-ext" httpRules: - to: operations: [ { "paths": [ { "prefix": "/" } ] } ] when: > request.headers['content-type'] == 'application/json' || request.headers['content-type'].startsWith('text/') EOF
  
  שימו לב לנקודות הבאות:
  
  הערך של policyProfile מוגדר כ-CONTENT_AUTHZ. זה מציין שספק המדיניות בהתאמה אישית מעבד את תנועת הבקשות והתגובות, כולל גוף הבקשה.
  
  הפרמטר httpRules מדגים איך להשתמש במאפייני CEL כדי ליצור תנאים שתואמים לתנועה הספציפית שרוצים להעביר להערכה ב-Model Armor. בדוגמה הזו, הכללים תואמים לכל התנועה עם סוגי התוכן application/json או text/. מומלץ להשתמש בכללים כאלה כדי להגביל את ההערכה של Model Armor לתנועה רלוונטית. כך אפשר לנתב תנועה נתמכת של LLM API, ‏ MCP ו-A2A אל Model Armor, ולהחריג תנועה פנימית כמו קריאות gRPC של סוכנים.
  מלקוח לנציג
  cat >ma-content-authz-policy.yaml <<EOF name: my-ma-content-authz-policy target: resources: - "projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME" policyProfile: CONTENT_AUTHZ action: CUSTOM customProvider: authzExtension: resources: - "projects/PROJECT_ID/locations/LOCATION/authzExtensions/my-ma-content-authz-ext" EOF
  
  הערך של policyProfile מוגדר כ-CONTENT_AUTHZ. זה מציין שספק המדיניות בהתאמה אישית מעבד את תנועת הבקשות והתגובות, כולל גוף הבקשה.
2. מייבאים את מדיניות ההרשאות לפרויקט. משתמשים בפקודה gcloud network-security authz-policies import עם ערכי הדוגמה הבאים.
```
gcloud network-security authz-policies import my-ma-content-authz-policy \
  --source=ma-content-authz-policy.yaml \
  --location=LOCATION
```

Terraform

כדי להגדיר באופן הצהרתי את התוספים שמפנים לבדיקת הרשאות ואת כללי המדיניות של CONTENT_AUTHZ ב-Model Armor באמצעות הספק google, צריך להגדיר את הקישורים הנדרשים של סוכן השירות ב-IAM, את התוסף שמפנה לבדיקת הרשאות ואת מדיניות ההרשאות. ההגדרה הזו רלוונטית גם אם התבניות של Model Armor נמצאות באותו פרויקט כמו Agent Gateway והנציג, וגם אם הן נמצאות בפרויקט נפרד. אם התבניות של Model Armor נמצאות בפרויקט שונה מהפרויקט שמכיל את הנציג או את Agent Gateway, ואתם משתמשים ב-VPC Service Controls, שני הפרויקטים צריכים להיות באותם גבולות גזרה לשירות של VPC Service Controls.

מקצים לסוכן השירות של Service Extensions את התפקידים הנדרשים בפרויקט שמכיל את Agent Gateway ובפרויקט שמכיל את התבניות של Model Armor. צריך לבצע את השלב הזה גם אם השער והתבניות נמצאים באותו פרויקט:

resource "google_project_iam_member" "dep_ma_callout_user" {
  project = "PROJECT_ID"
  role    = "roles/modelarmor.calloutUser"
  member  = "serviceAccount:service-PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com"
}

resource "google_project_iam_member" "dep_service_usage_consumer" {
  project = "PROJECT_ID"
  role    = "roles/serviceusage.serviceUsageConsumer"
  member  = "serviceAccount:service-PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com"
}

resource "google_project_iam_member" "dep_ma_template_user" {
  project = "MODEL_ARMOR_PROJECT_ID"
  role    = "roles/modelarmor.user"
  member  = "serviceAccount:service-PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com"
}

אם אתם משתמשים בשער ל-Agent Runtime, סוכן השירות של Agent Runtime צריך גם הרשאות, כמו שמתואר במאמר ניתוב התנועה של Agent Runtime דרך Agent Gateway.

מגדירים את המשאב google_network_services_authz_extension שמפנה להגנה מוגברת על המודל:

resource "google_network_services_authz_extension" "ma_content_authz_ext" {
  project   = "PROJECT_ID"
  location  = "LOCATION"
  name      = "my-ma-content-authz-ext"
  service   = "modelarmor.LOCATION.rep.googleapis.com"
  timeout   = "1s"
  fail_open = false

  metadata = {
    model_armor_settings = jsonencode([
      {
        response_template_id = "projects/MODEL_ARMOR_PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID"
        request_template_id  = "projects/MODEL_ARMOR_PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID"
      }
    ])
  }

  depends_on = [
    google_project_iam_member.dep_ma_callout_user,
    google_project_iam_member.dep_service_usage_consumer,
    google_project_iam_member.dep_ma_template_user,
  ]
}

מצרפים את התוסף ל-Agent Gateway באמצעות משאב google_network_security_authz_policy:

מסוכן לכל מקום

resource "google_network_security_authz_policy" "ma_content_authz_policy" {
  project        = "PROJECT_ID"
  location       = "LOCATION"
  name           = "my-ma-content-authz-policy"
  policy_profile = "CONTENT_AUTHZ"
  action         = "CUSTOM"

  target {
    resources = [
      "projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME"
    ]
  }

  custom_provider {
    authz_extension {
      resources = [
        google_network_services_authz_extension.ma_content_authz_ext.id
      ]
    }
  }

  http_rules {
    to {
      operations {
        paths {
          prefix = "/"
        }
      }
    }
    when = "request.headers['content-type'] == 'application/json' || request.headers['content-type'].startsWith('text/')"
  }
}

מלקוח לנציג

resource "google_network_security_authz_policy" "ma_content_authz_policy" {
  project        = "PROJECT_ID"
  location       = "LOCATION"
  name           = "my-ma-content-authz-policy"
  policy_profile = "CONTENT_AUTHZ"
  action         = "CUSTOM"

  target {
    resources = [
      "projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME"
    ]
  }

  custom_provider {
    authz_extension {
      resources = [
        google_network_services_authz_extension.ma_content_authz_ext.id
      ]
    }
  }
}

מחליפים את מה שכתוב בשדות הבאים:

‫PROJECT_ID: מזהה הפרויקט שבו יצרתם את Agent Gateway.
‫PROJECT_NUMBER: מספר הפרויקט שבו יצרתם את Agent Gateway.
‫MODEL_ARMOR_PROJECT_ID: מזהה הפרויקט שמכיל את התבנית של Model Armor. זה יכול להיות אותו פרויקט כמו PROJECT_ID או פרויקט נפרד. אם התבנית נמצאת בפרויקט שונה מהפרויקט של הנציג או של Agent Gateway, ואתם משתמשים ב-VPC Service Controls, שני הפרויקטים צריכים להיות באותם גבולות גזרה לשירות.
‫LOCATION: האזור שבו נמצאים Agent Gateway והתבנית של Model Armor.
‫TEMPLATE_ID: המזהה של התבנית של Model Armor.
‫AGENT_GATEWAY_NAME: השם של משאב Agent Gateway.

העברת הרשאות לתוספים מותאמים אישית שמפנים לבדיקת הרשאות

אתם יכולים להגדיר תוספים שמפנים לבדיקת הרשאות מותאמים אישית כדי להאציל החלטות לשירותים מותאמים אישית. התוספים האלה יכולים לטרגט רק שמות דומיין שמוגדרים במלואם (FQDN).

כשמשתמשים ביעדי FQDN, התוסף משתמש בפרוטוקול HTTP2 עם הצפנת TLS כדי לתקשר עם נקודות קצה ביציאה 443. עם זאת, התוסף לא מאמת את אישור השרת. לכן, כדי לשפר את האבטחה, צריך לוודא שנקודות הקצה שפותרים נמצאות בתוך רשת ה-VPC. חשוב גם לוודא שהגדרתם קישור בין רשתות שכנות (peering) ב-DNS בין הפרויקט של Agent Gateway לבין רשת ה-VPC.

כדי להגדיר תוסף שמפנה לבדיקת הרשאות עם מדיניות הרשאות ל-FQDN ספציפי, כמו mycustomauthz.internal.net, צריך לציין אותו כערך של service בקובץ ה-YAML של התוסף, כמו בדוגמה הבאה. בדוגמה הזו אנחנו מניחים שפרסתם שרת ברשת ה-VPC שמטמיע את הפרוטוקול ext_proc במצב עיבוד גוף FULL_DUPLEX_STREAMED.
```
cat >custom-authz-extension.yaml <<EOF
name: my-custom-authz-ext
service: mycustomauthz.internal.net
failOpen: false
timeout: 1s
EOF
```

יוצרים את התוסף שמפנה לבדיקת הרשאות כדי להפנות לשירות המותאם אישית.

gcloud beta service-extensions authz-extensions import custom-authz-extension \
  --source=custom-authz-extension.yaml \
  --location=LOCATION

אחרי שיוצרים את התוסף, מגדירים מדיניות הרשאה של CUSTOM שמעבירה את ההחלטות לתוסף שמפנה לבדיקת הרשאות.

  cat >authz-policy.yaml <<EOF
  name: authz-with-extension
  target:
    resources:
      - "projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME"
  policyProfile: CONTENT_AUTHZ
  action: CUSTOM
  customProvider:
    authzExtension:
      resources:
        - "projects/PROJECT_ID/locations/LOCATION/authzExtensions/custom-authz-extension"
  EOF

יוצרים את מדיניות ההרשאה.

gcloud network-security authz-policies import authz-policy-with-extension \
--source=authz-policy.yaml \
--location=LOCATION

שימו לב: כשתוסף שמפנה לבדיקת הרשאות משויך למדיניות הרשאות באמצעות הפרופיל CONTENT_AUTHZ, כמו בדוגמה הזו, השער מפעיל את התוסף למטענים ייעודיים (payloads) של בקשות ותגובות (כותרות וגופים). כך אפשר לבצע בדיקת תוכן מעמיקה, להגדיר מעקות בטיחות להנחיות ולבצע חיטוי נתונים לתנועה של הסוכן. כברירת מחדל, כללי המדיניות של CONTENT_AUTHZ משתמשים בפרוטוקול ext_proc של Envoy במצב FULL_DUPLEX_STREAMED כדי לעבד אירועים בגוף הבקשה.

שילוב של הרשאת IAP עם מעקות הבטיחות של Model Armor

כדי להבטיח אבטחה מקיפה, מומלץ להגדיר מדיניות הרשאה מסוג CUSTOM עם פרופיל מדיניות REQUEST_AUTHZ ומדיניות הרשאה נוספת מסוג CUSTOM עם פרופיל מדיניות CONTENT_AUTHZ.

בדוגמה הבאה, IAP משמש כמערכת מרכזית לאישור בקשות, ו-Model Armor משמש כמעקות בטיחות ל-AI. כמו שמוצג בדוגמאות הקודמות, אתם יכולים להחליף כל אחד מהם בתוספי שירות כדי להשתמש בפתרונות בהתאמה אישית משלכם.

מגדירים תוסף שמפנה לבדיקת הרשאות ב-REQUEST_AUTHZ ומעביר את הבקשה ל-IAP, ומדיניות הרשאות שמפנה לתוסף.
1. מגדירים את התוסף שמפנה לבדיקת הרשאות. השדה iapPolicyVersion בקטע metadata הוא שדה חובה.
```
cat >iap-extension.yaml <<EOF
name: iap-extension
service: iap.googleapis.com
failOpen: false
timeout: 1s
metadata:
  iapPolicyVersion: "V2"
EOF
```
2. יוצרים את התוסף שמפנה לבדיקת הרשאות.
```
gcloud service-extensions authz-extensions import iap-extension \
--source=iap-extension.yaml \
--location=LOCATION
```
  מחליפים את LOCATION באזור של התוסף.
3. מגדירים את מדיניות ההרשאות של REQUEST_AUTHZ שמעבירה את ההרשאות לתוסף.
```
cat >authz-policy-request-authz.yaml <<EOF
name: authz-iap
target:
  resources:
  - "projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME"
policyProfile: REQUEST_AUTHZ
action: CUSTOM
customProvider:
  authzExtension:
    resources:
    - "projects/PROJECT_ID/locations/LOCATION/authzExtensions/iap-extension"
EOF
```
  מחליפים את מה שכתוב בשדות הבאים:
  - ‫PROJECT_ID: מזהה הפרויקט.
  - ‫LOCATION: המיקום של המשאבים.
  - ‫AGENT_GATEWAY_NAME: השם של Agent Gateway.
4. יוצרים את מדיניות ההרשאה.
```
gcloud network-security authz-policies import authz-iap \
--source=authz-policy-request-authz.yaml \
--location=LOCATION
```

מגדירים תוסף שמפנה לבדיקת הרשאות ב-CONTENT_AUTHZ ומעביר את הבקשה ל-Model Armor, ומדיניות הרשאות שמפנה לתוסף.

מגדירים את התוסף.

cat >ma-extension-file.yaml <<EOF
name: ma-extension
service: modelarmor.LOCATION.rep.googleapis.com
metadata:
  model_armor_settings: '[
    {
    "response_template_id": "projects/MODEL_ARMOR_PROJECT_ID/locations/LOCATION/templates/RESPONSE_TEMPLATE_ID",
    "request_template_id": "projects/MODEL_ARMOR_PROJECT_ID/locations/LOCATION/templates/REQUEST_TEMPLATE_ID"
    }
  ]'
failOpen: false
timeout: 1s
EOF

מחליפים את מה שכתוב בשדות הבאים:

‫LOCATION: האזור שבו נמצאות התבניות של Model Armor.
‫MODEL_ARMOR_PROJECT_ID: מזהה הפרויקט שמכיל את התבניות של Model Armor.
‫RESPONSE_TEMPLATE_ID: המזהה של תבנית התשובה.
‫REQUEST_TEMPLATE_ID: המזהה של תבנית הבקשה.

יוצרים את התוסף שמפנה לבדיקת הרשאות.

gcloud service-extensions authz-extensions import ma-extension \
--source=ma-extension-file.yaml \
--location=LOCATION

מגדירים את מדיניות ההרשאות של CONTENT_AUTHZ שמעבירה את ההרשאות לתוסף.

cat >authz-policy-content-authz.yaml <<EOF
name: authz-ma
target:
  resources:
  - "projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME"
policyProfile: CONTENT_AUTHZ
action: CUSTOM
customProvider:
  authzExtension:
    resources:
    - "projects/PROJECT_ID/locations/LOCATION/authzExtensions/ma-extension"
EOF

יוצרים את מדיניות ההרשאה.

gcloud network-security authz-policies import ma-authz-policy \
--source=authz-policy-content-authz.yaml \
--location=LOCATION

כשתוסף שמפנה לבדיקת הרשאות משויך לפרופיל CONTENT_AUTHZ, הוא מקבל את כל האירועים של ext_proc, כולל כותרות, גוף וטריילרים של בקשות ותגובות. אם התוסף שמפנה לבדיקת הרשאות מבוסס-ext_proc יכול לטפל גם בהרשאה בזמן הבקשה וגם בהרשאה מבוססת-תוכן, מומלץ להגדיר מדיניות הרשאה אחת של CUSTOM עם פרופיל המדיניות CONTENT_AUTHZ. המדיניות הזו צריכה להפנות לתוסף שמפנה לבדיקת הרשאות. הגישה הזו מאפשרת את שני סוגי ההרשאות באמצעות תוסף אחד וחיבור ext_proc אחד, מה שיכול לשפר את פרופילי זמן האחזור.

הקצאת הרשאות למדיניות פיקוח בשפה טבעית

אתם יכולים להגדיר תוסף שמפנה לבדיקת הרשאות כדי להעביר למנוע מדיניות הפיקוח בשפה טבעית (semanticGovernancePolicyEngine) את ההחלטות לגבי מדיניות ההרשאות שקשורות להגבלת כוונות ולהגבלות בשפה טבעית.

כדי ללמוד איך להקצות את Policy Engine וליצור את מדיניות ההרשאות הנדרשת של CONTENT_AUTHZ ואת הקישור של תוסף שמפנה לבדיקת הרשאות בשער, קראו את המאמר חיבור Policy Engine ל-Agent Gateway.

הרשאה שמבוססת על מאפייני פרוטוקול MCP

‫Agent Gateway מנתח את המטען הייעודי (payload) של פרוטוקול ה-MCP בבקשה, והופך את המאפיינים שחולצו לזמינים למדיניות ההרשאה.

אתם יכולים להגביל את הגישה על סמך פרמטרים של שיטות MCP, כמו שמות של כלים ספציפיים. בקטע הזה מוצגות שתי דוגמאות, אחת למדיניות ALLOW ואחת למדיניות DENY.

מגדירים את מדיניות ההרשאות.

דוגמה למדיניות ALLOW

בדוגמה הזו, יש גישה לקבוצה ספציפית של כלים בשרת ה-MCP ולתכונות של פרוטוקול הבסיס, אבל אין גישה להנחיות ולמשאבים.

כשכותבים מדיניות ALLOW, חשוב לציין את baseProtocolMethodsOption: MATCH_BASE_PROTOCOL_METHODS כדי שקריאות RPC של MCP שלא קשורות לגישה, כמו אתחול, רישום ביומן, השלמה, התראות ופינג, ימשיכו לפעול. אם לא תעשו את זה, לא תוכלו ליצור סשן MCP.

cat >authz-policy-restrict-tools.yaml <<EOF
name: my-authz-policy-restrict-tools
target:
  resources:
  - "projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME"
policyProfile: REQUEST_AUTHZ
httpRules:
- to:
    operations:
    - mcp:
        baseProtocolMethodsOption: MATCH_BASE_PROTOCOL_METHODS
        methods:
        - name: "tools/list"
        - name: "tools/call"
          params:
          - exact: "get_weather"
          - exact: "get_location"
action: ALLOW
EOF

דוגמה למדיניות DENY

בדוגמה הזו, כל ההנחיות והשיטות לא יכולות לגשת לשרת MCP שנמצא מאחורי Agent Gateway.

cat >authz-policy-disallow-prompts.yaml <<EOF
name: my-authz-policy-disallow-prompts
target:
  resources:
  - "projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME"
policyProfile: REQUEST_AUTHZ
httpRules:
- to:
    operations:
    - mcp:
        methods:
        - name: "prompts"
action: DENY
EOF

יוצרים את מדיניות ההרשאה.
```
gcloud network-security authz-policies import AUTHZ_POLICY_NAME \
--source=AUTH_POLICY_YAML_FILE_PATH \
--location=LOCATION
```
מחליפים את מה שכתוב בשדות הבאים:
- ‫AUTHZ_POLICY_NAME: השם של מדיניות ההרשאה.
- ‫AUTH_POLICY_YAML_FILE_PATH: הנתיב לקובץ ה-YAML של מדיניות ההרשאות.
- ‫LOCATION: המיקום של המשאבים.

מגבלות

המגבלות הבאות חלות כשמשתמשים בכללי מדיניות הרשאה:

מספר כללי מדיניות ההרשאה המקסימלי לכל שער תלוי במצב השער:
- בשערי Agent-to-Anywhere (תעבורת נתונים יוצאת), אפשר להגדיר עד ארבעה כללי מדיניות הרשאה לכל שער, בלי קשר לפרופיל המדיניות (REQUEST_AUTHZ או CONTENT_AUTHZ).
- בשערי Client-to-Agent (כניסה) אפשר להגדיר מדיניות CONTENT_AUTHZ אחת לכל היותר.
מידע נוסף זמין במאמר הגדרות מומלצות לתעבורת נתונים נכנסת ויוצאת.
אם אתם משתמשים בתוספים מותאמים אישית שמפנים לבדיקת הרשאות עם הפרופיל CONTENT_AUTHZ, הם צריכים לתמוך בפרוטוקול ext_proc ובמצב FULL_DUPLEX_STREAMED לאירועים בגוף הבקשה.
אם מגדירים כמה כללי מדיניות של הרשאות בהתאמה אישית שמשתמשים באותו פרופיל, אין הבטחה לסדר הביצוע שלהם.

בקטעים הבאים מפורט מידע נוסף על המגבלות של תוספים שמפנים לבדיקת הרשאות:

במאמר מגבלות של תוספים מפורטות המגבלות שחלות על כל התוספים.
בקטע מגבלות של הסברים מפורטות המגבלות שחלות על הסברים.

המאמרים הבאים

Codelab

האצלת הרשאות באמצעות Service Extensions

תוספים וכללי מדיניות של הרשאות

הגדרה מומלצת לתעבורת נתונים נכנסת ויוצאת

הערכת מדיניות לגבי תעבורת נתונים יוצאת (egress)

לפני שמתחילים

הגדרת מדיניות הרשאות באמצעות תוספים

הענקת הרשאה ל-IAP

הענקת הרשאה ל-Model Armor

המסוף

gcloud

מסוכן לכל מקום

מלקוח לנציג

Terraform

מסוכן לכל מקום

מלקוח לנציג

העברת הרשאות לתוספים מותאמים אישית שמפנים לבדיקת הרשאות

שילוב של הרשאת IAP עם מעקות הבטיחות של Model Armor

הקצאת הרשאות למדיניות פיקוח בשפה טבעית

הרשאה שמבוססת על מאפייני פרוטוקול MCP

מגבלות

המאמרים הבאים

Codelab: ניהול עומסי עבודה של סוכנים באמצעות Agent Platform

מעקב אחרי Agent Gateway

פתרון בעיות ב-Agent Gateway

האצלת הרשאות באמצעות Service Extensions קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

תוספים וכללי מדיניות של הרשאות

הגדרה מומלצת לתעבורת נתונים נכנסת ויוצאת

הערכת מדיניות לגבי תעבורת נתונים יוצאת (egress)

לפני שמתחילים

הגדרת מדיניות הרשאות באמצעות תוספים

הענקת הרשאה ל-IAP

הענקת הרשאה ל-Model Armor

המסוף

gcloud

מסוכן לכל מקום

מלקוח לנציג

Terraform

מסוכן לכל מקום

מלקוח לנציג

העברת הרשאות לתוספים מותאמים אישית שמפנים לבדיקת הרשאות

שילוב של הרשאת IAP עם מעקות הבטיחות של Model Armor

הקצאת הרשאות למדיניות פיקוח בשפה טבעית

הרשאה שמבוססת על מאפייני פרוטוקול MCP

מגבלות

המאמרים הבאים

Codelab: ניהול עומסי עבודה של סוכנים באמצעות Agent Platform

מעקב אחרי Agent Gateway

פתרון בעיות ב-Agent Gateway

האצלת הרשאות באמצעות Service Extensions