שליטה בגישה ל-Memory Bank באמצעות תנאי IAM

Memory Bank מאפשר לכם לשלוט בגישה לזיכרונות ולמשאבי גרסאות זיכרון על סמך מאפייני ההיקף שלהם. אתם יכולים להשתמש בתנאים של IAM כדי להגדיר אמצעי בקרת גישה מפורטים, כמו הגבלת הגישה למשתמשים או לקבוצות ספציפיים על סמך קריטריונים שמוגדרים ב-Common Expression Language.

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

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

סקירה כללית

תנאי IAM מאפשרים לתת גישה למשאבי זיכרון ולגרסאות זיכרון רק אם מתקיימים תנאים ספציפיים. אתם יכולים לשלוט בגישה לזיכרונות על סמך השדה scope במשאב זיכרון באמצעות מאפיין ה-API‏ "aiplatform.googleapis.com/memoryScope" עם ביטוי שנכתב ב-Common Expression Language. ההיקף הוא מילון שרירותי שמסופק כשיוצרים או מייצרים זיכרונות, כמו {'user_id': '123'}, ומאפשר לארגן את הזיכרונות כך שכל אחד מהם ישתייך לקבוצה מסוימת.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

יצירת גישה מותנית לזיכרונות

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

לקבלת מדריך מפורט ליצירת מדיניות 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 המיוחדים של Memory Bank.

  5. מוסיפים תנאי לתפקיד, באמצעות aiplatform.googleapis.com/memoryScope כמאפיין ה-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 המיוחדים של Memory Bank.

    • ‫CONDITION: מוסיפים תנאי לתפקיד באמצעות aiplatform.googleapis.com/memoryScope כמאפיין ה-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       = "Memory Access Condition"
    description = "IAM condition for Memory Bank"
    expression  = "CONDITION"
  }
}

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

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

  • ‫ROLE: תפקיד ה-IAM שרוצים להקצות, למשל, roles/aiplatform.memoryEditor.

  • ‫MEMBER: החשבון הראשי שרוצים להקצות לו את התפקיד, למשל user:developerA@corp.com. רשימה מלאה של הערכים שיכולים להיות ל-MEMBER מופיעה במאמר מזהים של חשבונות משתמשים.

  • CONDITION: הצהרת תנאי ה-IAM באמצעות aiplatform.googleapis.com/memoryScope כמאפיין ה-API. בדוגמאות שבהמשך מופיעות כמה הצהרות אפשריות של תנאים.

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

כשיוצרים תנאים ל-Memory Bank, כדאי להשתמש בשיטות המומלצות הבאות:

  1. שימוש בתפקידים מיוחדים ב-Memory Bank: צריך להשתמש בתנאי IAM של Memory Bank רק לתפקידים שחלים על זיכרונות ועל גרסאות של זיכרונות. כדי למנוע גישה עם הרשאות רחבות מדי, אפשר להשתמש בתפקידים ייעודיים כמו aiplatform.googleapis.com/memoryViewer, ‏aiplatform.googleapis.com/memoryEditor ו-aiplatform.googleapis.com/memoryUser. פרטים נוספים זמינים במאמר בנושא תפקידים ב-IAM של Specialized Memory Bank.

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

  3. קיצור תנאים ככל האפשר: מומלץ להשתמש בלוגיקה הקצרה והפשוטה ביותר בביטויי תנאי IAM, במיוחד אם אתם מתכננים להשתמש בכמות גדולה של תנאים. יש מגבלת גודל לכללי מדיניות ההרשאה ב-IAM, ופישוט התנאים מונע חריגה מהמגבלות האלה. פרטים נוספים מופיעים במאמר בנושא מגבלות. לדוגמה, אפשר להשמיט את הבדיקה של נוכחות מפתח בביטוי 'user_id' in api.getAttribute('aiplatform.googleapis.com/memoryScope', {}) && api.getAttribute('aiplatform.googleapis.com/memoryScope', {})['user_id'] == 'userA' ולהשתמש במקום זאת בהצהרה הקצרה יותר api.getAttribute('aiplatform.googleapis.com/memoryScope', {})['user_id'] == 'userA'. אם המפתח user_id חסר, הביטוי הארוך יותר מחזיר את הערך false, ואילו הביטוי הקצר יותר מחזיר שגיאה. מכיוון ששגיאות בביטויי תנאי IAM גורמות לדחיית הגישה, שני הביטויים מניבים את אותה תוצאה.

תפקידי IAM מיוחדים ב-Memory Bank

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

שם התפקיד תיאור ההרשאות הכלולות
roles/aiplatform.memoryViewer התפקיד הזה מאפשר גישה לקריאה בלבד של זיכרונות וגרסאות של זיכרונות.
  • aiplatform.googleapis.com/memories.get
  • aiplatform.googleapis.com/memories.list
  • aiplatform.googleapis.com/memories.retrieve
  • aiplatform.googleapis.com/memoryRevisions.list
  • aiplatform.googleapis.com/memoryRevisions.get
