פתרון בעיות במערכת גישה מאוחדת לכללי מדיניות (UAP) של IAM

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

אכיפת המדיניות וכשלים בגישה

בקטע הזה מתוארות בעיות שקשורות לאכיפה.

המדיניות לא נאכפת

הבעיה: נציג יכול לגשת לכלים, לשרתי MCP או לנקודות קצה ביעד, למרות שכלל דחייה או כלל הרשאה מגביל של IAM הוגדרו כדי לחסום את הגישה.

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

הפתרון:

  1. מעבר ממצב פרימטר לבדיקות למצב אכיפה: קודם בודקים את קובץ התצורה של התוסף שמפנה לבדיקת הרשאות (iap-request-authz-extension.yaml). אם הערך של iamEnforcementMode הוא "DRY_RUN", מעדכנים אותו ל-"ENFORCE" (או מסירים את ההגדרה DRY_RUN) ומייבאים מחדש את התוסף באמצעות ה-CLI של gcloud:

    gcloud service-extensions authz-extensions import EXTENSION_NAME \
    --source=EXTENSION_FILE.yaml \
    --location=LOCATION

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

    • ‫EXTENSION_NAME: השם של התוסף שמפנה לבדיקת הרשאות
    • EXTENSION_FILE: שם הקובץ של הגדרת התוסף ב-YAML
    • ‫LOCATION: האזור ב- Cloud de Confiance שבו נפרס השער

  2. אימות האצלת מדיניות ההרשאה של שער: מוודאים שמדיניות ההרשאה של השער (policyProfile: REQUEST_AUTHZ) משויכת למופע הנכון של Agent Gateway (target.resources).

  3. בודקים את היקף הקישור של המדיניות: מוודאים שה-UAP של IAM מקושר להיקף של משאב היעד שאליו מגיעה התנועה.

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

מדיניות שנאכפת חוסמת את הגישה של הסוכן

תיאור הבעיה: בקשת תעבורת נתונים יוצאת של סוכן נכשלת עם שגיאת HTTP 403 Forbidden או PERMISSION_DENIED כשאכיפת המדיניות של Agent Gateway מופעלת.

הסיבות:

  • הזהות של הסוכן לא מצוינת ב-UAP.

  • לזהות של הנציג לא ניתנה ההרשאה iap.resources.egressViaIAP במשאב היעד.

  • שם המארח המדויק של היעד לא רשום ב-Agent Registry

  • מאפייני הבקשה לא עומדים בתנאים של Common Expression Language ‏ (CEL) ב-UAP.

