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

בדף הזה מוסבר איך אדמינים של Gemini Enterprise יכולים להשתמש ב-API כדי לנהל בקרת גישה מפורטת לאפליקציות ספציפיות של Gemini Enterprise.

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

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

• הגבלת הגישה של משתמשים לאפליקציות ספציפיות באותו פרויקט Google Cloud .
• התאמת ההרשאות לצורכי הארגון ולסילו נתונים בפריסות של Gemini Enterprise.

חשוב: הרשאות IAM ברמת הפרויקט קודמות למדיניות ברמת האפליקציה. אם למשתמש יש תפקיד של משתמש Gemini Enterprise ‏(roles/discoveryengine.agentspaceUser) ברמת הפרויקט, הוא יכול לגשת לכל האפליקציות בפרויקט הזה, בלי קשר להרשאות ברמת האפליקציה. כדי להגביל את הגישה של משתמש לאפליקציות ספציפיות, מחליפים את התפקיד Gemini Enterprise User ברמת הפרויקט בתפקיד Gemini Enterprise Restricted User ‏(roles/discoveryengine.agentspaceRestrictedUser), ואז מקצים את התפקיד Gemini Enterprise User לכל אפליקציה שהמשתמש צריך לגשת אליה.

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

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

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

• מוודאים שיש לכם את התפקיד אדמין של Gemini Enterprise (roles/discoveryengine.agentspaceAdmin).

• מוודאים שלכל המשתמשים ב-Gemini Enterprise יש רישיון תקף ושהוקצה להם התפקיד Gemini Enterprise Restricted User (roles/discoveryengine.agentspaceRestrictedUser) ברמת הפרויקט. הוראות מפורטות מופיעות במאמר איך מעניקים הרשאות למשתמשים.

  התפקיד הזה לא מעניק גישה לאף אפליקציה בפני עצמו. היא מספקת את הגישה ברמת הפרויקט שהמשתמשים צריכים, ואז אתם מעניקים גישה לאפליקציות ספציפיות. אם אתם משתמשים בתפקיד מותאם אישית ברמת הפרויקט במקום בתפקיד המוגדר מראש roles/discoveryengine.agentspaceRestrictedUser, ודאו שהתפקיד המותאם אישית כולל את ההרשאות discoveryengine.locations.buildAuthorizationUrl,‏ discoveryengine.dataStores.get,‏ discoveryengine.collections.get ו-discoveryengine.devToolsConfigs.get. השמטה של discoveryengine.devToolsConfigs.get גורמת לשגיאה 403 PERMISSION_DENIED ביומני הביקורת של Cloud כשבודקים את אפליקציית האינטרנט devToolsConfig.

מעבר מגישה ברמת הפרויקט לגישה ברמת האפליקציה

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

כדי להעביר משתמש מגישה ברמת הפרויקט לגישה ברמת האפליקציה, פועלים לפי השלבים הבאים. משתמשים במסוף Google Cloud לשינויים ברמת הפרויקט, וב-API להענקת הרשאה ברמת האפליקציה, שאותה אי אפשר לבצע במסוף Google Cloud .

1. נכנסים לדף IAM במסוף Google Cloud .
2. מחפשים את המשתמש ומסירים את התפקיד Gemini Enterprise User (roles/discoveryengine.agentspaceUser) מההרשאות שלו ברמת הפרויקט.
3. אם עדיין לא עשיתם את זה, צריך להקצות למשתמש את התפקיד Gemini Enterprise Restricted User ‏(roles/discoveryengine.agentspaceRestrictedUser) ברמת הפרויקט.
4. משתמשים בשיטה setIamPolicy כדי להעניק למשתמש את התפקיד 'משתמש Gemini Enterprise' (roles/discoveryengine.agentspaceUser) לכל אפליקציה ספציפית שהוא צריך לגשת אליה. מידע נוסף מופיע במאמר ניהול מדיניות IAM לאפליקציות.

ניהול מדיניות IAM לאפליקציות

כדי לנהל את הגישה לאפליקציית Gemini Enterprise, אפשר להשתמש בשיטות ה-API‏ getIamPolicy ו-setIamPolicy.

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

קבלת מדיניות IAM של האפליקציה

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

REST

מונח חשוב: ב-Gemini Enterprise, המונח אפליקציה יכול לשמש לחלופין למונח מנוע בהקשר של ממשקי API. מנוע Gemini Enterprise הוא מנוע חיפוש כללי שבו השדה app_type מוגדר ל-APP_TYPE_INTRANET.

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID:getIamPolicy"

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

