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

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

הרשימה הבאה מפרטת את המונחים הנפוצים שמשמשים את Directory API ביחס ל-RBAC בתוך Google Workspace:

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

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

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

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

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

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

הקצאת תפקיד לקבוצות

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

מיפוי תפקידים להרשאות במסוף 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.

קבלת רשימה של הרשאות דומיין

כדי לקבל רשימה מעומדת של ההרשאות הנתמכות בדומיין, משתמשים ב-method privileges.list().

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

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

בקשה

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 הבאה וכוללים את ההרשאה שמתוארת בקטע Authorize requests.

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

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

בקשה

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(). כשהפרמטר userKey מוגדר, ה-API עשוי להחזיר תוצאות ריקות עם אסימון דף. עליכם להמשיך את העימוד עד שלא יוחזר אסימון דף.

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

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

בקשה

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",
}

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

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

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

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

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

  • מחליפים את 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 הבאה וכוללים את ההרשאה שמתוארת בקטע Authorize requests. מוסיפים את 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 הבאה וכוללים את ההרשאה שמתוארת בקטע Authorize requests.

בקשה

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 הבאה ולכלול את ההרשאות שמתוארות בקטע Authorize requests.

מוסיפים גוף 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'"
}