ניהול תפקידים

באמצעות Directory API אפשר להשתמש בבקרת גישה מבוססת-תפקידים (RBAC) כדי לנהל את הגישה לתכונות בדומיין של Google Workspace. אתם יכולים ליצור תפקידים בהתאמה אישית עם הרשאות כדי להגביל את הגישה של האדמינים באופן ספציפי יותר מאשר התפקידים המוגדרים מראש שכלולים ב-Google Workspace. אפשר להקצות תפקידים למשתמשים או לקבוצות אבטחה. במדריך הזה נסביר איך לבצע כמה משימות בסיסיות שקשורות לתפקידים.

ריכזנו כאן רשימה של מונחים נפוצים שנעשה בהם שימוש ב-Directory API בנוגע ל-RBAC ב-Google Workspace:

הרשאה
ההרשאה הנדרשת לביצוע משימה או פעולה בדומיין של Google Workspace. מיוצג על ידי המשאב Privilege. אין נתונים קבועים שמשויכים למשאב הזה.
תפקיד
אוסף של הרשאות שמעניק לישות עם התפקיד הזה את היכולת לבצע משימות או פעולות מסוימות. מיוצג על ידי המשאב Role.
הקצאת תפקידים
הרשומה של תפקיד מסוים שהוקצה למשתמש או לקבוצה. הוא מיוצג על ידי המשאב RoleAssignment.
קבוצת אבטחה
סוג של קבוצה ב-Cloud Identity שמשמשת לבקרת הגישה למשאבים ארגוניים. קבוצות אבטחה יכולות לכלול גם משתמשים ספציפיים וגם קבוצות.

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

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

  • אפשר ליצור עד 750 תפקידים בהתאמה אישית לכל הארגון.
  • אפשר ליצור עד 1,000 הקצאות תפקידים לכל יחידה ארגונית (OU), כאשר הארגון ברמה הבסיסית נחשב ליחידה. לדוגמה, אפשר להקצות 600 תפקידים בארגון ברמה הבסיסית (root) ו-700 תפקידים ב-OU אחר שהגדרתם, כמו מחלקה בחברה. ברירת המחדל של כל תפקידי האדמין המוגדרים מראש ב-Google Workspace היא ברמת הארגון. מידע נוסף על המגבלות על ההרשאות שאפשר להקצות ברמת ה-OU

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

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

אם אתם צריכים להקצות יותר מ-1,000 תפקידים ב-OU, תוכלו להוסיף כמה משתמשים לקבוצת אבטחה ולהקצות תפקיד לקבוצה. להקצאות של תפקידים לקבוצות יש מגבלות נוספות. מידע ספציפי זמין במרכז העזרה לאדמינים.

מיפוי של תפקידים להרשאות במסוף Google Admin

כדי להקצות תפקידים למשתמשים שיכולים לגשת להרשאות שלהם דרך מסוף Admin, יכול להיות שתצטרכו להעניק להם הרשאות נוספות מסוימות. לדוגמה, כדי לתת למשתמש את היכולת ליצור משתמשים אחרים דרך מסוף Admin, נדרשת לא רק ההרשאה USERS_CREATE, אלא גם ההרשאות USERS_UPDATE ו-ORGANIZATION_UNITS_RETRIEVE. בטבלה הבאה מפורטת המיפוי של הפונקציונליות של מסוף Admin להרשאות הנדרשות לניהול משתמשים ויחידות ארגוניות.

