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
parent
086dd2738b
commit
eefc69e119
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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"
|
||||
}
|
||||
}
|
||||
|
||||
|
|
@ -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"
|
||||
}
|
||||
}
|
||||
|
|
@ -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…
Reference in New Issue