Add system role assignment documentation

Hot off the press! This commit contains all the API reference
documentation for using system role assignments. It is also
consistent with the api-reference conventions we established
during the Queens PTG in Denver.

bp system-scope

Change-Id: Ic49555423d7ca7415d7c8546c5dfa7368ad8fe7e

api-ref/source/v3/index.rst

@@ -187,6 +187,7 @@ This page lists the Identity API operations in the following order:
 * `Project Tags`_
 * `Regions`_
 * `Roles`_
+* `System Role Assignments`_
 * `Service catalog and endpoints`_
 * `Users`_
 * `OS-INHERIT`_
@@ -206,5 +207,6 @@ This page lists the Identity API operations in the following order:
 .. include:: project-tags.inc
 .. include:: regions-v3.inc
 .. include:: roles.inc
+.. include:: system-roles.inc
 .. include:: service-catalog.inc
 .. include:: users.inc

api-ref/source/v3/parameters.yaml

@@ -345,6 +345,12 @@ scope_project_id_query:
   in: query
   required: false
   type: string
+scope_system_query:
+  description: |
+    Filters the response by system assignments.
+  in: query
+  required: false
+  type: string
 service_id_query:
   description: |
     Filters the response by a service ID.
@@ -1450,6 +1456,13 @@ signed:
   in: body
   required: true
   type: string
+system_roles_response_body:
+  description: |
+    A list of ``role`` objects containing ``domain_id``, ``id``, ``links``,
+    and ``name`` attributes.
+  in: body
+  required: true
+  type: array
 token:
   description: |
     A ``token`` object.

api-ref/source/v3/roles.inc

@@ -24,10 +24,10 @@ user on a project::
 
   PUT /v3/projects/{project_id}/users/{user_id}/roles/{role_id}
 
-You can also list roles assigned to a specified domain, project, or user using
+You can also list roles assigned to the system, or to a specified domain,
-this form of API, however a more generalized API for list assignments is
+project, or user using this form of API, however a more generalized API for
-provided where query parameters are used to filter the set of assignments
+list assignments is provided where query parameters are used to filter the set
-returned in the collection. For example:
+of assignments returned in the collection. For example:
 
 - List role assignments for the specified user::
 
@@ -37,6 +37,14 @@ returned in the collection. For example:
 
     GET /role_assignments?scope.project.id={project_id}
 
+- List system role assignments for a specific user::
+
+    GET /role_assignments?scope.system=all?user.id={user_id}
+
+Since Identity API v3.10, you can grant role assignments to users and groups on
+an entity called the ``system``. The role assignment API also supports listing
+and filtering role assignments on the system.
+
 Since Identity API v3.6, you can also list all role assignments within a tree of projects,
 for example the following would list all role assignments for a specified
 project and its sub-projects::
@@ -51,15 +59,15 @@ Each role assignment entity in the collection contains a link to
 the assignment that created the entity.
 
 As mentioned earlier, role assignments can be made to a user or a group on a
-particular project or domain. A user who is a member of a group that has a
+particular project, domain, or the entire system. A user who is a member of a
-role assignment, will also be treated as having that role assignment by virtue
+group that has a role assignment, will also be treated as having that role
-of their group membership. The *effective* role assignments of a user (on a
+assignment by virtue of their group membership. The *effective* role
-given project or domain) therefore consists of any direct assignments they have,
+assignments of a user (on a given project or domain) therefore consists of any
-plus any they gain by virtue of membership of groups that also have assignments
+direct assignments they have, plus any they gain by virtue of membership of
-on the given project or domain. This set of effective role assignments is what
+groups that also have assignments on the given project or domain. This set of
-is placed in the token for reference by services wishing to check policy. You
+effective role assignments is what is placed in the token for reference by
-can list the effective role assignments using the ``effective`` query parameter
+services wishing to check policy. You can list the effective role assignments
-at the user, project, and domain level:
+using the ``effective`` query parameter at the user, project, and domain level:
 
 - Determine what a user can actually do::
 
@@ -1295,6 +1303,7 @@ Parameters
    - include_subtree: include_subtree_query
    - group.id: group_id_query
    - role.id: role_id_query
+   - scope.system: scope_system_query
    - scope.domain.id: scope_domain_id_query
    - scope.project.id: scope_project_id_query
    - user.id: user_id_query

api-ref/source/v3/samples/admin/list-system-roles-for-group-response.json

@@ -0,0 +1,18 @@
+{
+    "roles": [
+        {
+            "domain_id": null,
+            "id": "6d550353899f4b0fbf3e410e1b6ddc05",
+            "links": {
+                "self": "http://example.com/identity/v3/roles/6d550353899f4b0fbf3e410e1b6ddc05"
+            },
+            "name": "admin"
+        }
+    ],
+    "links": {
+        "next": null,
+        "previous": null,
+        "self": "http://example.com/identity/v3/system/groups/934cc15c4d03479ebba167d67d47737f/roles"
+    }
+}
+

