Browse Source

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
changes/07/524307/13
Lance Bragstad 4 years ago
parent
commit
eefc69e119
  1. 2
      api-ref/source/v3/index.rst
  2. 13
      api-ref/source/v3/parameters.yaml
  3. 35
      api-ref/source/v3/roles.inc
  4. 18
      api-ref/source/v3/samples/admin/list-system-roles-for-group-response.json
  5. 17
      api-ref/source/v3/samples/admin/list-system-roles-for-user-response.json
  6. 417
      api-ref/source/v3/system-roles.inc

2
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

13
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.

35
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
this form of API, however a more generalized API for list assignments is
provided where query parameters are used to filter the set of assignments
returned in the collection. For example:
You can also list roles assigned to the system, or to a specified domain,
project, or user using this form of API, however a more generalized API for
list assignments is provided where query parameters are used to filter the set
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
role assignment, will also be treated as having that role assignment by virtue
of their group membership. The *effective* role assignments of a user (on a
given project or domain) therefore consists of any direct assignments they have,
plus any they gain by virtue of membership of groups that also have assignments
on the given project or domain. This set of effective role assignments is what
is placed in the token for reference by services wishing to check policy. You
can list the effective role assignments using the ``effective`` query parameter
at the user, project, and domain level:
particular project, domain, or the entire system. A user who is a member of a
group that has a role assignment, will also be treated as having that role
assignment by virtue of their group membership. The *effective* role
assignments of a user (on a given project or domain) therefore consists of any
direct assignments they have, plus any they gain by virtue of membership of
groups that also have assignments on the given project or domain. This set of
effective role assignments is what is placed in the token for reference by
services wishing to check policy. You can list the effective role assignments
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

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

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

417
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
Loading…
Cancel
Save