Trang này được dịch bởi Cloud Translation API.

Quản lý vai trò

API Thư mục cho phép bạn sử dụng kiểm soát quyền truy cập dựa trên vai trò (RBAC) để quản lý quyền truy cập vào các tính năng trong miền Google Workspace của bạn. Bạn có thể tạo các vai trò tuỳ chỉnh có đặc quyền để giới hạn quyền quản trị cụ thể hơn các vai trò tạo sẵn có trong Google Workspace. Bạn có thể chỉ định vai trò với người dùng hoặc nhóm bảo mật. Hướng dẫn này giải thích cách thực hiện một số thao tác các công việc cơ bản liên quan đến vai trò.

Sau đây là danh sách các thuật ngữ phổ biến mà API Thư mục sử dụng với về RBAC trong Google Workspace:

Đặc quyền: Quyền cần thiết để thực hiện một tác vụ hoặc thao tác trong một Google Workspace. Đại diện bởi Tài nguyên Privilege. Có không có dữ liệu cố định nào liên kết với tài nguyên này.
Vai trò: Một tập hợp đặc quyền cấp cho các thực thể có vai trò đó thực hiện một số tác vụ hoặc thao tác nhất định. Đại diện bởi Tài nguyên Role.
Chỉ định vai trò: Bản ghi của một vai trò cụ thể được cấp cho người dùng hoặc nhóm. Người đại diện RoleAssignment tài nguyên.
Nhóm bảo mật: Một loại Nhóm Cloud Identity được dùng để kiểm soát quyền truy cập vào của chúng tôi. Nhóm bảo mật có thể chứa cả người dùng cá nhân và nhóm.

Giới hạn về việc chỉ định vai trò và vai trò

Bạn chỉ có thể tạo một số vai trò tuỳ chỉnh hoặc lượt chỉ định vai trò nhất định, vì vậy, nếu bạn sắp đạt đến giới hạn, hãy hợp nhất hoặc loại bỏ chúng để không vượt quá hạn mức tối đa. Vai trò và việc chỉ định vai trò có các giới hạn sau:

Bạn có thể tạo tối đa 750 vai trò tuỳ chỉnh cho toàn bộ tổ chức của mình.
Bạn có thể tạo tối đa 1.000 lượt chỉ định vai trò cho mỗi đơn vị tổ chức (OU), trong đó tổ chức gốc được coi là một đơn vị. Ví dụ: bạn có thể chỉ định 600 vai trò trong tổ chức gốc và 700 vai trò trong một đơn vị tổ chức khác mà bạn đã xác định, chẳng hạn như một phòng ban của công ty. Tất cả vai trò quản trị viên tạo sẵn trên Google Workspace đều được đặt mặc định là trong phạm vi tổ chức. Tìm hiểu thêm về giới hạn về đặc quyền có thể chỉ định ở cấp đơn vị tổ chức.

Sau đây là các giới hạn đối với vai trò và việc chỉ định vai trò cho nhóm:

Bạn có thể chỉ định vai trò bất kỳ, ngoại trừ Quản trị viên cấp cao.
Bạn có thể chỉ định tổng cộng tối đa 250 vai trò cho các nhóm trong đơn vị tổ chức chung và trong từng đơn vị tổ chức.
Nhóm này phải là một nhóm bảo mật trong tổ chức của bạn.
Bạn chỉ nên chỉ cho phép những người dùng trong tổ chức của mình là thành viên trong nhóm. Bạn có thể thêm người dùng từ bên ngoài tổ chức của bạn, nhưng họ có thể không nhận được đặc quyền của vai trò. Để biết thông tin chi tiết, hãy xem Hạn chế tư cách thành viên trong nhóm. ### Chỉ định vai trò cho các nhóm

Nếu cần chỉ định hơn 1.000 vai trò trong một đơn vị tổ chức, bạn có thể thêm nhiều vai trò thành viên cho một nhóm bảo mật và chỉ định vai trò cho nhóm đó. Vai trò trong nhóm Bài tập có thêm một số hạn chế, vui lòng xem Trung tâm trợ giúp dành cho quản trị viên để biết thông tin cụ thể.

