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

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

סקירה כללית

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

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

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

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

כדי להגדיר מדיניות ניהול זהויות והרשאות גישה (IAM) מותנית לסשנים ולאירועים בסשנים, צריך לבצע את הפעולות הבאות:

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

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

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

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

    התפקידים המוגדרים מראש האלה מכילים את ההרשאות שנדרשות כדי להחיל תנאי IAM על משאבי סשן של Vertex AI Agent Engine. כדי לראות בדיוק אילו הרשאות נדרשות, אפשר להרחיב את הקטע ההרשאות הנדרשות:

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

    כדי להחיל תנאי IAM על משאבי סשן של Vertex AI Agent Engine, נדרשות ההרשאות הבאות:

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

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

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

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

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

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

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

המסוף

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

    כניסה לדף IAM

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

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

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

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

    • כדי להקצות תפקיד לחשבון משתמש שאין לו תפקידים קיימים במשאב, לוחצים על Grant Access ואז מזינים מזהה של חשבון משתמש. לדוגמה, //iam.googleapis.com/locations/global/workforcePools/my-pool/subject/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 de Confiance , מפעילים את Cloud Shell.

    הפעלת Cloud Shell

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

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

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

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

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

    • ‏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: מזהה הפרויקט ב- Cloud de Confiance . מזהי פרויקטים מכילים אותיות וספרות, למשל 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 user (צפייה ועריכה) גישה לסשנים שיש להם רק מזהי משתמשים 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. ListSessions תמיכה ב-API: ListSessions API לא תומך בתנאי IAM. כדי לתת הרשאות ListSessions, צריך לתת לישות תפקיד ללא תנאי, כמו aiplatform.googleapis.com/sessionViewer, ‏aiplatform.googleapis.com/sessionUser או תפקיד רלוונטי ללא תנאי בפלטפורמת הסוכנים של Gemini Enterprise.