تتيح لك 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"
لتعيين الأدوار للمستخدمين الذين يمكنهم الوصول إلى امتيازاتهم من خلال
وحدة تحكم المشرف، قد يلزم منح بعض الامتيازات الإضافية. على سبيل المثال، لمنح مستخدم إمكانية إنشاء مستخدمين آخرين من خلال
وحدة تحكّم المشرف، لا يتطلب ذلك امتياز USERS_CREATE
فحسب،
بل يجب أيضًا منح امتيازَي USERS_UPDATE
وORGANIZATION_UNITS_RETRIEVE
. ويربط الجدول التالي وظائف "وحدة تحكُّم المشرف" بمنح الامتيازات المطلوبة لإدارة المستخدمين والوحدات التنظيمية.
وظائف "وحدة تحكُّم المشرف" | الامتيازات المطلوبة |
---|---|
الوحدات التنظيمية - القراءة | 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
كرقم تعريفي للعميل.إذا كنت مورّدًا تحصل على امتيازات لأحد عملائك، استخدِم الرقم التعريفي للعميل الذي تعرضه عملية استرداد حساب مستخدم.
الطلب
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
الإجابة
تعرض الاستجابة الناجحة رمز حالة 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
},
...
]
}
إدراج جميع تعيينات الأدوار
للحصول على قائمة مقسّمة على صفحات تضمّ جميع مهام الأدوار المباشرة، استخدِم طريقة
roleAssignments.list()
. قد تعرِض واجهة برمجة التطبيقات نتائج فارغة برمز الصفحة المميّز عند ضبط معلَمة userKey
. يجب عليك متابعة التقسيم على صفحات حتى لا يتم عرض الرمز المميز للصفحة.
إذا كنت مشرفًا يحصل على عمليات إسناد أدوار في نطاقك، استخدِم
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()
.
قد تعرض واجهة برمجة التطبيقات نتائج فارغة تتضمّن رمزًا مميّزًا للصفحة. يجب متابعة التقسيم على صفحات حتى لا يتم عرض أي رمز مميز للصفحة.
إذا كنت مشرفًا يحصل على عمليات إسناد أدوار في نطاقك، استخدِم
my_customer
كرقم تعريفي للعميل.إذا كنت مورّدًا تحصل على تعيينات الأدوار لأحد عملائك، استخدِم الرقم التعريفي للعميل الذي تعرضه عملية استرداد مستخدم.
استبدِل
USER_KEY
بقيمة تحدِّد المستخدم في طلب البيانات من واجهة برمجة التطبيقات. لمزيد من المعلومات، يُرجى الاطّلاع على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
لكل امتياز يجب منحه لهذا الدور. بالنسبة إلى خصائص الطلب والاستجابة، يمكنك الاطّلاع على مرجع واجهة برمجة التطبيقات.
الطلب
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
التالية وأدرِج التفويض
الموضّح في
طلبات التفويض.
لتعيين الدور إلى مستخدم، أضِف نص 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" }
الإجابة
تعرض الاستجابة الناجحة رمز حالة 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
. يجب استخدام سلسلتَي الشرطَين حرفيًا كما هو موضّح أدناه، ولا تعمل إلا مع أدوار المشرف المحدّدة مسبقًا لـ "محرّر المجموعات" وقارئ "مجموعات 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'" }
الإجابة
تعرض الاستجابة الناجحة رمز حالة 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'"
}