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
This commit is contained in:
Lance Bragstad 2017-11-30 18:20:27 +00:00
parent 086dd2738b
commit eefc69e119
6 changed files with 489 additions and 13 deletions

View File

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

View File

@ -345,6 +345,12 @@ scope_project_id_query:
in: query in: query
required: false required: false
type: string type: string
scope_system_query:
description: |
Filters the response by system assignments.
in: query
required: false
type: string
service_id_query: service_id_query:
description: | description: |
Filters the response by a service ID. Filters the response by a service ID.
@ -1450,6 +1456,13 @@ signed:
in: body in: body
required: true required: true
type: string 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: token:
description: | description: |
A ``token`` object. A ``token`` object.

View File

@ -24,10 +24,10 @@ user on a project::
PUT /v3/projects/{project_id}/users/{user_id}/roles/{role_id} 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:: - 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} 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, 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 for example the following would list all role assignments for a specified
project and its sub-projects:: 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. the assignment that created the entity.
As mentioned earlier, role assignments can be made to a user or a group on a 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:: - Determine what a user can actually do::
@ -1295,6 +1303,7 @@ Parameters
- include_subtree: include_subtree_query - include_subtree: include_subtree_query
- group.id: group_id_query - group.id: group_id_query
- role.id: role_id_query - role.id: role_id_query
- scope.system: scope_system_query
- scope.domain.id: scope_domain_id_query - scope.domain.id: scope_domain_id_query
- scope.project.id: scope_project_id_query - scope.project.id: scope_project_id_query
- user.id: user_id_query - user.id: user_id_query

View File

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

View File

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

View File

@ -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