הפונקציונליות של מסוף Admin ההרשאות הנדרשות
יחידות ארגוניות – קריאה ORGANIZATION_UNITS_RETRIEVE
יחידות ארגוניות – יצירה ORGANIZATION_UNITS_RETRIEVE + ORGANIZATION_UNITS_CREATE
יחידות ארגוניות – עדכון ORGANIZATION_UNITS_RETRIEVE + ORGANIZATION_UNITS_UPDATE
יחידות ארגוניות – מחיקה ORGANIZATION_UNITS_RETRIEVE + ORGANIZATION_UNITS_DELETE
יחידות ארגוניות ORGANIZATION_UNITS_ALL
משתמשים – קריאה USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE
משתמשים – יצירה ‫USERS_CREATE‏ +‏ USERS_UPDATE‏ +‏ ORGANIZATION_UNITS_RETRIEVE
משתמשים – עדכון USERS_UPDATE + ORGANIZATION_UNITS_RETRIEVE
משתמשים – העברת משתמשים ‫USERS_MOVE‏ +‏ USERS_RETRIEVE‏ +‏ ORGANIZATION_UNITS_RETRIEVE
משתמשים – שינוי שמות של משתמשים ‫USERS_ALIAS‏ +‏ USERS_RETRIEVE‏ +‏ ORGANIZATION_UNITS_RETRIEVE
משתמשים – איפוס סיסמה ‫USERS_RESET_PASSWORD‏ +‏ USERS_RETRIEVE‏ +‏ ORGANIZATION_UNITS_RETRIEVE
משתמשים – אילוץ שינוי סיסמה ‫USERS_FORCE_PASSWORD_CHANGE‏ +‏ USERS_RETRIEVE‏ +‏ ORGANIZATION_UNITS_RETRIEVE
משתמשים – הוספה/הסרה של כינויים ‫USERS_ADD_NICKNAME‏ +‏ USERS_RETRIEVE‏ +‏ ORGANIZATION_UNITS_RETRIEVE
משתמשים – השעיית משתמשים ‫USERS_SUSPEND‏ +‏ USERS_RETRIEVE‏ +‏ ORGANIZATION_UNITS_RETRIEVE
קבוצות GROUPS_ALL
אבטחה – ניהול אבטחת משתמשים ‫USER_SECURITY_ALL‏ +‏ USERS_RETRIEVE‏ +‏ ORGANIZATION_UNITS_RETRIEVE

דוגמאות לתרחישים לדוגמה

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

משלימים את השלבים של האימות וההרשאה ב-Google Workspace.

הצגת רשימה של הרשאות הדומיין

כדי לקבל רשימה מחולקת לדפים של ההרשאות הנתמכות בדומיין, משתמשים בשיטה privileges.list().

  • אם אתם אדמינים שמקבלים הרשאות בדומיין שלכם, צריך להשתמש ב-my_customer בתור מזהה הלקוח.

  • אם אתם מפיצים שמקבלים הרשאות לאחד מהלקוחות שלכם, תוכלו להשתמש במזהה הלקוח שמוחזר על ידי הפעולה Retrieve a user.

בקשה

GET https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roles/ALL/privileges

תשובה

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

{
  "kind": "admin\#directory\#privileges",
  "etag": ...,
  "items": [
    {
      "kind": "admin\#directory\#privilege",
      "etag": ...,
      "serviceId": "02afmg282jiquyg",
      "privilegeName": "APP_ADMIN",
      "isOuScopable": false
    },
    {
      "kind": "admin\#directory\#privilege",
      "etag": ...,
      "serviceId": "04f1mdlm0ki64aw",
      "privilegeName": "MANAGE_USER_SETTINGS",
      "isOuScopable": true,
      "childPrivileges": [
        {
          "kind": "admin\#directory\#privilege",
          "etag": ...,
          "serviceId": "04f1mdlm0ki64aw",
          "privilegeName": "MANAGE_APPLICATION_SETTINGS",
          "isOuScopable": true
        }
      ]
    },
    ...
  ]
}

אחזור של תפקידים קיימים

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

  • אם אתם אדמינים שמקבלים תפקידים בדומיין שלכם, השתמשו ב-my_customer בתור מזהה הלקוח.

  • אם אתם מפיצים שמקבלים תפקידים עבור לקוח, צריך להשתמש במזהה הלקוח שקיבלת באמצעות הפעולה Retrieve a user.

בקשה

GET https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roles

תשובה

בתגובה מוצלחת מוחזר קוד סטטוס HTTP 200. יחד עם קוד הסטטוס, התשובה מחזירה את התפקידים שקיימים בדומיין:

