نقش ها را مدیریت کنید

Directory API به شما امکان می‌دهد از کنترل دسترسی مبتنی بر نقش (RBAC) برای مدیریت دسترسی به ویژگی‌های دامنه Google Workspace خود استفاده کنید. می‌توانید نقش‌های سفارشی با امتیازاتی ایجاد کنید تا دسترسی سرپرست را به‌طور خاص‌تری نسبت به نقش‌های از پیش ساخته‌شده ارائه شده با Google Workspace محدود کنید. می توانید نقش هایی را به کاربران یا گروه های امنیتی اختصاص دهید. این راهنما نحوه انجام برخی وظایف اساسی مرتبط با نقش را توضیح می دهد.

در زیر لیستی از اصطلاحات رایج مورد استفاده توسط Directory API با توجه به RBAC در Google Workspace است:

امتیاز

مجوز لازم برای انجام یک کار یا عملیات در دامنه Google Workspace. ارائه شده توسط منبع Privilege . هیچ داده دائمی مرتبط با این منبع وجود ندارد.

نقش

مجموعه ای از امتیازات که به نهادهای دارای آن نقش توانایی انجام وظایف یا عملیات معین را می دهد. ارائه شده توسط منبع Role .

تعیین نقش

رکورد یک نقش خاص که به کاربر یا گروه داده شده است. ارائه شده توسط منبع RoleAssignment .

گروه امنیتی

نوعی از Cloud Identity Group که برای کنترل دسترسی به منابع سازمانی استفاده می شود. گروه‌های امنیتی می‌توانند هم شامل کاربران و هم گروه‌ها باشند.

محدودیت های انتساب نقش و نقش

شما فقط می‌توانید تعداد محدودی از نقش‌های سفارشی یا تخصیص نقش ایجاد کنید، بنابراین اگر به حد مجاز نزدیک می‌شوید، آن‌ها را ادغام یا حذف کنید تا زیر حد باقی بمانید. نقش ها و تکالیف نقش دارای محدودیت های زیر است:

• شما می توانید تا 750 نقش سفارشی برای کل سازمان خود ایجاد کنید.
• شما می توانید تا 1000 انتساب نقش در هر واحد سازمانی (OU) ایجاد کنید، جایی که سازمان ریشه یک واحد در نظر گرفته می شود. به عنوان مثال، می توانید 600 نقش را در سازمان ریشه و 700 نقش را در OU دیگری که تعریف کرده اید، مانند بخش یک شرکت، اختصاص دهید. همه نقش‌های سرپرست از پیش ساخته شده Google Workspace به طور پیش‌فرض در محدوده سازمانی قرار دارند. درباره محدودیت‌های امتیازاتی که می‌توان در سطح OU اختصاص داد، بیشتر بیاموزید.

نقش ها و انتساب نقش محدودیت های زیر را برای گروه ها دارد:

• شما می توانید هر نقشی را به جز Super Admin اختصاص دهید.
• شما می توانید تا 250 انتساب نقش به گروه ها در مجموع در OU کلی و در هر OU داشته باشید.
• گروه باید یک گروه امنیتی در سازمان شما باشد.
• توصیه می کنیم عضویت گروه را به کاربران سازمان خود محدود کنید. می‌توانید کاربران خارج از سازمان خود را اضافه کنید، اما ممکن است امتیازات نقش را دریافت نکنند. برای جزئیات، به محدود کردن عضویت گروه مراجعه کنید. ### تعیین نقش به گروه ها

اگر نیاز به اختصاص بیش از 1000 نقش در یک OU دارید، می توانید چندین عضو را به یک گروه امنیتی اضافه کنید و نقشی را به گروه اختصاص دهید. تخصیص نقش های گروهی دارای محدودیت های اضافی است - برای اطلاعات خاص به مرکز راهنمایی مدیر مراجعه کنید.

نقشه‌برداری نقش به امتیاز کنسول Google Admin

برای اختصاص نقش به کاربرانی که از طریق کنسول Admin به امتیازات خود دسترسی دارند، ممکن است نیاز به اعطای برخی امتیازات اضافی باشد. به عنوان مثال، برای اعطای توانایی به کاربر برای ایجاد کاربران دیگر از طریق کنسول مدیریت، نه تنها به امتیاز USERS_CREATE نیاز است، بلکه به امتیازات USERS_UPDATE و 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 تنظیم شده باشد، 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 زیر استفاده کنید و مجوز شرح داده شده در درخواست‌های مجوز را اضافه کنید. برای هر امتیازی که باید با این نقش اعطا شود، یک 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 زیر استفاده کنید و مجوز شرح داده شده در درخواست‌های مجوز را اضافه کنید.

• برای اختصاص دادن نقش به یک کاربر، یک بدنه JSON با user_id کاربر اضافه کنید، که می‌توانید آن را از users.get() ، roleId (همانطور که در Get exist roles توضیح داده شد) و scope_type دریافت کنید.

• برای تخصیص نقش به یک حساب سرویس، یک بدنه JSON با شناسه unique_id حساب سرویس (همانطور که در مدیریت هویت و دسترسی (IAM) تعریف شده است)، roleId (همانطور که در دریافت نقش‌های موجود توضیح داده شده است) و scope_type اضافه کنید.

• برای اختصاص دادن نقش به یک گروه، یک بدنه JSON با group_id گروه اضافه کنید، که می توانید آن را از groups.get() ، roleId (همانطور که در Get exist roles توضیح داده شده است) و 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 همانطور که در Get exist roles توضیح داده شده است، و condition اضافه کنید. دو رشته شرط باید به طور کلمه به کلمه همانطور که در زیر نشان داده شده است استفاده شوند و آنها فقط با نقش های سرپرست از پیش ساخته شده Groups Editor و Groups Reader کار می کنند. این شرایط از نحو شرط 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'"
}