api-ref/source/v3/samples/admin/list-system-roles-for-user-response.json

@@ -0,0 +1,17 @@
+{
+    "roles": [
+        {
+            "domain_id": null,
+            "id": "6d550353899f4b0fbf3e410e1b6ddc05",
+            "links": {
+                "self": "http://example.com/identity/v3/roles/6d550353899f4b0fbf3e410e1b6ddc05"
+            },
+            "name": "admin"
+        }
+    ],
+    "links": {
+        "next": null,
+        "previous": null,
+        "self": "http://example.com/identity/v3/system/users/0b916f1b1e51455cb24b3a051520c576/roles"
+    }
+}

api-ref/source/v3/system-roles.inc

@@ -0,0 +1,417 @@
+.. -*- rst -*-
+
+=======================
+System Role Assignments
+=======================
+
+A system role assignment ultimately controls access to system-level API calls.
+System role assignments are similar to project or domain role assignments, but
+are meant for a different target. Instead of giving a user or group a role on a
+project, they can be given a system role.
+
+Good examples of system-level APIs include management of the service catalog
+and compute hypervisors.
+
+List system role assignments for a user
+=======================================
+
+.. rest_method::  GET /v3/system/users/{user_id}/roles
+
+Lists all system role assignment a user has.
+
+Relationship: ``https://docs.openstack.org/api/openstack-identity/3/rel/system_user_roles``
+
+Request
+-------
+
+Parameters
+~~~~~~~~~~
+
+.. rest_parameters:: parameters.yaml
+
+   - user_id: user_id_path
+
+Response
+--------
+
+Parameters
+~~~~~~~~~~
+
+.. rest_parameters:: parameters.yaml
+
+   - links: link_response_body
+   - roles: system_roles_response_body
+
+Status Codes
+~~~~~~~~~~~~
+
+.. rest_status_code:: success status.yaml
+
+   - 200
+
+.. rest_status_code:: error status.yaml
+
+   - 400
+   - 401
+   - 403
+
+Example
+~~~~~~~
+
+.. literalinclude:: ./samples/admin/list-system-roles-for-user-response.json
+   :language: javascript
+
+The functionality of this request can also be achieved using the generalized
+list assignments API::
+
+  GET /role_assignments?user.id={user_id}&scope.system
+
+Assign a system role to a user
+==============================
+
+.. rest_method::  PUT /v3/system/users/{user_id}/roles/{role_id}
+
+Grant a user a role on the system.
+
+Relationship: ``https://docs.openstack.org/api/openstack-identity/3/rel/system_user_role``
+
+Request
+-------
+
+Parameters
+~~~~~~~~~~
+
+.. rest_parameters:: parameters.yaml
+
+   - user_id: user_id_path
+   - role_id: role_id_path
+
+Response
+--------
+
+Status Codes
+~~~~~~~~~~~~
+
+.. rest_status_code:: success status.yaml
+
+   - 204
+
+.. rest_status_code:: error status.yaml
+
+   - 401
+   - 403
+   - 404
+
+Check user for a system role assignment
+=======================================
+
+.. rest_method::  HEAD /v3/system/users/{user_id}/roles/{role_id}
+
+Check if a specific user has a role assignment on the system.
+
+Relationship: ``https://docs.openstack.org/api/openstack-identity/3/rel/system_user_role``
+
+Request
+-------
+
+Parameters
+~~~~~~~~~~
+
+.. rest_parameters:: parameters.yaml
+
+   - user_id: user_id_path
+   - role_id: role_id_path
+
+Response
+--------
+
+Status Codes
+~~~~~~~~~~~~
+
+.. rest_status_code:: success status.yaml
+
+   - 204
+
+.. rest_status_code:: error status.yaml
+
+   - 401
+   - 403
+   - 404
+
+Get system role assignment for a user
+=====================================
+
+.. rest_method::  GET /v3/system/users/{user_id}/roles/{role_id}
+
+Get a specific system role assignment for a user. This is the same API as
+``HEAD /v3/system/users/{user_id}/roles/{role_id}``.
+
+Relationship: ``https://docs.openstack.org/api/openstack-identity/3/rel/system_user_role``
+
+Request
+-------
+
+Parameters
+~~~~~~~~~~
+
+.. rest_parameters:: parameters.yaml
+
+   - user_id: user_id_path
+   - role_id: role_id_path
+
+Response
+--------
+
+Status Codes
+~~~~~~~~~~~~
+
+.. rest_status_code:: success status.yaml
+
+   - 204
+
+.. rest_status_code:: error status.yaml
+
+   - 400
+   - 401
+   - 403
+   - 404
+
+Delete a system role assignment from a user
+===========================================
+
+.. rest_method::  DELETE /v3/system/users/{user_id}/roles/{role_id}
+
+Remove a system role assignment from a user.
+
+Relationship: ``https://docs.openstack.org/api/openstack-identity/3/rel/system_user_role``
+
+Request
+-------
+
+Parameters
+~~~~~~~~~~
+
+.. rest_parameters:: parameters.yaml
+
+   - user_id: user_id_path
+   - role_id: role_id_path
+
+Response
+--------
+
+Status Codes
+~~~~~~~~~~~~
+
+.. rest_status_code:: success status.yaml
+
+   - 204
+
+.. rest_status_code:: error status.yaml
+
+   - 400
+   - 401
+   - 403
+   - 404
+
+List system role assignments for a group
+========================================
+
+.. rest_method::  GET /v3/system/groups/{group_id}/roles
+
+Lists all system role assignment a group has.
+
+Relationship: ``https://docs.openstack.org/api/openstack-identity/3/rel/system_group_roles``
+
+Request
+-------
+
+Parameters
+~~~~~~~~~~
+
+.. rest_parameters:: parameters.yaml
+
+   - group_id: group_id_path
+
+Response
+--------
+
+Parameters
+~~~~~~~~~~
+
+.. rest_parameters:: parameters.yaml
+
+   - links: link_response_body
+   - roles: system_roles_response_body
+
+Status Codes
+~~~~~~~~~~~~
+
+.. rest_status_code:: success status.yaml
+
+   - 200
+
+.. rest_status_code:: error status.yaml
+
+   - 400
+   - 401
+   - 403
+
+Example
+~~~~~~~
+
+.. literalinclude:: ./samples/admin/list-system-roles-for-group-response.json
+   :language: javascript
+
+The functionality of this request can also be achieved using the generalized
+list assignments API::
+
+  GET /role_assignments?group.id={group_id}&scope.system
+
+Assign a system role to a group
+===============================
+
+.. rest_method::  PUT /v3/system/groups/{group_id}/roles/{role_id}
+
+Grant a group a role on the system.
+
+Relationship: ``https://docs.openstack.org/api/openstack-identity/3/rel/system_group_role``
+
+Request
+-------
+
+Parameters
+~~~~~~~~~~
+
+.. rest_parameters:: parameters.yaml
+
+   - group_id: group_id_path
+   - role_id: role_id_path
+
+Response
+--------
+
+Status Codes
+~~~~~~~~~~~~
+
+.. rest_status_code:: success status.yaml
+
+   - 204
+
+.. rest_status_code:: error status.yaml
+
+   - 400
+   - 401
+   - 403
+   - 404
+
+Check group for a system role assignment
+========================================
+
+.. rest_method::  HEAD /v3/system/groups/{group_id}/roles/{role_id}
+
+Check if a specific group has a role assignment on the system.
+
+Relationship: ``https://docs.openstack.org/api/openstack-identity/3/rel/system_group_role``
+
+Request
+-------
+
+Parameters
+~~~~~~~~~~
+
+.. rest_parameters:: parameters.yaml
+
+   - group_id: group_id_path
+   - role_id: role_id_path
+
+Response
+--------
+
+Status Codes
+~~~~~~~~~~~~
+
+.. rest_status_code:: success status.yaml
+
+   - 204
+
+.. rest_status_code:: error status.yaml
+
+   - 400
+   - 401
+   - 403
+   - 404
+
+Get system role assignment for a group
+======================================
+
+.. rest_method::  GET /v3/system/groups/{group_id}/roles/{role_id}
+
+Get a specific system role assignment for a group. This is the same API as
+``HEAD /v3/system/groups/{group_id}/roles/{role_id}``.
+
+Relationship: ``https://docs.openstack.org/api/openstack-identity/3/rel/system_group_role``
+
+Request
+-------
+
+Parameters
+~~~~~~~~~~
+
+.. rest_parameters:: parameters.yaml
+
+   - group_id: group_id_path
+   - role_id: role_id_path
+
+Response
+--------
+
+Status Codes
+~~~~~~~~~~~~
+
+.. rest_status_code:: success status.yaml
+
+   - 204
+
+.. rest_status_code:: error status.yaml
+
+   - 400
+   - 401
+   - 403
+   - 404
+
+Delete a system role assignment from a group
+============================================
+
+.. rest_method::  DELETE /v3/system/groups/{group_id}/roles/{role_id}
+
+Remove a system role assignment from a group.
+
+Relationship: ``https://docs.openstack.org/api/openstack-identity/3/rel/system_group_role``
+
+Request
+-------
+
+Parameters
+~~~~~~~~~~
+
+.. rest_parameters:: parameters.yaml
+
+   - group_id: group_id_path
+   - role_id: role_id_path
+
+Response
+--------
+
+Status Codes
+~~~~~~~~~~~~
+
+.. rest_status_code:: success status.yaml
+
+   - 204
+
+.. rest_status_code:: error status.yaml
+
+   - 400
+   - 401
+   - 403
+   - 404