שליטה בגישה לסשנים באמצעות תנאי IAM

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

סקירה כללית

אתם יכולים להשתמש בתנאי IAM כדי לתת לחשבונות המשתמשים גישה למשאבים של סשנים ואירועים בסשנים רק כשהם עומדים בתנאים ספציפיים. אתם יכולים לשלוט בגישה לסשנים על סמך המחרוזת userId במשאב הסשן, באמצעות מאפיין ה-API‏ aiplatform.googleapis.com/sessionUserId עם ביטוי שכתוב ב-Common Expression Language. מזהה המשתמש הוא מחרוזת שרירותית שצריך לספק כשיוצרים סשנים, כמו userId = "userA".

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

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

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

כדי להגדיר מדיניות מותנית של ניהול זהויות והרשאות גישה לסשנים ולאירועי סשנים:

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

    כדי לקבל את ההרשאות שדרושות בשביל להחיל תנאי IAM על משאבים של Agent Platform Sessions, אתם צריכים לבקש מהאדמין לתת לכם את התפקידים הבאים ב-IAM:

    • בפרויקטים: אדמין IAM של פרויקט (`roles/resourcemanager.projectIamAdmin`)

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

    התפקידים המוגדרים מראש האלה מכילים את ההרשאות שנדרשות כדי להחיל תנאי IAM על משאבים של Agent Platform Sessions. כדי לראות בדיוק אילו הרשאות נדרשות, אפשר להרחיב את הקטע ההרשאות הנדרשות:

    ההרשאות הנדרשות

    כדי להחיל תנאי IAM על משאבי Agent Platform Sessions, נדרשות ההרשאות הבאות:

    • הגדרת גישה מותנית ל-IAM ברמת הפרויקט: `resourcemanager.projects.setIamPolicy`

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

    אם אתם מתכננים להשתמש בתנאי IAM בכל הארגון, אתם צריכים גם הרשאות לניהול כללי המדיניות של הארגון.

יצירת גישה מותנית לסשנים

כדי לתת גישה מותנית לסשנים, מוסיפים תנאי לקישור של מדיניות ניהול הזהויות והרשאות הגישה (IAM) ברמת הפרויקט. התנאי כולל את הפונקציה api.getAttribute('aiplatform.googleapis.com/sessionUserId', "") כדי לבדוק את מזהה המשתמש של משאב הסשן. מגדירים מזהה משתמש כשיוצרים סשן.

במאמר תנאים במדיניות ההרשאות מוסבר בפירוט איך יוצרים מדיניות IAM עם תנאים.

כדי לתת תפקיד לחשבון ראשי, תוכלו לבצע את הפעולות הבאות:

המסוף

  1. נכנסים לדף IAM במסוף Google Cloud .

    כניסה לדף IAM

  2. בוחרים את הפרויקט הרצוי.

  3. בוחרים חשבון משתמש כדי להקצות לו תפקיד:

    • כדי לתת את התפקיד לחשבון ראשי שכבר יש לו תפקידים אחרים במשאב, לוחצים על Edit principal בשורה שמכילה את החשבון ואז על Add another role.

      כדי להקצות תפקיד לסוכן שירות, מסמנים את התיבה Include Google-provided role grants כדי לראות את כתובת האימייל שלו.

    • כדי להקצות תפקיד לחשבון משתמש שאין לו תפקידים קיימים במשאב, לוחצים על Grant Access ומזינים את המזהה של חשבון המשתמש. לדוגמה, my-user@example.com או //iam.googleapis.com/locations/global/workforcePools/example-pool/group/example-group@example.com.

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

  5. מוסיפים תנאי לתפקיד, ומשתמשים ב-aiplatform.googleapis.com/sessionUserId כמאפיין ה-API. בדוגמאות שבהמשך מופיעות כמה הצהרות תנאי אפשריות.

  6. לוחצים על Save. חשבון המשתמש מקבל את התפקיד במשאב.