{
  "kind": "admin\#directory\#roles",
  "etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/DywA6_jaJCYw-f0lFs2-g17UWe8\"",
  "items": [
    {
      "kind": "admin\#directory\#role",
      "etag": ... ,
      "roleId": "3894208461012993",
      "roleName": "_SEED_ADMIN_ROLE",
      "roleDescription": "Google Workspace Administrator Seed Role",
      "rolePrivileges": [
        {
          "privilegeName": "SUPER_ADMIN",
          "serviceId": "01ci93xb3tmzyin"
        },
        {
          "privilegeName": "ROOT_APP_ADMIN",
          "serviceId": "00haapch16h1ysv"
        },
        {
          "privilegeName": "ADMIN_APIS_ALL",
          "serviceId": "00haapch16h1ysv"
        },
        ...
      ],
      "isSystemRole": true,
      "isSuperAdminRole": true
    },
    {
      "kind": "admin\#directory\#role",
      "etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/bTXiZXfuK1NGr_f4paosCWXuHmw\"",
      "roleId": "3894208461012994",
      "roleName": "_GROUPS_ADMIN_ROLE",
      "roleDescription": "Groups Administrator",
      "rolePrivileges": [
        {
          "privilegeName": "CHANGE_USER_GROUP_MEMBERSHIP",
          "serviceId": "01ci93xb3tmzyin"
        },
        {
          "privilegeName": "USERS_RETRIEVE",
          "serviceId": "00haapch16h1ysv"
        },
        {
          "privilegeName": "GROUPS_ALL",
          "serviceId": "00haapch16h1ysv"
        },
        {
          "privilegeName": "ADMIN_DASHBOARD",
          "serviceId": "01ci93xb3tmzyin"
        },
        {
          "privilegeName": "ORGANIZATION_UNITS_RETRIEVE",
          "serviceId": "00haapch16h1ysv"
        }
      ],
      "isSystemRole": true
    },
    ...
  ]
}

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

כדי לקבל רשימה מחולקת לדפים של כל הקצאות התפקידים הישירות, משתמשים ב-method‏ roleAssignments.list(). יכול להיות שה-API יחזיר תוצאות ריקות עם אסימון דף כשהפרמטר userKey מוגדר. צריך להמשיך את החלוקה לדפים עד שלא מוחזר אסימון דף.

  • אם אתם אדמינים שמקבלים הקצאות תפקידים בדומיין שלכם, תוכלו להשתמש ב-my_customer בתור מזהה הלקוח.

  • אם אתם מפיצים שמקבלים הקצאות תפקידים לאחד מהלקוחות שלכם, תוכלו להשתמש במזהה הלקוח שמוחזר על ידי הפעולה Retrieve a user.

בקשה

GET https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roleassignments

תשובה

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

{
  "kind": "admin\#directory\#roleAssignment",
  "etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/VdrrUEz7GyXqlr9I9JL0wGZn8yE\"",
  "roleAssignmentId:"3894208461013211",
  "assignedTo:"100662996240850794412",
  "assigneeType:"user",
  "scopeType:"CUSTOMER",
}

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

כדי לקבל רשימה מחולקת לדפים של כל הקצאות התפקידים, כולל אלה שהוקצו למשתמש באופן עקיף בגלל הקבוצות שהוא שייך אליהן, משתמשים ב-method‏ roleAssignments.list().

יכול להיות שה-API יחזיר תוצאות ריקות עם אסימון דף. צריך להמשיך בעימוד עד שלא מוחזר אסימון דף.

  • אם אתם אדמינים שמקבלים הקצאות תפקידים בדומיין שלכם, תוכלו להשתמש ב-my_customer בתור מזהה הלקוח.

  • אם אתם מפיצים שמקבלים הקצאות תפקידים לאחד מהלקוחות שלכם, תוכלו להשתמש במזהה הלקוח שמוחזר על ידי הפעולה Retrieve a user.

  • מחליפים את הערך USER_KEY בערך שמזהה את המשתמש בבקשת ה-API. מידע נוסף זמין במאמר users.get.

בקשה

GET https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roleassignments?userKey=USER_KEY&includeIndirectRoleAssignments=true

תשובה

בתגובה מוצלחת מוחזר קוד סטטוס HTTP 200. יחד עם קוד הסטטוס, התשובה מחזירה את כל התפקידים שהוקצו בדומיין ואת הערך של assigneeType, שהוא user או group:

