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

تتيح لك 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'"
}