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

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

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

امتیاز
مجوز لازم برای انجام یک کار یا عملیات در دامنه Google Workspace. با منبع Privilege نمایش داده می‌شود. هیچ داده پایداری مرتبط با این منبع وجود ندارد.
نقش
مجموعه‌ای از امتیازات که به موجودیت‌های دارای آن نقش، توانایی انجام وظایف یا عملیات خاص را می‌دهد. این ویژگی توسط منبع Role نمایش داده می‌شود.
واگذاری نقش
رکوردی از یک نقش خاص که به کاربر یا گروه داده شده است. توسط منبع RoleAssignment نمایش داده می‌شود.
گروه امنیتی
نوعی گروه هویت ابری که برای کنترل دسترسی به منابع سازمانی استفاده می‌شود. گروه‌های امنیتی می‌توانند شامل کاربران و گروه‌های شخصی باشند.

نقش و محدودیت‌های واگذاری نقش

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

  • شما می‌توانید تا ۷۵۰ نقش سفارشی برای کل سازمان خود ایجاد کنید.
  • شما می‌توانید تا ۱۰۰۰ نقش را به ازای هر واحد سازمانی (OU) ایجاد کنید، که در آن سازمان ریشه یک واحد در نظر گرفته می‌شود. به عنوان مثال، می‌توانید ۶۰۰ نقش را در سازمان ریشه و ۷۰۰ نقش را در یک OU دیگر که تعریف کرده‌اید، مانند یک دپارتمان از یک شرکت، اختصاص دهید. همه نقش‌های مدیر از پیش ساخته شده Google Workspace به طور پیش‌فرض در محدوده کل سازمان قرار دارند. درباره محدودیت‌های امتیازاتی که می‌توان در سطح OU اختصاص داد، بیشتر بدانید.

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

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

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

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

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

از مثال‌های موردی استفاده کنید

قبل از اینکه شروع کنی

قبل از اجرای مثال‌های این راهنما، احراز هویت و مجوز را تنظیم کنید.

  1. صفحه رضایت OAuth را پیکربندی کنید .

  2. ایجاد اعتبارنامه‌های دسترسی .

دریافت لیست امتیازات دامنه

برای دریافت لیست صفحه‌بندی‌شده‌ی مجوزهای پشتیبانی‌شده در دامنه‌ی خود، از متد 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 زیر استفاده کنید و مجوز شرح داده شده در Authorize requests را وارد کنید.

  • اگر شما مدیر سیستم هستید و در دامنه خودتان نقش‌هایی را دریافت می‌کنید، 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() استفاده کنید. API ممکن است هنگام تنظیم پارامتر 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() استفاده کنید.

ممکن است 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 زیر استفاده کنید و مجوز شرح داده شده در Authorize requests را وارد کنید.

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

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

  • برای اختصاص نقش به یک گروه، یک بدنه JSON با group_id گروه اضافه کنید، که می‌توانید آن را از groups.get() ، roleId (مطابق توضیحات در Get existing 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 زیر استفاده کنید و مجوز شرح داده شده در Authorize requests را وارد کنید.

یک بدنه JSON با user_id کاربر اضافه کنید، که می‌توانید آن را از users.get() دریافت کنید، roleId همانطور که در Get existing 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'"
}