Liên kết vai trò đến đặc quyền trong Bảng điều khiển dành cho quản trị viên của Google

Để chỉ định vai trò cho người dùng có quyền truy cập đặc quyền của họ thông qua Bảng điều khiển dành cho quản trị viên, một số đặc quyền bổ sung có thể cần đã được cấp. Ví dụ: để cấp cho người dùng khả năng tạo người dùng khác thông qua Bảng điều khiển dành cho quản trị viên không chỉ là đặc quyền USERS_CREATE bắt buộc, đồng thời cũng có USERS_UPDATE và ORGANIZATION_UNITS_RETRIEVE đặc quyền. Bảng sau đây liên kết Bảng điều khiển dành cho quản trị viên chức năng cho các cấp đặc quyền bắt buộc để quản lý người dùng và đơn vị tổ chức.

Chức năng của Bảng điều khiển dành cho quản trị viên	Đặc quyền cần thiết
Đơn vị tổ chức – Đọc	`ORGANIZATION_UNITS_RETRIEVE`
Đơn vị tổ chức – Tạo	`ORGANIZATION_UNITS_RETRIEVE` + `ORGANIZATION_UNITS_CREATE`
Đơn vị tổ chức – Cập nhật	`ORGANIZATION_UNITS_RETRIEVE` + `ORGANIZATION_UNITS_UPDATE`
Đơn vị tổ chức – Xoá	`ORGANIZATION_UNITS_RETRIEVE` + `ORGANIZATION_UNITS_DELETE`
Đơn vị tổ chức	`ORGANIZATION_UNITS_ALL`
Người dùng – Đọc	`USERS_RETRIEVE` + `ORGANIZATION_UNITS_RETRIEVE`
Người dùng – Tạo	`USERS_CREATE` + `USERS_UPDATE` + `ORGANIZATION_UNITS_RETRIEVE`
Người dùng - Cập nhật	`USERS_UPDATE` + `ORGANIZATION_UNITS_RETRIEVE`
Người dùng – Chuyển người dùng	`USERS_MOVE` + `USERS_RETRIEVE` + `ORGANIZATION_UNITS_RETRIEVE`
Người dùng - Đổi tên người dùng	`USERS_ALIAS` + `USERS_RETRIEVE` + `ORGANIZATION_UNITS_RETRIEVE`
Người dùng - Đặt lại mật khẩu	`USERS_RESET_PASSWORD` + `USERS_RETRIEVE` + `ORGANIZATION_UNITS_RETRIEVE`
Người dùng - Bắt buộc thay đổi mật khẩu	`USERS_FORCE_PASSWORD_CHANGE` + `USERS_RETRIEVE` + `ORGANIZATION_UNITS_RETRIEVE`
Người dùng - Thêm/xóa bí danh	`USERS_ADD_NICKNAME` + `USERS_RETRIEVE` + `ORGANIZATION_UNITS_RETRIEVE`
Người dùng - Tạm ngừng người dùng	`USERS_SUSPEND` + `USERS_RETRIEVE` + `ORGANIZATION_UNITS_RETRIEVE`
NHÓM	`GROUPS_ALL`
Bảo mật – Quản lý bảo mật người dùng	`USER_SECURITY_ALL` + `USERS_RETRIEVE` + `ORGANIZATION_UNITS_RETRIEVE`

Ví dụ về trường hợp sử dụng

Trước khi bắt đầu

Hoàn thành xác thực và uỷ quyền cho Google Workspace.

Lấy danh sách các đặc quyền của miền

Để nhận danh sách phân trang gồm các đặc quyền được hỗ trợ trong miền của bạn, hãy sử dụng privileges.list() .

Nếu bạn là quản trị viên nhận đặc quyền trong miền của riêng mình, hãy sử dụng my_customer làm mã khách hàng.
Nếu bạn là đại lý nhận đặc quyền cho một trong các khách hàng của mình, sử dụng ID khách hàng được trả về bởi lệnh Truy xuất người dùng.

Yêu cầu

GET https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roles/ALL/privileges

Phản hồi

