From eefc69e11987a4f1beaff13fdb7fd8a7aef2b1ec Mon Sep 17 00:00:00 2001 From: Lance Bragstad Date: Thu, 30 Nov 2017 18:20:27 +0000 Subject: [PATCH] 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 --- api-ref/source/v3/index.rst | 2 + api-ref/source/v3/parameters.yaml | 13 + api-ref/source/v3/roles.inc | 35 +- .../list-system-roles-for-group-response.json | 18 + .../list-system-roles-for-user-response.json | 17 + api-ref/source/v3/system-roles.inc | 417 ++++++++++++++++++ 6 files changed, 489 insertions(+), 13 deletions(-) create mode 100644 api-ref/source/v3/samples/admin/list-system-roles-for-group-response.json create mode 100644 api-ref/source/v3/samples/admin/list-system-roles-for-user-response.json create mode 100644 api-ref/source/v3/system-roles.inc diff --git a/api-ref/source/v3/index.rst b/api-ref/source/v3/index.rst index 5d7beea364..029c24c820 100644 --- a/api-ref/source/v3/index.rst +++ b/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 diff --git a/api-ref/source/v3/parameters.yaml b/api-ref/source/v3/parameters.yaml index 49b16e0319..47992b88fd 100644 --- a/api-ref/source/v3/parameters.yaml +++ b/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. diff --git a/api-ref/source/v3/roles.inc b/api-ref/source/v3/roles.inc index 714fe5825c..efb6ba7995 100644 --- a/api-ref/source/v3/roles.inc +++ b/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 diff --git a/api-ref/source/v3/samples/admin/list-system-roles-for-group-response.json b/api-ref/source/v3/samples/admin/list-system-roles-for-group-response.json new file mode 100644 index 0000000000..ef9a8eaf2a --- /dev/null +++ b/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" + } +} + diff --git a/api-ref/source/v3/samples/admin/list-system-roles-for-user-response.json b/api-ref/source/v3/samples/admin/list-system-roles-for-user-response.json new file mode 100644 index 0000000000..22d8694ec4 --- /dev/null +++ b/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" + } +} diff --git a/api-ref/source/v3/system-roles.inc b/api-ref/source/v3/system-roles.inc new file mode 100644 index 0000000000..5c55b026b6 --- /dev/null +++ b/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