הפתרון:

  1. מעבר למצב פרימטר לבדיקות כדי לנפות באגים בלי הפרעות: בזמן אבחון הכשל, מעבירים באופן זמני את התוסף שמפנה לבדיקת הרשאות למצב פרימטר לבדיקות (iamEnforcementMode: "DRY_RUN") כדי שתנועת הסוכנים הפעילים לא תיחסם בזמן שבודקים את יומני הביקורת.

  2. שאילתה ביומני הביקורת של Cloud: אפשר לשלוח שאילתה ליומני הביקורת של Cloud כדי לבדוק את בדיקת ההרשאה המדויקת ואת הערכת המאפיינים של CEL:

    gcloud

    מריצים את הפקודה הבאה של gcloud logging read:

    gcloud logging read \
    'protoPayload.serviceName="iap.googleapis.com" AND protoPayload.authorizationInfo.permission="iap.resources.egressViaIAP" AND protoPayload.status.code!=0' \
    --project=PROJECT_ID \
    --limit=20

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

    המסוף

    1. נכנסים לדף Logs Explorer במסוף Cloud de Confiance .
    2. בוחרים את הפרויקט הרצוי.
    3. בעורך השאילתות, מזינים את השאילתה הבאה: 
          protoPayload.serviceName="iap.googleapis.com"
    protoPayload.authorizationInfo.permission="iap.resources.egressViaIAP"
    protoPayload.status.code!=0
    4. לוחצים על Run query.
    5. מרחיבים את רשומת היומן ובודקים את protoPayload.authorizationInfo כדי לראות איזה URI של משאב יעד ואיזו הרשאה נכשלו בהערכה.

  3. מוודאים שיש התאמה מדויקת של שם המארח: Agent Gateway מתאים את שמות המארחים של היעד באופן מדויק. יכול להיות ש-API של Google או שירות של צד שלישי יפעלו באמצעות כמה וריאציות של שמות מארחים, בהתאם לגרסת ה-SDK, להגדרת הלקוח האזורי או לשימוש ב-mTLS – לדוגמה, us-central1-aiplatform.googleapis.com לעומת us-central1-aiplatform.mtls.googleapis.com לעומת aiplatform.googleapis.com.

    • אם אתם מסתמכים על יעדים רשומים, חשוב לוודא שכל וריאציה של שם מארח מדויק רשומה במאגר סוכני המשתמש.
    • אם הסוכן ניגש לנקודות קצה לא רשומות, צריך לוודא שמדיניות של נקודת קצה לא רשומה מעניקה iap.resources.egressViaIAP למארח ולנתיב האלה.

  4. בדיקת הכיסוי של קישור המדיניות בהיקפים השונים: בודקים אם קיים קישור מדיניות באחד משלושת ההיקפים הנתמכים:

    • בכל הרישום: מעניק גישה לכל הסוכנים, שרתי ה-MCP ונקודות הקצה ברישום.
    • לכל משאב: נותנת גישה לשרת MCP, לנקודת קצה או לסוכן ספציפיים שרשומים.
    • נקודות קצה לא רשומות: מאפשרות גישה ליעדים מחוץ למאגר הסוכנים.
    • הערה: כשמתארים קישורי מדיניות למשאב יעד, אם הפלט שמוחזר מכיל את השדה "etag" אבל אין קישורים, לא קיימת מדיניות IAM לאותו יעד.

הודעות שגיאה נפוצות בממשק המשתמש, ב-gcloud וב-API בארכיטקטורת REST

בקטע הזה מתוארות הודעות השגיאה ואיך לפתור אותן.

המדיניות לא נמצאה

הודעת שגיאה:

  • ממשק המשתמש של המסוף: "The requested policy doesn't exist. צריך לוודא שהמדיניות קיימת עבור המשאב שנבחר".
  • ‫API / gcloud: POLICY_NOT_FOUND / HTTP 404 Not Found

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

פתרון: כדי לוודא מהו מזהה המדיניות המדויק ואיפה היא נמצאת לפני שמקשרים או מעדכנים אותה, צריך להשתמש בפקודה gcloud iam access-policies list --project=<var>PROJECT_ID</var> --location=global כדי להציג רשימה של כל מדיניות ה-UAP שזמינה בפרויקט.

חרגת ממגבלת הקישורים ליעדים

הודעת שגיאה:

  • ממשק המשתמש של Console: "היעד שנבחר הגיע למגבלת הקישורים של מדיניות הגישה. כדי להוסיף קישור חדש, צריך למחוק קישור קיים."
  • ‫API או gcloud: TOO_MANY_ACCESS_POLICY_BINDINGS_PER_TARGET

הסיבה: ניסיתם לצרף למשאב יעד (כמו שרת MCP או מרשם) יותר קישורי מדיניות מהמגבלה המקסימלית המותרת לכל יעד.

פתרון: במקום ליצור UAP נפרד וקישור לכל כלל בנפרד, מאחדים כמה כללי הרשאה או דחייה ל-UAP אחד. מסירים קישורים שלא בשימוש באמצעות gcloud iam policy-bindings delete.

חריגה ממגבלת קשירת המדיניות