Phản hồi thành công sẽ trả về trạng thái HTTP 200 . Cùng với mã trạng thái thì phản hồi sẽ trả về các đặc quyền được hỗ trợ trong miền:

{
  "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
        }
      ]
    },
    ...
  ]
}

Nhận vai trò hiện có

Để xem danh sách vai trò hiện tại, hãy sử dụng yêu cầu GET sau đây và thêm uỷ quyền được mô tả trong Uỷ quyền yêu cầu.

Nếu bạn là quản trị viên và nhận vai trò trong miền của riêng bạn, hãy sử dụng my_customer làm mã khách hàng.
Nếu bạn là đại lý nhận các vai trò cho một khách hàng, hãy sử dụng mã khách hàng mà bạn đã sử dụng công cụ Truy xuất người dùng.

Yêu cầu

GET https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roles

Phản hồi

Khi phản hồi thành công, hệ thống sẽ trả về trạng thái HTTP 200 . Cùng với mã trạng thái, phản hồi sẽ trả về vai trò hiện có trong miền:

{
  "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
    },
    ...
  ]
}

Liệt kê tất cả các lượt chỉ định vai trò

Để nhận danh sách phân trang của tất cả việc chỉ định vai trò trực tiếp, hãy sử dụng roleAssignments.list() . API có thể trả về kết quả trống kèm theo mã thông báo trang khi userKey tham số được đặt. Bạn nên tiếp tục phân trang cho đến khi không còn mã thông báo trang nào bị trả lại.

Nếu bạn là quản trị viên và được chỉ định vai trò trong miền của riêng bạn, hãy sử dụng my_customer làm mã khách hàng.
Nếu bạn là đại lý và đang nhận chỉ định vai trò cho một trong các khách hàng của mình, sử dụng ID khách hàng được trả về bởi lệnh Truy xuất người dùng.

Yêu cầu

GET https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roleassignments

Phản hồi

Khi phản hồi thành công, hệ thống sẽ trả về trạng thái HTTP 200 . Cùng với mã trạng thái, phản hồi sẽ trả về tất cả vai trò đã chỉ định trong miền:

{
  "kind": "admin\#directory\#roleAssignment",
  "etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/VdrrUEz7GyXqlr9I9JL0wGZn8yE\"",
  "roleAssignmentId:"3894208461013211",
  "assignedTo:"100662996240850794412",
  "assigneeType:"user",
  "scopeType:"CUSTOMER",
}

Liệt kê tất cả các lượt chỉ định vai trò gián tiếp

Để tải danh sách được phân trang của tất cả việc chỉ định vai trò, bao gồm cả những vai trò gián tiếp gán cho người dùng vì các nhóm mà họ thuộc về, hãy sử dụng roleAssignments.list() .

API có thể trả về kết quả trống kèm theo mã thông báo trang. Bạn nên tiếp tục phân trang cho đến khi không có mã thông báo trang nào được trả về.

Nếu bạn là quản trị viên và được chỉ định vai trò trong miền của riêng bạn, hãy sử dụng my_customer làm mã khách hàng.
Nếu bạn là đại lý và đang nhận chỉ định vai trò cho một trong các khách hàng của mình, sử dụng ID khách hàng được trả về bởi lệnh Truy xuất người dùng.
Thay thế USER_KEY bằng một giá trị giúp xác định người dùng trong yêu cầu API. Để biết thêm thông tin, hãy xem users.get.

Yêu cầu

GET https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roleassignments?userKey=USER_KEY&includeIndirectRoleAssignments=true

Phản hồi

Khi phản hồi thành công, hệ thống sẽ trả về trạng thái HTTP 200 . Cùng với mã trạng thái thì phản hồi sẽ trả về tất cả vai trò được chỉ định trong miền và liệu assigneeType là user hoặc group:

{
  "kind": "admin\#directory\#roleAssignment",
  "etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/VdrrUEz7GyXqlr9I9JL0wGZn8yE\"",
  "roleAssignmentId:"3894208461013211",
  "assignedTo:"100662996240850794412",
  "assigneeType:"group",
  "scopeType:"CUSTOMER",
}