• ‫PROJECT_ID: מזהה הפרויקט.
• ‫ENDPOINT_LOCATION: האזור הרב-אזורי של בקשת ה-API. מציינים אחד מהערכים הבאים:
  • ‫us לאזור הגיאוגרפי בארה"ב שכולל מספר אזורים
  • ‫eu עבור מספר אזורים באיחוד האירופי
  • ‫global למיקום הגלובלי
  מידע נוסף זמין במאמר בנושא ציון אזור מרובה עבור מאגר הנתונים.
• ‫LOCATION: האזור המרובה של מאגר הנתונים: ‫global,‏ us או eu

• ‫APP_ID: המזהה של האפליקציה שרוצים להגדיר.

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

דוגמה לפקודה ולתוצאה

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://global-discoveryengine.googleapis.com/v1/projects/my-project-123/locations/global/collections/default_collection/engines/my-app:getIamPolicy"

{
  "version": 1,
  "etag": "1234567890"
}
  

עדכון מדיניות ה-IAM של האפליקציה

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

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

במדיניות IAM נעשה שימוש בתפקיד Gemini Enterprise User (roles/discoveryengine.agentspaceUser) כדי להעניק למשתמשים גישה ישירה לאפליקציה.

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

REST

מונח חשוב: ב-Gemini Enterprise, המונח אפליקציה יכול לשמש לחלופין למונח מנוע בהקשר של ממשקי API. מנוע Gemini Enterprise הוא מנוע חיפוש כללי שבו השדה app_type מוגדר ל-APP_TYPE_INTRANET.

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d '{
      "policy": {
         "etag": "ETAG",
         "bindings": [
          {
            "role": "roles/discoveryengine.agentspaceUser",
            "members": [
              "user:USER_EMAIL",
              "group:GROUP_EMAIL",
              "principal://iam.googleapis.com/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT_ID",
              "principalSet://iam.googleapis.com/locations/global/workloadIdentityPools/POOL_ID/attribute.NAME/VALUE"
            ]
          }
        ]
      }
    }' \
"https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID:setIamPolicy"

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

• ‫ETAG: הערך etag שקיבלתם בתגובה כשנעשה שימוש ב-method getIamPolicy.

• ‫USER_EMAIL, GROUP_EMAIL: כתובת אימייל אחת או יותר של משתמשים או קבוצות. בנוסף ל-user ול-group,‏ principal ו-principalSet הם סוגי חברים תקינים באיחוד שירותי אימות הזהות של עומסי עבודה.

  • כדי להעניק גישה, מוסיפים חשבונות משתמשים למערך members. לדוגמה, "user:[e-mail]" או "group:[e-mail]".

    הערה: חשוב להימנע מרווחים מיותרים לפני כתובת האימייל או אחריה.

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

• ‫POOL_ID: המזהה של מאגר הזהויות של עומסי עבודה.

• ‫SUBJECT_ID: מזהה הנושא של זהות ספציפית.

• ‫NAME: השם של מאפיין.

• ‫VALUE: הערך של מאפיין.

• ‫PROJECT_ID: מזהה הפרויקט.

• ‫ENDPOINT_LOCATION: האזור הרב-אזורי של בקשת ה-API. מציינים אחד מהערכים הבאים:

  • ‫us לאזור הגיאוגרפי בארה"ב שכולל מספר אזורים
  • ‫eu עבור מספר אזורים באיחוד האירופי
  • ‫global Global location
  מידע נוסף זמין במאמר בנושא ציון אזור מרובה עבור מאגר הנתונים.

• ‫LOCATION: האזור המרובה של מאגר הנתונים: ‫global,‏ us או eu.

• ‫APP_ID: המזהה של האפליקציה שרוצים להגדיר.

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

דוגמה לפקודה ולתוצאה

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d '{
      "policy": {
         "etag": "1234567890",
         "bindings": [
          {
            "role": "roles/discoveryengine.user",
            "members": [
              "user:[e-mail]",
              "group:[e-mail]"
            ]
          }
        ]
      }
    }' \
"https://global-discoveryengine.googleapis.com/v1/projects/my-project-123/locations/global/collections/default_collection/engines/my-app:setIamPolicy"

{
  "version": 1,
  "etag": "2345678901",
  "bindings": [
    {
      "role": "roles/discoveryengine.user",
      "members": [
        "user:cloudysanfrancisco.com",
        "group:[e-mail]"
      ]
    }
  ]
}
  

מה השלב הבא?

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