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

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

في ما يلي قائمة بالمصطلحات الشائعة التي تستخدمها واجهة برمجة التطبيقات Directory API، بغض النظر عن RBAC ضمن Google Workspace:

الامتياز
الإذن اللازم لتنفيذ مهمة أو عملية في نطاق Google Workspace. ممثلة في المورد Privilege. ولا تتوفّر بيانات دائمة مرتبطة بهذا المورد.
الدور
مجموعة من الامتيازات التي تمنح الكيانات ذات هذا الدور القدرة على أداء مهام أو عمليات معيّنة. ممثلة في المورد Role.
إسناد الدور
سجلّ دور معيّن تم منحه للمستخدم أو المجموعة ممثلة في مورد RoleAssignment.
مجموعة الأمان
نوع من مجموعات Cloud Identity يتم استخدامها للتحكّم في الوصول إلى الموارد التنظيمية. يمكن أن تحتوي مجموعات الأمان على مستخدمين فرديين ومجموعات على حد سواء.

حدود الأدوار وإسناد الأدوار

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

  • ويمكنك إنشاء ما يصل إلى 750 دورًا مخصَّصًا لمؤسستك بأكملها.
  • يمكنك إنشاء ما يصل إلى 500 عملية تعيين أدوار لكل وحدة تنظيمية، حيث تُعتبر المؤسسة الجذر وحدة. على سبيل المثال، يمكنك تعيين 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 التالية وأدرِج التفويض الموضّح في طلبات التفويض.

الطلب

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. يجب استخدام سلسلتَي الشروط حرفيًا كما هو موضّح أدناه ولا تعمل إلا مع أدوار المشرف السابقة التحديد لمحرّر المجموعات وقارئ المجموعات. تتّبع هذه الشروط بنية شرط 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'"
}