roles/aiplatform.memoryEditor ההרשאה הזו מאפשרת לכתוב ולייצר גישה לזיכרונות, ולבטל שינויים בגרסאות של זיכרונות.
  • aiplatform.googleapis.com/memories.create
  • aiplatform.googleapis.com/memories.update
  • aiplatform.googleapis.com/memories.delete
  • aiplatform.googleapis.com/memories.generate
  • aiplatform.googleapis.com/memoryRevisions.rollback
roles/aiplatform.memoryUser התפקיד הזה נותן גישה מלאה לזיכרונות ולגרסאות קודמות, כולל כל ההרשאות של צפייה ועריכה. התפקיד כולל את כל ההרשאות של memoryEditor וגם של memoryViewer.

שימוש בתנאי IAM עם Memory Bank

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

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

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

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

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

  5. מתן גישה מלאה לזיכרונות עם היקף המפתח באמצעות קבוצה של ערכים מותרים.

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

התנאי הבא מעניק לאדם userA@gmail.com גישת צפייה בלבד בזיכרונות עם היקף ההרשאות {"userId": "userA"}.

המשמעות היא שהמשתמש יכול לקבל ולאחזר זיכרונות, וגם לראות את הגרסאות הקודמות של הזיכרונות האלה, כל עוד ההיקף הוא בדיוק {"userId": "userA"}. למשתמש אין גישה לזיכרונות עם היקף כמו {'userId': 'userA', 'source': 'ADK'}.

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

הענקת גישת כתיבה לזיכרונות עם היקף שמכיל צמד ספציפי של מפתח/ערך

התנאי הבא נותן לאדם developerA@corp.com גישת עריכה לכל הזיכרונות שמכילים את צמד המפתח/ערך 'userId': 'userA'.

המשמעות היא שהמשתמש יכול ליצור, לעדכן, למחוק ולייצר זיכרונות, וליצור ולבטל שינויים בזיכרונות האלה, עם היקפים כמו {'userId': 'userA'} ו-{'userId': 'userA', 'source': 'ADK'}.

{
  "members": ["user:developerA@corp.com"],
  "role": "roles/aiplatform.memoryEditor",
  "condition": {
    "title": "Memory Access Condition",
    "expression": "api.getAttribute('aiplatform.googleapis.com/memoryScope', {})['userId'] == 'userA'"
  }
}

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

התנאי הבא מעניק לקבוצה group:engineering@corp.com גישה (צפייה ועריכה) לזיכרונות עם המפתח 'admin_override' או 'public_access_flag'.

כלומר, לחברי הקבוצה יש גישת קריאה וכתיבה מלאה לזיכרונות עם היקפים כמו {'admin_override': 'true'}, ‏ {'admin_override': 'true', 'public_access_flag': 'false'} ו-{'userId': 'userA', 'public_access_flag': 'false'}.

{
  "members": ["group:engineering@corp.com"],
  "role": "roles/aiplatform.memoryUser",
  "condition": {
    "title": "Memory Access Condition",
    "expression": "('admin_override' in api.getAttribute('aiplatform.googleapis.com/memoryScope', {})) || ('public_access_flag' in api.getAttribute('aiplatform.googleapis.com/memoryScope', {}))"
  }
}

הענקת גישה מלאה לזיכרונות עם היקף שכולל תחילית ספציפית

התנאי הבא מעניק לקבוצת המשתמשים group:engineering@corp.com (צפייה ועריכה) גישה לזיכרונות עם המפתח 'userId' והערך שמתחיל ב-'user'.אפשר להשתמש ב-'startsWith' לבדיקת קידומת וב-'endsWith' לבדיקת סיומת.

המשמעות היא שלחברי הקבוצה יש גישת קריאה וכתיבה מלאה לזיכרונות עם היקפים כמו {'userId': 'userA'}, {'userId': 'userB', 'public_access_flag': 'false'}.

{
  "members": ["group:engineering@corp.com"],
  "role": "roles/aiplatform.memoryUser",
  "condition": {
    "title": "Memory Access Condition",
    "expression": "api.getAttribute('aiplatform.googleapis.com/memoryScope', {})['userId'].startsWith('user')"
  }
}

מתן גישה מלאה לזיכרונות עם היקף המפתח וקבוצה של ערכים מותרים

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

המשמעות היא שלחברי הקבוצה יש גישת קריאה וכתיבה מלאה לזיכרונות עם היקפים כמו {'userId': 'userA'}, {'userId': 'userB', 'public_access_flag': 'false'}.

{
  "members": ["group:engineering@corp.com"],
  "role": "roles/aiplatform.memoryUser",
  "condition": {
    "title": "Memory Access Condition",
    "expression": "api.getAttribute('aiplatform.googleapis.com/memoryScope', {})['userId'] in ['userA', 'userB']"
  }
}

מגבלות

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

  • תמיכה ב-API: תנאי IAM לא נתמכים על ידי שיטות שפועלות במספר היקפים, כמו ListMemories ו-PurgeMemories. כדי להעניק את ההרשאות האלה, צריך להקצות לישות תפקיד לא מותנה, כמו aiplatform.googleapis.com/memoryViewer או aiplatform.googleapis.com/memoryUser, או תפקיד רלוונטי לא מותנה בפלטפורמת הסוכנים של Gemini Enterprise.