openstack/keystone
Code Issues Proposed changes
e4c01229e3
keystone/api-ref/source/v3/system-roles.inc
Lance Bragstad eefc69e119 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
2018-01-17 22:51:17 +00:00

418 lines
7.2 KiB
ReStructuredText
Raw Blame History

.. -*- 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
View Git Blame Copy Permalink