דף זה תורגם על ידי Cloud Translation API.

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

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

בהמשך מופיעה רשימה של מונחים נפוצים שמשמשים ב-Directory API בהקשר של RBAC ב-Google Workspace:

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

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

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

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

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

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

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

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

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

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

לפני שמריצים את הדוגמאות במדריך הזה, צריך להגדיר אימות והרשאה.

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

כדי לקבל רשימה עם מספור עמודים של ההרשאות הנתמכות בדומיין, משתמשים בשיטה 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 כמזהה הלקוח.
אם אתם מפיצים שמקבלים תפקידים בשביל לקוח, אתם צריכים להשתמש במזהה הלקוח שקיבלתם באמצעות הפעולה אחזור משתמש.

בקשה

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

תשובה

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

{
  "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
    },
    ...
  ]
}

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

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

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

בקשה

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

תשובה

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

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

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

כדי לקבל רשימה עם מספור עמודים של כל הקצאות התפקידים, כולל אלה שהוקצו למשתמש באופן עקיף בגלל הקבוצות שהוא משתייך אליהן, משתמשים בשיטה 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

תשובה

תגובה מוצלחת מחזירה קוד סטטוס 200 של HTTP. בנוסף לקוד הסטטוס, התשובה מחזירה את כל התפקידים שהוקצו בדומיין ואם 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"
    }
  ]
}

תשובה

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

{
  "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 הבאה וכוללים את ההרשאה שמתוארת במאמר אישור בקשות.

כדי להקצות את התפקיד למשתמש, מוסיפים גוף JSON עם user_id של המשתמש, שאפשר לקבל מ-users.get(), עם roleId (כפי שמתואר במאמר קבלת תפקידים קיימים) ועם scope_type.
כדי להקצות את התפקיד לחשבון שירות, מוסיפים גוף JSON עם unique_id של חשבון השירות (כפי שמוגדר בניהול זהויות והרשאות גישה (IAM)), עם roleId (כפי שמתואר במאמר קבלת תפקידים קיימים) ועם scope_type.
כדי להקצות את התפקיד לקבוצה, מוסיפים גוף JSON עם group_id של הקבוצה, שאפשר לקבל מ-groups.get(), עם roleId (כפי שמתואר במאמר קבלת תפקידים קיימים) ועם scope_type.

בקשה

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

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

תשובה

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

{
  "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. צריך להשתמש בשני מחרוזות התנאים בדיוק כמו שמופיע בהמשך, והן פועלות רק עם תפקידי אדמין מובנים מראש של כלי העריכה של קבוצות Google וכלי הקריאה של קבוצות Google. התנאים האלה פועלים לפי תחביר התנאים ב-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'"
}

תשובה

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

{
  "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'"
}

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

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

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

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

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

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

בקשה

תשובה

קבלת תפקידים קיימים

בקשה

תשובה

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

בקשה

תשובה

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

בקשה

תשובה

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

בקשה

תשובה

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

בקשה

תשובה

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

בקשה

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

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

תשובה

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