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

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

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

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

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

חשוב: הרשאות IAM ברמת הפרויקט קודמות לכללי מדיניות ברמת האפליקציה. אם למשתמש יש את התפקיד Gemini Enterprise User (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" (roles/discoveryengine.agentspaceUser) מההרשאות שלו ברמת הפרויקט.
3. אם עדיין לא עשיתם את זה, מקצים למשתמש את התפקיד "משתמש עם הרשאות מוגבלות ב-Gemini Enterprise" (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 למיקום הגלובלי
  מידע נוסף זמין במאמר הגדרת מספר אזורים למאגר הנתונים.

• ‫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.