9a5395f1b2
Docs at [1] have already been converted from WADL (SGML / XML) to RST using fairy-slipper [2]. This commit polish the results from the conversion and migrate the docs to our repository under 'api-ref/source' directory. In addition, it added missing descriptions for access_token_id and consumer_id to 'parameters.yaml'. Polishing the generated RST files include: - Removing unnecessary blank lines; - Removing empty references. Polishing the generated RST files do not include: - Modifying their content; - Modifying file names; - Wrapping lines at the maximum of 79 chars. Updating the documentation will be done after this migration step. This change also adds a tox environment to build the docs using sphinx under 'api-ref/build', which in turn is added to '.gitignore'. Lastly, 'os-api-ref' is added as a test requirement. It provides the sphinx stanzas rest_method and rest_parameter, used to define OpenStack APIs in RST docs. [1] https://github.com/openstack/api-site/tree/master/api-ref/source/identity/v3 [2] https://github.com/russell/fairy-slipper Change-Id: If1b9a3e1b2e4ea7211c337071254c26b881893a3
588 lines
11 KiB
ReStructuredText
588 lines
11 KiB
ReStructuredText
.. -*- rst -*-
|
|
|
|
=============
|
|
Roles (roles)
|
|
=============
|
|
|
|
Roles grant a user a set of permitted actions for either a specific
|
|
project or an entire domain.
|
|
|
|
You can grant roles to a user on a project, including projects
|
|
owned by other domains.
|
|
|
|
You can create, list, and delete roles. You can also list roles
|
|
assigned to a specified domain, project, or user.
|
|
|
|
You can list role assignments and, since v3.6, all role assignments
|
|
within a tree of projects. Use the query parameters to filter the
|
|
list because the role assignments list can be long. Some typical
|
|
examples are:
|
|
|
|
- List role assignments for the specified user:
|
|
|
|
:: GET /role_assignments?user.id={user_id}
|
|
|
|
- List role assignments for the specified project:
|
|
|
|
:: GET /role_assignments?scope.project.id={project_id}
|
|
|
|
- List all role assignments for a specified project and its sub-
|
|
projects:
|
|
|
|
:: GET /role_assignments?scope.project.id={project_id}?includ
|
|
e_subtree=true
|
|
|
|
If you specify ``include_subtree=true``, you must also specify
|
|
the ``scope.project.id``. Otherwise, this call returns the ``Bad
|
|
Request (400)`` response code.
|
|
|
|
Each role assignment entity in the collection contains a link to
|
|
the assignment that created the entity.
|
|
|
|
Use the ``effective`` query parameter to list effective assignments
|
|
at the user, project, and domain level. This parameter allows for
|
|
the effects of group membership. The group role assignment entities
|
|
themselves are not returned in the collection. This represents the
|
|
effective role assignments that would be included in a scoped
|
|
token.
|
|
|
|
In the response, the ``links`` entity section for entities for
|
|
group members also contains a URL that enables access to the
|
|
membership of the group.
|
|
|
|
You can use the other query parameters with the ``effective``
|
|
parameter, such as:
|
|
|
|
- Determine what a user can actually do:
|
|
|
|
:: GET /role_assignments?user.id={user_id} & effective
|
|
|
|
- Get the equivalent set of role assignments that are included in a
|
|
project-scoped token response:
|
|
|
|
:: GET /role_assignments?user.id={user_id} &
|
|
scope.project.id={project_id} & effective
|
|
|
|
|
|
Grant role to group on project
|
|
==============================
|
|
|
|
.. rest_method:: PUT /v3/projects/{project_id}/groups/{group_id}/roles/{role_id}
|
|
|
|
Grants a role to a group on a project.
|
|
|
|
Error response codes:204,413,415,405,404,403,401,400,503,409,
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- role_id: role_id
|
|
- project_id: project_id
|
|
- group_id: group_id
|
|
|
|
|
|
Check whether group has role on project
|
|
=======================================
|
|
|
|
.. rest_method:: HEAD /v3/projects/{project_id}/groups/{group_id}/roles/{role_id}
|
|
|
|
Validates that a group has a role on a project.
|
|
|
|
Error response codes:204,413,405,404,403,401,400,503,
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- role_id: role_id
|
|
- project_id: project_id
|
|
- group_id: group_id
|
|
|
|
|
|
Revoke role from group on project
|
|
=================================
|
|
|
|
.. rest_method:: DELETE /v3/projects/{project_id}/groups/{group_id}/roles/{role_id}
|
|
|
|
Revokes a role from a group on a project.
|
|
|
|
Error response codes:204,413,415,405,404,403,401,400,503,409,
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- role_id: role_id
|
|
- project_id: project_id
|
|
- group_id: group_id
|
|
|
|
|
|
Grant role to user on project
|
|
=============================
|
|
|
|
.. rest_method:: PUT /v3/projects/{project_id}/users/{user_id}/roles/{role_id}
|
|
|
|
Grants a role to a user on a project.
|
|
|
|
Error response codes:204,413,415,405,404,403,401,400,503,409,
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- role_id: role_id
|
|
- project_id: project_id
|
|
- user_id: user_id
|
|
|
|
|
|
Check whether user has role on project
|
|
======================================
|
|
|
|
.. rest_method:: HEAD /v3/projects/{project_id}/users/{user_id}/roles/{role_id}
|
|
|
|
Validates that a user has a role on a project.
|
|
|
|
Error response codes:204,413,405,404,403,401,400,503,
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- role_id: role_id
|
|
- project_id: project_id
|
|
- user_id: user_id
|
|
|
|
|
|
Revoke role from user on project
|
|
================================
|
|
|
|
.. rest_method:: DELETE /v3/projects/{project_id}/users/{user_id}/roles/{role_id}
|
|
|
|
Revokes a role from a user on a project.
|
|
|
|
Error response codes:204,413,415,405,404,403,401,400,503,409,
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- role_id: role_id
|
|
- project_id: project_id
|
|
- user_id: user_id
|
|
|
|
|
|
List roles for user on project
|
|
==============================
|
|
|
|
.. rest_method:: GET /v3/projects/{project_id}/users/{user_id}/roles
|
|
|
|
Lists roles for a user on a project.
|
|
|
|
Normal response codes: 200
|
|
Error response codes:413,405,404,403,401,400,503,
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- project_id: project_id
|
|
- user_id: user_id
|
|
|
|
Response Example
|
|
----------------
|
|
|
|
.. literalinclude:: ./samples/admin/project-user-roles-list-response.json
|
|
:language: javascript
|
|
|
|
|
|
List roles for group on project
|
|
===============================
|
|
|
|
.. rest_method:: GET /v3/projects/{project_id}/groups/{group_id}/roles
|
|
|
|
Lists roles for a group on a project.
|
|
|
|
Normal response codes: 200
|
|
Error response codes:413,405,404,403,401,400,503,
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- project_id: project_id
|
|
- group_id: group_id
|
|
|
|
Response Example
|
|
----------------
|
|
|
|
.. literalinclude:: ./samples/admin/project-group-roles-list-response.json
|
|
:language: javascript
|
|
|
|
|
|
Grant role to group on domain
|
|
=============================
|
|
|
|
.. rest_method:: PUT /v3/domains/{domain_id}/groups/{group_id}/roles/{role_id}
|
|
|
|
Grants a role to a group on a domain.
|
|
|
|
Error response codes:204,413,415,405,404,403,401,400,503,409,
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- domain_id: domain_id
|
|
- role_id: role_id
|
|
- group_id: group_id
|
|
|
|
|
|
Check whether group has role on domain
|
|
======================================
|
|
|
|
.. rest_method:: HEAD /v3/domains/{domain_id}/groups/{group_id}/roles/{role_id}
|
|
|
|
Validates that a group has a role on a domain.
|
|
|
|
Error response codes:204,413,405,404,403,401,400,503,
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- domain_id: domain_id
|
|
- role_id: role_id
|
|
- group_id: group_id
|
|
|
|
|
|
Revoke role from group on domain
|
|
================================
|
|
|
|
.. rest_method:: DELETE /v3/domains/{domain_id}/groups/{group_id}/roles/{role_id}
|
|
|
|
Revokes a role from a group on a domain.
|
|
|
|
Error response codes:204,413,415,405,404,403,401,400,503,409,
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- domain_id: domain_id
|
|
- role_id: role_id
|
|
- group_id: group_id
|
|
|
|
|
|
List roles for user on domain
|
|
=============================
|
|
|
|
.. rest_method:: GET /v3/domains/{domain_id}/users/{user_id}/roles
|
|
|
|
Lists roles for a user on a domain.
|
|
|
|
Normal response codes: 200
|
|
Error response codes:413,405,404,403,401,400,503,
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- domain_id: domain_id
|
|
- user_id: user_id
|
|
|
|
Response Parameters
|
|
-------------------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- roles: roles
|
|
- id: id
|
|
- links: links
|
|
- name: name
|
|
|
|
Response Example
|
|
----------------
|
|
|
|
.. literalinclude:: ./samples/admin/domain-user-roles-list-response.json
|
|
:language: javascript
|
|
|
|
|
|
List roles
|
|
==========
|
|
|
|
.. rest_method:: GET /v3/roles
|
|
|
|
Lists roles.
|
|
|
|
Normal response codes: 200
|
|
Error response codes:413,405,404,403,401,400,503,
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- name: name
|
|
|
|
Response Parameters
|
|
-------------------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- roles: roles
|
|
- id: id
|
|
- links: links
|
|
- name: name
|
|
|
|
Response Example
|
|
----------------
|
|
|
|
.. literalinclude:: ./samples/admin/roles-list-response.json
|
|
:language: javascript
|
|
|
|
|
|
Create role
|
|
===========
|
|
|
|
.. rest_method:: POST /v3/roles
|
|
|
|
Creates a role.
|
|
|
|
Error response codes:201,413,415,405,404,403,401,400,503,409,
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- role: role
|
|
- name: name
|
|
|
|
Request Example
|
|
---------------
|
|
|
|
.. literalinclude:: ./samples/admin/role-create-request.json
|
|
:language: javascript
|
|
|
|
Response Parameters
|
|
-------------------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- role: role
|
|
- id: id
|
|
- links: links
|
|
- name: name
|
|
|
|
|
|
Grant role to user on domain
|
|
============================
|
|
|
|
.. rest_method:: PUT /v3/domains/{domain_id}/users/{user_id}/roles/{role_id}
|
|
|
|
Grants a role to a user on a domain.
|
|
|
|
Error response codes:204,413,415,405,404,403,401,400,503,409,
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- domain_id: domain_id
|
|
- role_id: role_id
|
|
- user_id: user_id
|
|
|
|
|
|
Check whether user has role on domain
|
|
=====================================
|
|
|
|
.. rest_method:: HEAD /v3/domains/{domain_id}/users/{user_id}/roles/{role_id}
|
|
|
|
Validates that a user has a role on a domain.
|
|
|
|
Error response codes:204,413,405,404,403,401,400,503,
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- domain_id: domain_id
|
|
- role_id: role_id
|
|
- user_id: user_id
|
|
|
|
|
|
Revoke role from user on domain
|
|
===============================
|
|
|
|
.. rest_method:: DELETE /v3/domains/{domain_id}/users/{user_id}/roles/{role_id}
|
|
|
|
Revokes a role from a user on a domain.
|
|
|
|
Error response codes:204,413,415,405,404,403,401,400,503,409,
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- domain_id: domain_id
|
|
- role_id: role_id
|
|
- user_id: user_id
|
|
|
|
|
|
List role assignments
|
|
=====================
|
|
|
|
.. rest_method:: GET /v3/role_assignments
|
|
|
|
Lists role assignments.
|
|
|
|
Normal response codes: 200
|
|
Error response codes:413,405,404,403,401,400,503,
|
|
|
|
Response Parameters
|
|
-------------------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- role_assignments: role_assignments
|
|
|
|
Response Example
|
|
----------------
|
|
|
|
.. literalinclude:: ./samples/admin/role-assignments-list-response.json
|
|
:language: javascript
|
|
|
|
|
|
Show role details
|
|
=================
|
|
|
|
.. rest_method:: GET /v3/roles/{role_id}
|
|
|
|
Shows details for a role.
|
|
|
|
Normal response codes: 200
|
|
Error response codes:413,405,404,403,401,400,503,
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- role_id: role_id
|
|
|
|
Response Parameters
|
|
-------------------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- role: role
|
|
- id: id
|
|
- links: links
|
|
- name: name
|
|
|
|
Response Example
|
|
----------------
|
|
|
|
.. literalinclude:: ./samples/admin/role-show-response.json
|
|
:language: javascript
|
|
|
|
|
|
Update role
|
|
===========
|
|
|
|
.. rest_method:: PATCH /v3/roles/{role_id}
|
|
|
|
Updates a role.
|
|
|
|
Normal response codes: 200
|
|
Error response codes:413,415,405,404,403,401,400,503,409,
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- role: role
|
|
- name: name
|
|
- role_id: role_id
|
|
|
|
Request Example
|
|
---------------
|
|
|
|
.. literalinclude:: ./samples/admin/role-update-request.json
|
|
:language: javascript
|
|
|
|
Response Parameters
|
|
-------------------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- role: role
|
|
- id: id
|
|
- links: links
|
|
- name: name
|
|
|
|
Response Example
|
|
----------------
|
|
|
|
.. literalinclude:: ./samples/admin/role-update-response.json
|
|
:language: javascript
|
|
|
|
|
|
Delete role
|
|
===========
|
|
|
|
.. rest_method:: DELETE /v3/roles/{role_id}
|
|
|
|
Deletes a role.
|
|
|
|
Error response codes:204,413,415,405,404,403,401,400,503,409,
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- role_id: role_id
|
|
|
|
|
|
List roles for group on domain
|
|
==============================
|
|
|
|
.. rest_method:: GET /v3/domains/{domain_id}/groups/{group_id}/roles
|
|
|
|
Lists roles for a group on a domain.
|
|
|
|
Normal response codes: 200
|
|
Error response codes:413,405,404,403,401,400,503,
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- domain_id: domain_id
|
|
- group_id: group_id
|
|
|
|
Response Example
|
|
----------------
|
|
|
|
.. literalinclude:: ./samples/admin/domain-group-roles-list-response.json
|
|
:language: javascript
|