gcloud

  1. מפעילים את Cloud Shell במסוף Google Cloud .

    הפעלת Cloud Shell

    בחלק התחתון של מסוף Google Cloud יתחיל סשן של Cloud Shell ותופיע הודעה של שורת הפקודה. Cloud Shell היא סביבת מעטפת שבה ה-CLI של Google Cloud מותקן ומוגדרים ערכים לפרויקט הקיים. הסשן יופעל תוך כמה שניות.

  2. הפקודה add-iam-policy-binding מאפשרת להקצות תפקיד לחשבון משתמש במהירות.

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

    • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud . מזהי פרויקטים מכילים אותיות וספרות, למשל my-project.

    • ‏PRINCIPAL: מזהה של חשבון המשתמש או המנוי, שבדרך כלל נראה כך: PRINCIPAL_TYPE:ID. לדוגמה, user:my-user@example.com או principalSet://iam.googleapis.com/locations/global/workforcePools/example-pool/group/example-group@example.com. בדף העזר בנושא מזהים של חשבונות משתמשים תוכלו למצוא רשימה מלאה של הערכים שיכולים להיות ל-PRINCIPAL.

      בסוג חשבון המשתמש user, שם הדומיין במזהה צריך להיות של Google Workspace או של Cloud Identity. למידע על הגדרת דומיין ב-Cloud Identity, אפשר לעיין בסקירה כללית של Cloud Identity

    • ‏ROLE_NAME: שם התפקיד שרוצים לבטל. צריך להשתמש באחד מהפורמטים הבאים:

      • תפקידים מוגדרים מראש: roles/aiplatform.IDENTIFIER
      • תפקידים בהתאמה אישית ברמת הפרויקט: projects/PROJECT_ID/roles/IDENTIFIER

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

    • ‫CONDITION: מוסיפים תנאי לתפקיד, ומשתמשים ב-aiplatform.googleapis.com/sessionUserId כמאפיין ה-API. בדוגמאות הבאות מופיעות כמה הצהרות תנאי אפשריות.

    מריצים את הפקודה הבאה:

    ‫Linux,‏ macOS או Cloud Shell

    gcloud projects add-iam-policy-binding PROJECT_ID \
        --member=PRINCIPAL --role=ROLE_NAME \
        --condition=CONDITION

    ‏Windows (PowerShell)

    gcloud projects add-iam-policy-binding PROJECT_ID `
        --member=PRINCIPAL --role=ROLE_NAME `
        --condition=CONDITION

    ‏Windows (cmd.exe)

    gcloud projects add-iam-policy-binding PROJECT_ID ^
        --member=PRINCIPAL --role=ROLE_NAME ^
        --condition=CONDITION

    התשובה תכלול את המדיניות המעודכנת של IAM.

Terraform

במאמר פקודות בסיסיות ב-Terraform מוסבר איך מוסיפים או מסירים הגדרות אישיות ב-Terraform. למידע נוסף, ראו את מאמרי העזרה לספקים של Terraform.

אם אתם משתמשים ב-Terraform כדי להגדיר את כללי מדיניות ה-IAM, אתם יכולים לכלול תנאי במשאב google_project_iam_member כדי להגביל את הגישה של חבר לפגישות.

resource "google_project_iam_member" "example" {
  project    = "PROJECT_ID"
  role       = "ROLE"
  member     = "MEMBER"
  condition {
    title       = "Session Access Condition"
    description = "IAM condition for Session"
    expression  = "CONDITION"
  }
}

מחליפים את המשתנים הבאים:

  • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud . מזהי פרויקטים מכילים אותיות וספרות, למשל my-project.
  • ‫ROLE: תפקיד ה-IAM שרוצים להקצות, למשל roles/aiplatform.sessionEditor.
  • ‫MEMBER: חשבון המשתמש שרוצים לתת לו את התפקיד, לדוגמה user:developerA@corp.com. בדף העזר בנושא מזהים של חשבונות משתמשים תוכלו למצוא רשימה מלאה של הערכים שיכולים להיות ל-MEMBER.
  • CONDITION: הצהרת תנאי IAM שמשתמשת ב-aiplatform.googleapis.com/sessionUserId כמאפיין ה-API. בדוגמאות הבאות מופיעות כמה הצהרות תנאי אפשריות.

שיטות מומלצות להרשאות ברמת מזהה המשתמש

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

  1. שימוש בתפקידי IAM ייעודיים לסשנים: צריך להשתמש בתנאי IAM לסשנים רק בתפקידים שחלים על סשנים ועל אירועים של סשנים. כדי למנוע גישה עם יותר מדי הרשאות, אתם יכולים להשתמש בתפקידים ייעודיים כמו aiplatform.googleapis.com/sessionViewer,‏ aiplatform.googleapis.com/sessionEditor ו-aiplatform.googleapis.com/sessionUser. למידע נוסף, קראו את הקטע תפקידי IAM ייעודיים לסשנים.

  2. שימוש בתנאים חיוביים: כדי לשפר את הדיוק, מומלץ להשתמש בתנאים חיוביים (כמו בדיקות של שוויון או נוכחות של קידומות) ב-aiplatform.googleapis.com/sessionUserId. מכיוון שסוגים ושירותים לא נתמכים מיוצגים על ידי מזהה משתמש ריק, תנאים שליליים (כמו בדיקות של אי-שוויון) עשויים להתאים בטעות למגוון רחב של משאבים, מה שעלול להיות מתירני מדי ולאפשר הענקת הרשאות לא צפויות.

  3. לקצר את התנאים ככל האפשר: מומלץ להשתמש בלוגיקה הקצרה והפשוטה ביותר בביטויי תנאי IAM, במיוחד אם אתם מתכננים להשתמש בכמות גדולה של תנאים. לכללי מדיניות ההרשאה של IAM יש מגבלת גודל, ופישוט התנאים ימנע חריגה מהמגבלות של IAM. פרטים נוספים זמינים בקטע מגבלות. לדוגמה, כדי לבדוק שני מזהי משתמשים שונים, אפשר לפשט את ההצהרה המורכבת api.getAttribute('aiplatform.googleapis.com/sessionUserId', '') == 'sessionA' || api.getAttribute('aiplatform.googleapis.com/sessionUserId', '') == sessionB', כי היא שווה להצהרה הקצרה יותר api.getAttribute('aiplatform.googleapis.com/sessionUserId', '') in ['sessionA', 'sessionB'].

