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

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

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

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

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

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

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

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

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

מידע נוסף על מדיניות הרשאות, פרופילי מדיניות ותיאורי מקרה זמין במאמר סקירה כללית על מדיניות הרשאות.

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

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

  • שערי Agent-to-Anywhere: שערי Agent-to-Anywhere (יציאה) תומכים בעד ארבעה כללי מדיניות הרשאות. שערי יציאה תומכים בפרופילי מדיניות מסוג REQUEST_AUTHZ וגם מסוג CONTENT_AUTHZ, ואפשר להגדיר מספר מדיניות מכל סוג במסגרת המגבלה הזו.

    מומלץ להשתמש בהגדרה הבאה:

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

    מידע נוסף על אופן ההערכה של כללי המדיניות זמין במאמר בנושא הערכת מדיניות בתעבורת נתונים יוצאת (egress).

טופולוגיית ה-multi-gateway הזו מבטיחה ש-Model Armor יסנן הנחיות נכנסות, וש-IAP, ‏ Model Armor ומדיניות סמנטית יסננו תשובות יוצאות.

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

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

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

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

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

  • ה-Agent Gateway נפרס. מידע נוסף זמין במאמר בנושא הגדרת Agent Gateway.

  • כדי לצרף מדיניות הרשאות לשער, צריכה להיות לכם הרשאת ה-IAM‏ networkservices.agentGateways.use במשאב Agent Gateway שנפרס.

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

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

האצלת הרשאות ל-IAP

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

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

  1. לפני שמתחילים: משביתים את האכיפה של האילוץ Disable binding access policy to resource (constraints/iam.managed.disableAccessPolicyBindings) של מדיניות הארגון המנוהלת. כברירת מחדל, האילוץ הבוליאני הזה מופעל בארגונים חדשים, והוא ימנע מכם לקשר מדיניות מאוחדת של IAM למשאב. מידע נוסף זמין במאמר בנושא עדכון מדיניות באמצעות כללים בוליאניים.

  2. יוצרים את מדיניות ה-IAM הנדרשת ליציאה (egress) עבור הסוכנים והכלים. מידע נוסף זמין במאמר בנושא יצירת מדיניות של סוכני IAM.

  3. במאמר הגדרת Agent Gateway במצב Agent-to-Anywhere (יציאה) מוסבר איך להפעיל את IAP כשיוצרים את Agent Gateway (באמצעות הפרמטר Access authorization).

  4. מגדירים תוסף הרשאה שיפנה אל IAP.

    1. מגדירים את התוסף בקובץ YAML. משתמשים בערכים לדוגמה שצוינו. אם רוצים לפרוס את התוסף במצב ביקורת בלבד של הרצה יבשה, כדי לבדוק את מדיניות ההרשאות בלי לאכוף אותה, אפשר לציין את השדה 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
      

      אם רוצים לפרוס את התוסף במצב ביקורת בלבד של הרצה יבשה, כדי לבדוק את מדיניות ההרשאות בלי לאכוף אותה, אפשר לציין את השדה 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.

    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
      
  5. באותו פרויקט, מגדירים מדיניות הרשאות שמקצה את ההחלטה לתוסף.

    1. מגדירים מדיניות הרשאות שמקשרת את התוסף 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 במזהה הפרויקט.

    2. מייבאים את מדיניות ההרשאות לפרויקט. משתמשים ב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.

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

המסוף

כדי להשתמש במסוף Cloud de Confiance כדי להפעיל את הגנה מוגברת על המודל עבור Agent Gateway, מבצעים את השלבים הבאים:

  1. יוצרים את התבניות הנדרשות של הגנה מוגברת על המודל.

  2. במאמר הגדרת Agent Gateway מוסבר איך להפעיל את Model Armor כשיוצרים את Agent Gateway (באמצעות תיבת הסימון Enable Model Armor). תבניות של הגנה מוגברת על המודל נתמכות במצבים Client-to-Agent ו-Agent-to-Anywhere.

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

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

    • התפקידים roles/modelarmor.calloutUser ו-roles/serviceusage.serviceUsageConsumer בפרויקט שמכיל את השער.
    • התפקיד roles/modelarmor.user בפרויקט שמכיל את תבניות הגנה מוגברת על המודל.

    כדי להשלים את השלב הזה, צריך להשתמש ב-CLI של gcloud.

    gcloud projects add-iam-policy-binding GATEWAY_PROJECT_ID \
        --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep.s3ns-system.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.s3ns-system.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.s3ns-system.iam.gserviceaccount.com \
        --role=roles/modelarmor.user
    

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

    • ‫GATEWAY_PROJECT_ID: מזהה הפרויקט שבו יצרתם את שער הגישה.
    • ‫GATEWAY_PROJECT_NUMBER: מספר הפרויקט שבו יצרתם את שער הנתונים.
    • ‫MODEL_ARMOR_PROJECT_ID: מזהה הפרויקט שמכיל את תבנית הגנה מוגברת על המודל.

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

