באמצעות 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.
כדי להקצות את התפקיד למשתמש, מוסיפים גוף JSON עם
user_id
של המשתמש, שאותו ניתן לקבל מ-users.get()
, מה-roleId
(כפי שמתואר בהסבר על קבלת תפקידים קיימים) וה-scope_type
.כדי להקצות את התפקיד לחשבון שירות, מוסיפים גוף JSON עם
unique_id
של חשבון השירות (כפי שמוגדר בניהול זהויות והרשאות גישה (IAM)),roleId
(כפי שמתואר במאמר קבלת תפקידים קיימים) וב-scope_type
.כדי להקצות את התפקיד לקבוצה, מוסיפים גוף JSON עם
group_id
של הקבוצה, שאותו אפשר לקבל מ-groups.get()
, מה-roleId
(כפי שמתואר במאמר Get existing role) וה-scope_type
.
בקשה
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'"
}