תפקידי IAM מיוחדים לסשנים

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

שם התפקיד תיאור ההרשאות הכלולות
roles/aiplatform.sessionViewer הרשאת קריאה בלבד לסשנים ולאירועים ברשימה.
  • aiplatform.googleapis.com/sessions.get
  • aiplatform.googleapis.com/sessions.list
  • aiplatform.googleapis.com/sessionEvents.list
roles/aiplatform.sessionEditor מעניקה גישת כתיבה לסשנים והוספת אירועים.
  • aiplatform.googleapis.com/sessions.create
  • aiplatform.googleapis.com/sessions.update
  • aiplatform.googleapis.com/sessions.delete
  • aiplatform.googleapis.com/sessionEvents.append
roles/aiplatform.sessionUser גישה מלאה לסשנים ולאירועים, כולל כל ההרשאות של בעלי הרשאות צפייה ועריכה. כולל את כל ההרשאות של sessionEditor ושל sessionViewer.

שימוש בתנאי IAM עם סשנים

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

  1. לתת גישת קריאה לסשנים עם התאמה מדויקת של מזהה המשתמש.

  2. הענקת גישת כתיבה לסשנים שמכילים תחילית ספציפית במזהה המשתמש.

  3. מתן גישה מלאה לסשנים שמכילים אחד משני מזהי משתמשים.

מתן גישת קריאה לסשנים עם התאמה מדויקת של מזהה המשתמש

התנאי הבא מעניק לאדם userA@gmail.com גישת צפייה רק לסשנים עם מזהה המשתמש המדויק userA.

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

{
  "members": ["user:userA@gmail.com"],
  "role": "roles/aiplatform.sessionViewer",
  "condition": {
    "title": "Session Access Condition",
    "expression": "api.getAttribute('aiplatform.googleapis.com/sessionUserId', '') == 'userA'"
  }
}

מתן גישת כתיבה לסשנים שמכילים קידומת ספציפית במזהה המשתמש

התנאי הבא מעניק למשתמש developerA@corp.com גישת עריכה לכל הסשנים שמכילים את מזהה המשתמש שמתחיל ב-user. אפשר להשתמש ב-startsWith כדי לבדוק את הקידומת וב-endsWith כדי לבדוק את הסיומת.

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

{
  "members": ["user:developerA@corp.com"],
  "role": "roles/aiplatform.sessionEditor",
  "condition": {
    "title": "Session Access Condition",
    "expression": "api.getAttribute('aiplatform.googleapis.com/sessionUserId', '').startsWith('user')"
  }
}

מתן גישה מלאה לסשנים שמכילים אחד משני מזהי משתמשים

התנאי הבא מעניק למשתמש group:engineering@corp.com בקבוצה (צופה ועורך) גישה לסשנים שכוללים רק את מזהי המשתמשים userA או user123.

{
  "members": ["group:engineering@corp.com"],
  "role": "roles/aiplatform.sessionUser",
  "condition": {
    "title": "Session Access Condition",
    "expression": "api.getAttribute('aiplatform.googleapis.com/sessionUserId', '') in ['userA', 'user123']"
  }
}

מגבלות

  1. מגבלת חשבונות משתמשים: מדיניות IAM מוגבלת ל-1,500 חשבונות משתמשים ייחודיים. אפשר לנהל את המגבלה הזו באמצעות קבוצות Google. מידע נוסף על המגבלות על כל חשבונות המשתמשים

  2. תמיכה ב-API של ListSessions: ה-API של ListSessions לא תומך בתנאי IAM. כדי לתת את ההרשאות של ListSessions, צריך לתת לחשבון המשתמש תפקיד ללא תנאים, כמו aiplatform.googleapis.com/sessionViewer, ‏aiplatform.googleapis.com/sessionUser או תפקיד רלוונטי ללא תנאים ב-Gemini Enterprise Agent Platform.