gcloud

  1. יוצרים את התבניות הנדרשות של הגנה מוגברת על המודל.

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

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

    • התפקידים roles/modelarmor.calloutUser ו-roles/serviceusage.serviceUsageConsumer בפרויקט שמכיל את השער.
    • התפקיד roles/modelarmor.user בפרויקט שמכיל את תבנית הגנה מוגברת על המודל.
    gcloud projects add-iam-policy-binding GATEWAY_PROJECT_ID \
        --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep.s3ns-system.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.s3ns-system.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.s3ns-system.iam.gserviceaccount.com \
        --role=roles/modelarmor.user
    

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

    • ‫GATEWAY_PROJECT_ID: מזהה הפרויקט שבו יצרתם את שער הגישה.
    • ‫GATEWAY_PROJECT_NUMBER: מספר הפרויקט שבו יצרתם את שער הנתונים.
    • ‫MODEL_ARMOR_PROJECT_ID: מזהה הפרויקט שמכיל את תבנית הגנה מוגברת על המודל.
  3. מגדירים את תוסף ההרשאה כך שיצביע על Model Armor.

    1. מגדירים את התוסף בקובץ 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
      
    2. מייבאים את תוסף ההרשאות. משתמשים ב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
      
  4. הגדרת מדיניות הרשאות באמצעות התוסף.

    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
      

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

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

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

  1. כדי להגדיר תוסף הרשאה עם מדיניות הרשאה עבור 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
    
  2. יוצרים את תוסף ההרשאה כדי להפנות לשירות המותאם אישית.

    gcloud beta service-extensions authz-extensions import custom-authz-extension \
      --source=custom-authz-extension.yaml \
      --location=LOCATION
    
  3. אחרי שיוצרים את התוסף, מגדירים 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
    
  4. יוצרים את מדיניות ההרשאות.

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

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

שילוב של הרשאת IAP עם אמצעי בקרה של הגנה מוגברת על המודל

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

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

  1. מגדירים תוסף הרשאה של 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
      
  2. מגדירים תוסף הרשאה של CONTENT_AUTHZ שמעביר את ההרשאה ל-Model Armor, ומדיניות הרשאה שמפנה לתוסף.

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

      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: המזהה של תבנית הבקשה.
    2. יוצרים את תוסף ההרשאה.

      gcloud service-extensions authz-extensions import ma-extension \
      --source=ma-extension-file.yaml \
      --location=LOCATION
      
    3. הגדרת מדיניות ההרשאות של 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
      
    4. יוצרים את מדיניות ההרשאות.

      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 ל-Agent Gateway מוסבר איך להקצות את Policy Engine וליצור את CONTENT_AUTHZ מדיניות ההרשאות והקישור של תוסף שמפנה לבדיקת הרשאות הנדרשים בשער.

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

ה-Agent Gateway מנתח את מטען ה-MCP בפקודה ומאפשר להשתמש במאפיינים שחולצו במדיניות ההרשאות.

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

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

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

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

    כשכותבים מדיניות ALLOW, חשוב לציין baseProtocolMethodsOption: MATCH_BASE_PROTOCOL_METHODS כדי שפרוטוקולי ה-RPC של MCP שלא קשורים לגישה, כמו initialize,‏ logging,‏ completion,‏ notifications ו-ping, ימשיכו לפעול. אם לא תעשו את זה, לא תוכלו ליצור סשן 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
    
  2. יוצרים את מדיניות ההרשאות.

    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).
    • בשערי כניסה (ingress) של לקוחות לסוכנים, אפשר להגדיר עד CONTENT_AUTHZ מדיניות אחת.

    מידע נוסף זמין במאמר בנושא הגדרות מומלצות של תעבורת כניסה ויציאה.

  • אם אתם משתמשים בתוספים מותאמים אישית להרשאות עם פרופיל CONTENT_AUTHZ, הם צריכים לתמוך בפרוטוקול ext_proc ובמצב FULL_DUPLEX_STREAMED לאירועים של body.

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

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

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

Codelab

איך שולטים בעומסי עבודה אקטיביים באמצעות Agent Gateway ב-Gemini Enterprise Agent Platform.

מדריך

איך עוקבים אחרי Agent Gateway

פתרון בעיות

איך פותרים בעיות בקישוריות של Agent Gateway