إدارة الأدوار

تتيح لك Directory API استخدام التحكم في الوصول استنادًا إلى الدور (RBAC) لإدارة إمكانية الوصول إلى الميزات في نطاق Google Workspace. يمكنك إنشاء أدوار مخصَّصة مع امتيازات لتقييد وصول المشرف بشكل أكثر تحديدًا مقارنةً بالأدوار المحدَّدة مسبقًا المقدَّمة مع Google Workspace. يمكنك إسناد الأدوار إلى المستخدمين أو مجموعات الأمان. يوضّح هذا الدليل كيفية تنفيذ بعض المهام الأساسية المتعلّقة بالدور.

في ما يلي قائمة بالمصطلحات الشائعة التي تستخدمها Directory API في ما يتعلّق بإدارة الأذونات بالاستناد إلى الدور (RBAC) في Google Workspace:

الامتياز

الإذن اللازم لتنفيذ مهمة أو عملية في أحد نطاقات Google Workspace يُرمز إليه بالمورد Privilege. ليس هناك بيانات دائمة مرتبطة بهذا المورد.

Role

مجموعة من الامتيازات التي تمنح الكيانات التي تمتلك هذا الدور القدرة على تنفيذ مهام أو عمليات معيّنة. يُمثّل ذلك المورد Role.

إسناد الدور

سجلّ دور معيّن تم منحه للمستخدم أو المجموعة يتم تمثيله باستخدام موارد RoleAssignment.

مجموعة الأمان

نوع من مجموعات Cloud Identity يُستخدَم للتحكّم في الوصول إلى موارد المؤسسة. يمكن أن تحتوي مجموعات الأمان على مستخدمين فرديين ومجموعات.

حدود الأدوار وعمليات إسناد الأدوار

يمكنك إنشاء عدد محدود فقط من الأدوار المخصّصة أو عمليات إسناد الأدوار، لذا إذا كان عددها يقترب من الحدّ الأقصى، يمكنك دمجها أو إزالتها للبقاء ضمن الحدّ الأقصى. تنطبق الحدود التالية على الأدوار وتخصيصات الأدوار:

• يمكنك إنشاء ما يصل إلى 750 دورًا مخصّصًا لمؤسستك بأكملها.
• يمكنك إنشاء ما يصل إلى 1000 عملية إسناد دور لكل وحدة تنظيمية، حيث تُعدّ المؤسسة الجذر وحدة. على سبيل المثال، يمكنك تعيين 600 دور في المؤسسة الجذر و700 دور ضمن وحدة تنظيمية أخرى حدّدتها، مثل قسم في شركة. تكون جميع أدوار المشرف المُعدّة مسبقًا في Google Workspace مضبوطة تلقائيًا على النطاق على مستوى المؤسسة. اطّلِع على مزيد من المعلومات حول الحدود المفروضة على الامتيازات التي يمكن تعيينها على مستوى الوحدة التنظيمية.

تنطبق الحدود التالية على الأدوار وإسناد الأدوار للمجموعات:

• يمكنك إسناد أي دور باستثناء دور "المشرف المتميّز".
• يمكنك إسناد أدوار إلى 250 مجموعة في المجمل كحد أقصى على مستوى الوحدة التنظيمية ككل وداخل كل وحدة تنظيمية.
• يجب أن تكون المجموعة مجموعة أمان في مؤسستك.
• ننصح بقصر عضوية المجموعة على المستخدمين في مؤسستك. يمكنك إضافة مستخدمين من خارج مؤسستك، ولكن قد لا يحصلون على امتيازات الدور. لمعرفة التفاصيل، يُرجى الاطّلاع على تقييد عضوية المجموعة. ### تعيين الأدوار للمجموعات

إذا كنت بحاجة إلى منح أكثر من 1000 دور في وحدة تنظيمية، يمكنك إضافة عدة أعضاء إلى مجموعة أمان ومنح دور للمجموعة. تفرض عملية منح أدوار المجموعة بعض القيود الإضافية. يُرجى الاطّلاع على مركز مساعدة المشرف للحصول على معلومات محدّدة.

ربط الأدوار بالامتيازات في "وحدة تحكّم المشرف في 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 التالي وأضِف التفويض الموضّح في طلبات 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 التالية وأضِف التفويض описан في طلبات التفويض.

• لتعيين الدور user_id لمستخدم، أضِف نصًا بتنسيق 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" و"قارئ مجموعات 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'"
}