Tạo vai trò

Để tạo vai trò mới, hãy sử dụng yêu cầu POST sau đây và thêm uỷ quyền được mô tả trong Uỷ quyền yêu cầu. Thêm privilegeName và serviceId cho mỗi đặc quyền được cấp vai trò này. Để biết các thuộc tính yêu cầu và phản hồi, hãy xem API Tệp đối chiếu.

Yêu cầu

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"
    }
  ]
}

Phản hồi

Khi phản hồi thành công, hệ thống sẽ trả về trạng thái HTTP 200 . Cùng với mã trạng thái thì phản hồi sẽ trả về các thuộc tính cho vai trò mới:

{
  "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"
    }
  ]
}

Tạo việc chỉ định vai trò

Để chỉ định một vai trò, hãy sử dụng phương thức POST sau đây và bao gồm yêu cầu uỷ quyền được mô tả trong Uỷ quyền cho các yêu cầu.

Để chỉ định vai trò cho một người dùng, hãy thêm nội dung JSON cùng với user_id của người dùng, mà bạn có thể nhận từ users.get(), roleId (như được mô tả trong Nhận các vai trò hiện tại) và scope_type.
Để chỉ định vai trò cho một tài khoản dịch vụ, hãy thêm nội dung JSON có phần tử unique_id của tài khoản dịch vụ (như được xác định trong Quản lý danh tính và quyền truy cập (IAM)), roleId (như được mô tả trong Nhận các vai trò hiện có) và scope_type.
Để chỉ định vai trò cho một nhóm, hãy thêm nội dung JSON cùng với group_id của mà bạn có thể lấy từ groups.get(), roleId (như được mô tả trong Nhận các vai trò hiện tại), và scope_type.

Yêu cầu

POST https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roleassignments

{
  "roleId": "3894208461012995",
  "assignedTo": "100662996240850794412",
  "scopeType": "CUSTOMER"
}

Phản hồi

Khi phản hồi thành công, hệ thống sẽ trả về trạng thái HTTP 200 . Cùng với mã trạng thái thì phản hồi sẽ trả về các thuộc tính cho việc chỉ định vai trò mới:

{
  "kind": "admin\#directory\#roleAssignment",
  "etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/VdrrUEz7GyXqlr9I9JL0wGZn8yE\"",
  "roleAssignmentId": "3894208461013211",
  "roleId": "3894208461012995",
  "assignedTo": "100662996240850794412",
  "scopeType": "CUSTOMER"
}

Tạo việc chỉ định vai trò kèm theo các điều kiện

Bạn có thể cấp vai trò để thực hiện những hành động đáp ứng các điều kiện cụ thể. Hiện tại, chỉ có hai điều kiện được hỗ trợ:

Chỉ áp dụng cho nhóm bảo mật
Không áp dụng cho nhóm bảo mật

Khi bạn đặt condition, lựa chọn này sẽ chỉ có hiệu lực khi tài nguyên đang được đã truy cập đáp ứng điều kiện. Nếu condition trống, vai trò (roleId) sẽ là được áp dụng cho tác nhân (assignedTo) ở phạm vi (scopeType) một cách vô điều kiện.

Để chỉ định vai trò cho người dùng, hãy sử dụng phương thức POST sau và thêm phương thức uỷ quyền được mô tả trong Uỷ quyền .

Thêm nội dung JSON có user_id của người dùng mà bạn có thể lấy từ đó users.get(), roleId dưới dạng được mô tả trong phần Nhận vai trò hiện tại và condition. Chiến lược phát hành đĩa đơn hai chuỗi điều kiện phải được sử dụng nguyên văn như được trình bày dưới đây và chúng chỉ hoạt động với Trình chỉnh sửa nhóm và Trình đọc Groups vai trò quản trị viên tạo sẵn. Các điều kiện này tuân theo Cú pháp điều kiện Cloud IAM.

Yêu cầu

Chỉ áp dụng cho nhóm bảo mật

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'"
}

Không áp dụng cho nhóm bảo mật

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'"
}

Phản hồi

{
  "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'"
}