הודעת שגיאה:

  • ממשק המשתמש של המסוף: "The selected policy has reached its limit for bindings. כדי להוסיף קישור חדש, צריך למחוק קישור קיים."
  • ‫API / gcloud: TOO_MANY_ACCESS_POLICY_BINDINGS_TO_POLICY

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

פתרון: מקשרים את המדיניות להיקף רחב יותר, כמו היקף כלל-המרשם (AgentRegistry) או היקף הפרויקט, ומשתמשים בתנאי מאפיינים של CEL (כמו destination.agent_registry.mcp_server.name) כדי לנהל את הגישה לכלים ספציפיים במסגרת כללי המדיניות.

חריגה ממגבלת התנאים

הודעת שגיאה:

  • ממשק המשתמש של המסוף: "הגענו למספר המקסימלי של תנאי מאפיינים במדיניות הזו. כדי לשמור את השינויים, צריך להסיר חלק מהתנאים".
  • ‫API / gcloud: TOO_MANY_CONDITIONS / חריגה ממגבלת התנאים של כלל במדיניות.

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

פתרון: מאחדים את בדיקות המאפיינים באמצעות אופרטורים לוגיים של CEL‏ (&&, ||) או חיפושים של הכללת קבוצות (in), או מפצלים את הביטויים לכמה כללים באותו UAP.

פרטי הכלל המיושן

הודעת שגיאה:

  • ממשק המשתמש של המסוף: "פרטי הכלל לא עדכניים. משתמש אחר שינה את הכלל הזה אחרי שהדף נטען. צריך לרענן את הדף כדי לאחזר את הפרטים הנוכחיים לפני העריכה או המחיקה."
  • ‫API / gcloud: HTTP 412 Precondition Failed / ABORTED בגלל חוסר התאמה של etag.

הסיבה: אדמין אחר או תהליך אוטומטי שינו את ה-UAP אחרי שאחזרתם אותו, ולכן ה-etag של הבקשה שלכם שונה מהמצב הפעיל של השרת.

הפתרון: מרעננים את הדף במסוף כדי לאחזר את פרטי המדיניות הפעילה וetag לפני ששומרים את השינויים. כשמשתמשים ב-API בארכיטקטורת REST, קודם שולחים בקשת GET כדי לאחזר את הערך הפעיל של "etag", וכוללים אותו במטען הייעודי (payload) של בקשת ה-PATCH.

אי אפשר למחוק את הכלל האחרון במדיניות

הודעת שגיאה:

  • ממשק המשתמש של המסוף: "Cannot delete this rule. במדיניות ברירת המחדל צריך להיות לפחות כלל אחד. כדי להסיר את הכלל הזה, צריך למחוק את המדיניות במקום זאת". או "זה הכלל האחרון ב <שם המדיניות>. אם תמחקו אותו, המדיניות תימחק וכל ההתאמות המשויכות יוסרו באופן סופי, מה שיכול להשפיע על הגישה של הסוכן למשאבים".

הסיבה: אי אפשר לשמור UAP של IAM עם אפס כללים.

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

ביטוי CEL בהתאמה אישית נשמר בכרטיסייה "מתקדם"

הודעת שגיאה:

  • ממשק המשתמש של המסוף: "לא ניתן להמיר את ביטוי ה-CEL המותאם אישית לבחירות סטנדרטיות בממשק המשתמש. הביטוי נשמר בכרטיסייה 'מתקדם'.

הסיבה: הזנתם פונקציה או תנאי CEL מורכבים ב-Condition editor (בכרטיסייה Advanced), שאי אפשר למפות אותם לבוררים הפשוטים בתפריט הנפתח של הכלי הרגיל להגדרת תנאים.

הפתרון: ההודעה הזו היא התראה אינפורמטיבית. תנאי ה-CEL המותאם אישית שלכם תקף ונשמר. ממשיכים לבצע את העריכות הרצויות ישירות בכרטיסייה Condition editor.

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