{
  "kind": "admin\#directory\#roleAssignment",
  "etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/VdrrUEz7GyXqlr9I9JL0wGZn8yE\"",
  "roleAssignmentId:"3894208461013211",
  "assignedTo:"100662996240850794412",
  "assigneeType:"group",
  "scopeType:"CUSTOMER",
}

יצירת תפקיד חדש

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

בקשה

POST https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roles

{
  "roleName": "My New Role",
  "rolePrivileges": [
    {
      "privilegeName": "USERS_ALL",
      "serviceId": "00haapch16h1ysv"
    },
    {
      "privilegeName": "GROUPS_ALL",
      "serviceId": "00haapch16h1ysv"
    }
  ]
}

תשובה

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

{
  "kind": "admin\#directory\#role",
  "etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/uX9tXw0qyijC9nUKgCs08wo8aEM\"",
  "roleId": "3894208461013031",
  "roleName": "My New Role",
  "rolePrivileges": [
    {
      "privilegeName": "GROUPS_ALL",
      "serviceId": "00haapch16h1ysv"
    },
    {
      "privilegeName": "USERS_ALL",
      "serviceId": "00haapch16h1ysv"
    }
  ]
}

יצירת הקצאת תפקיד

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

בקשה

POST https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roleassignments

{
  "roleId": "3894208461012995",
  "assignedTo": "100662996240850794412",
  "scopeType": "CUSTOMER"
}

תשובה

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

{
  "kind": "admin\#directory\#roleAssignment",
  "etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/VdrrUEz7GyXqlr9I9JL0wGZn8yE\"",
  "roleAssignmentId": "3894208461013211",
  "roleId": "3894208461012995",
  "assignedTo": "100662996240850794412",
  "scopeType": "CUSTOMER"
}

יצירת הקצאת תפקיד עם תנאים

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

  • רלוונטי רק לקבוצות אבטחה
  • לא רלוונטי לקבוצות אבטחה

כשמגדירים את condition, הוא ייכנס לתוקף רק כשהמשאב שאליו מתבצעת הגישה יעמוד בתנאי. אם השדה condition ריק, התפקיד (roleId) מוחל על הגורם (assignedTo) ברמת ההיקף (scopeType) ללא תנאי.

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

מוסיפים גוף JSON עם user_id של המשתמש, שאפשר לקבל מ-users.get(), את roleId כפי שמתואר בקטע קבלת תפקידים קיימים ואת condition. צריך להשתמש בשתי מחרוזות התנאי בדיוק כפי שמוצג בהמשך, והן פועלות רק עם תפקידי האדמין המובנים 'עריכת קבוצות' ו'קריאת קבוצות'. התנאים האלה פועלים לפי תחביר התנאים של Cloud IAM.

בקשה

רלוונטי רק לקבוצות אבטחה
POST https://admin.googleapis.com/admin/directory/v1.1beta1/customer/customer_id/roleassignments

{
  "roleId": "3894208461012995",
  "assignedTo": "100662996240850794412",
  "scopeType": "CUSTOMER",
  "condition": "api.getAttribute('cloudidentity.googleapis.com/groups.labels',
    []).hasAny(['groups.security']) && resource.type ==
    'cloudidentity.googleapis.com/Group'"
}
לא רלוונטי לקבוצות אבטחה
POST https://admin.googleapis.com/admin/directory/v1.1beta1/customer/customer_id/roleassignments

{
  "roleId": "3894208461012995",
  "assignedTo": "100662996240850794412",
  "scopeType": "CUSTOMER",
  "condition": "!api.getAttribute('cloudidentity.googleapis.com/groups.labels',
    []).hasAny(['groups.security']) && resource.type ==
    'cloudidentity.googleapis.com/Group'"
}

תשובה

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

{
  "kind": "admin\#directory\#roleAssignment",
  "etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/VdrrUEz7GyXqlr9I9JL0wGZn8yE\"",
  "roleAssignmentId": "3894208461013211",
  "roleId": "3894208461012995",
  "assignedTo": "100662996240850794412",
  "scopeType": "CUSTOMER",
  "condition": "!api.getAttribute('cloudidentity.googleapis.com/groups.labels',
    []).hasAny(['groups.security']) && resource.type ==
    'cloudidentity.googleapis.com/Group'"
}