openstack/keystone
Code Issues Proposed changes

Update API version for access rules

Browse Source 
This change updates the minor API version for the new access rules
feature for application credentials, and also adds documentation for
the new feature to the API reference as well as a release note.

bp whitelist-extension-for-app-creds

Change-Id: I8a03223df63877a4f86fbe7e9fa382fdd96c5934
This commit is contained in:
Colleen Murphy 2019-07-17 17:08:43 -07:00 committed by Colleen Murphy
parent 049d9bcbe4
commit 131f7ddd4e
13 changed files with 372 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

220
api-ref/source/v3/application-credentials.inc
View File

@ -21,6 +21,87 @@ Application credentials are limited by the lifespan of the user that created
them. If the user is deleted, disabled, or loses a role assignment on a
project, the application credential is deleted.
Application credentials can have their privileges limited in two ways. First,
the owner may specify a subset of their own roles that the application
credential may assume when getting a token for a project. For example, if a
user has the ``member`` role on a project, they also have the implied role
``reader`` and can grant the application credential only the ``reader`` role
for the project:
::
"roles": [
{"name": "reader"}
]
Users also have the option of delegating more fine-grained access control to
their application credentials by using access rules. For example, to create an
application credential that is constricted to creating servers in nova, the
user can add the following access rules:
::
"access_rules": [
{
"path": "/v2.1/servers",
"method": "POST",
"service": "compute"
}
]
The ``"path"`` attribute of application credential access rules uses a wildcard
syntax to make it more flexible. For example, to create an application
credential that is constricted to listing server IP addresses, you could use
either of the following access rules:
::
"access_rules": [
{
"path": "/v2.1/servers/*/ips",
"method": "GET",
"service": "compute"
}
]
or equivalently:
::
"access_rules": [
{
"path": "/v2.1/servers/{server_id}/ips",
"method": "GET",
"service": "compute"
}
]
In both cases, a request path containing any server ID will match the access
rule. For even more flexibility, the recursive wildcard ``**`` indicates that
request paths containing any number of ``/`` will be matched. For example:
::
"access_rules": [
{
"path": "/v2.1/**",
"method": "GET",
"service": "compute"
}
]
will match any nova API for version 2.1.
An access rule created for one application credential can be re-used by providing its ID to another application credential, for example:
::
"access_rules": [
{
"id": "abcdef"
}
]
Authenticating with an Application Credential
=============================================
@ -119,6 +200,7 @@ Parameters
- expires_at: request_application_credential_expires_at_body_not_required
- roles: request_application_credential_roles_body_not_required
- unrestricted: request_application_credential_unrestricted_body_not_required
- access_rules: request_application_credential_access_rules_body_not_required
Example
~~~~~~~
@ -154,6 +236,7 @@ Parameters
- expires_at: response_application_credential_expires_at_body
- project_id: response_application_credential_project_id_body
- roles: response_application_credential_roles_body
- access_rules: response_application_credential_access_rules_body
- unrestricted: response_application_credential_unrestricted_body
- links: link_response_body
@ -207,6 +290,7 @@ Parameters
- expires_at: response_application_credential_expires_at_body
- project_id: response_application_credential_project_id_body
- roles: response_application_credential_roles_body
- access_rules: response_application_credential_access_rules_body
- unrestricted: response_application_credential_unrestricted_body
- links: link_collection
@ -261,6 +345,7 @@ Parameters
- expires_at: response_application_credential_expires_at_body
- project_id: response_application_credential_project_id_body
- roles: response_application_credential_roles_body
- access_rules: response_application_credential_access_rules_body
- unrestricted: response_application_credential_unrestricted_body
- links: link_response_body
@ -302,3 +387,138 @@ Response
- 401
- 403
- 404
List access rules
=================
.. rest_method:: GET /v3/users/{user_id}/access_rules
List all access rules for a user.
Relationship: ``https://docs.openstack.org/api/openstack-identity/3/rel/access_rules``
Request
-------
Parameters
~~~~~~~~~~
.. rest_parameters:: parameters.yaml
- user_id: request_access_rule_user_id_path_required
Response
--------
.. rest_status_code:: success status.yaml
- 200
.. rest_status_code:: error status.yaml
- 401
- 403
- 404
Parameters
~~~~~~~~~~
.. rest_parameters:: parameters.yaml
- access_rules: response_access_rules_body
- id: response_access_rules_id_body
- path: response_access_rules_path_body
- method: response_access_rules_method_body
- service: response_access_rules_service_body
- links: link_collection
Example
~~~~~~~
.. literalinclude:: samples/admin/access-rules-list-response.json
:language: javascript
Show access rule details
========================
.. rest_method:: GET /v3/users/{user_id}/access_rules/{access_rule_id}
Show details of an access rule.
Relationship: ``https://docs.openstack.org/api/openstack-identity/3/rel/access_rules``
Request
-------
Parameters
~~~~~~~~~~
.. rest_parameters:: parameters.yaml
- user_id: request_access_rule_user_id_path_required
- access_rule_id: request_access_rule_id_path_required
Response
--------
.. rest_status_code:: success status.yaml
- 200
.. rest_status_code:: error status.yaml
- 401
- 403
- 404
Parameters
~~~~~~~~~~
.. rest_parameters:: parameters.yaml
- access_rules: response_access_rules_body
- id: response_access_rules_id_body
- path: response_access_rules_path_body
- method: response_access_rules_method_body
- service: response_access_rules_service_body
- links: link_collection
Example
~~~~~~~
.. literalinclude:: samples/admin/access-rule-get-response.json
:language: javascript
Delete access rule
==================
.. rest_method:: DELETE /v3/users/{user_id}/access_rules/{access_rule_id}
Delete an access rule. An access rule that is still in use by an application
credential cannot be deleted.
Relationship: ``https://docs.openstack.org/api/openstack-identity/3/rel/access_rules``
Request
-------
Parameters
~~~~~~~~~~
.. rest_parameters:: parameters.yaml
- user_id: request_access_rule_user_id_path_required
- access_rule_id: request_access_rule_id_path_required
Response
--------
.. rest_status_code:: success status.yaml
- 204
.. rest_status_code:: error status.yaml
- 401
- 403
- 404

7
api-ref/source/v3/index.rst
View File

@ -26,6 +26,13 @@ For information about Identity API protection, see
<https://docs.openstack.org/keystone/latest/admin/service-api-protection.html>`_
in the OpenStack Cloud Administrator Guide.
==================================
What's New in Version 3.13 (Train)
==================================
- New parameter access_rules for application credentials
- New read-only API /v3/users/{user_id}/access_rules for viewing access rules
==================================
What's New in Version 3.12 (Stein)
==================================

60
api-ref/source/v3/parameters.yaml
View File

@ -111,6 +111,18 @@ registered_limit_id_path:
in: path
required: true
type: string
request_access_rule_id_path_required:
description: |
The ID of the access rule.
in: path
required: true
type: string
request_access_rule_user_id_path_required:
description: |
The ID of the user who owns the access rule.
in: path
required: true
type: string
request_application_credential_id_path_required:
description: |
The ID of the application credential.
@ -1557,6 +1569,12 @@ registered_limits:
in: body
required: true
type: array
request_application_credential_access_rules_body_not_required:
description: |
A list of ``access_rules`` objects
in: body
required: false
type: list
request_application_credential_auth_id_body_not_required:
description: |
The ID of the application credential used for authentication. If not
@ -1702,6 +1720,48 @@ resource_name:
in: body
required: true
type: string
response_access_rules_body:
description: |
A list of ``access_rules`` objects
in: body
type: list
required: true
response_access_rules_id_body:
description: |
The ID of the access rule
in: body
type: string
required: true
response_access_rules_method_body:
description: |
The request method that the application credential is permitted to use for
a given API endpoint.
in: body
type: string
required: true
response_access_rules_path_body:
description: |
The API path that the application credential is permitted to access. May
use named wildcards such as ``{tag}`` or the unnamed wildcard ``*`` to
match against any string in the path up to a ``/``, or the recursive
wildcard ``**`` to include ``/`` in the matched path.
in: body
type: string
required: true
response_access_rules_service_body:
description: |
The service type identifier for the service that the application credential
is permitted to access. Must be a service type that is listed in the
service catalog and not a code name for a service.
in: body
type: string
required: true
response_application_credential_access_rules_body:
description: |
A list of ``access_rules`` objects
in: body
type: list
required: true
response_application_credential_body:
description: |
The application credential object.

11
api-ref/source/v3/samples/admin/access-rule-get-response.json Normal file
View File

@ -0,0 +1,11 @@
{
"access_rule": {
"path": "/v2.0/metrics",
"links": {
"self": "https://example.com/identity/v3/access_rules/07d719df00f349ef8de77d542edf010c"
},
"id": "07d719df00f349ef8de77d542edf010c",
"service": "monitoring",
"method": "GET"
}
}

18
api-ref/source/v3/samples/admin/access-rules-list-response.json Normal file
View File

@ -0,0 +1,18 @@
{
"links": {
"self": "https://example.com/identity/v3/users/3e0716aefcad4b129a0f19f95ec9489e/access_rules",
"previous": null,
"next": null
},
"access_rules": [
{
"path": "/v2.0/metrics",
"links": {
"self": "https://example.com/identity/v3/access_rules/07d719df00f349ef8de77d542edf010c"
},
"id": "07d719df00f349ef8de77d542edf010c",
"service": "monitoring",
"method": "GET"
}
]
}

7
api-ref/source/v3/samples/admin/application-credential-create-request.json
View File

@ -7,6 +7,13 @@
"roles": [
{"name": "Reader"}
],
"access_rules": [
{
"path": "/v2.0/metrics",
"method": "GET",
"service": "monitoring"
}
],
"unrestricted": false
}
}

8
api-ref/source/v3/samples/admin/application-credential-create-response.json
View File

@ -8,6 +8,14 @@
"name": "Reader"
}
],
"access_rules": [
{
"path": "/v2.0/metrics",
"id": "07d719df00f349ef8de77d542edf010c",
"service": "monitoring",
"method": "GET"
}
],
"links": {
"self": "http://example.com/identity/v3/users/fd786d56402c4d1691372e7dee0d00b5/application_credentials/58d61ff8e6e34accb35874016d1dba8b"
},

8
api-ref/source/v3/samples/admin/application-credential-get-response.json
View File

@ -8,6 +8,14 @@
"name": "Reader"
}
],
"access_rules": [
{
"path": "/v2.0/metrics",
"id": "07d719df00f349ef8de77d542edf010c",
"service": "monitoring",
"method": "GET"
}
],
"links": {
"self": "http://example.com/identity/v3/users/fd786d56402c4d1691372e7dee0d00b5/application_credentials/58d61ff8e6e34accb35874016d1dba8b"
},

10
api-ref/source/v3/samples/admin/application-credential-list-response.json
View File

@ -14,6 +14,8 @@
"id": "6aff702516544aeca22817fd3bc39683"
}
],
"access_rules": [
],
"links": {
"self": "http://example.com/identity/v3/users/fd786d56402c4d1691372e7dee0d00b5/application_credentials/308a7e905eee4071aac5971744c061f6"
},
@ -32,6 +34,14 @@
"name": "Reader"
}
],
"access_rules": [
{
"path": "/v2.0/metrics",
"id": "07d719df00f349ef8de77d542edf010c",
"service": "monitoring",
"method": "GET"
}
],
"links": {
"self": "http://example.com/identity/v3/users/fd786d56402c4d1691372e7dee0d00b5/application_credentials/58d61ff8e6e34accb35874016d1dba8b"
},

4
keystone/api/discovery.py
View File

@ -28,9 +28,9 @@ _DISCOVERY_BLUEPRINT = flask.Blueprint('Discovery', __name__)
def _get_versions_list(identity_url):
versions = {}
versions['v3'] = {
'id': 'v3.12',
'id': 'v3.13',
'status': 'stable',
'updated': '2019-01-22T00:00:00Z',
'updated': '2019-07-19T00:00:00Z',
'links': [{
'rel': 'self',
'href': identity_url,

4
keystone/tests/unit/test_versions.py
View File

@ -36,9 +36,9 @@ v3_MEDIA_TYPES = [
]
v3_EXPECTED_RESPONSE = {
"id": "v3.12",
"id": "v3.13",
"status": "stable",
"updated": "2019-01-22T00:00:00Z",
"updated": "2019-07-19T00:00:00Z",
"links": [
{
"rel": "self",

2
keystone/version.py
View File

@ -12,4 +12,4 @@
def release_string():
return 'v3.12'
return 'v3.13'

18
releasenotes/notes/bp-whitelist-extension-for-app-creds-90e5bcd7b2b78b02.yaml Normal file
View File

@ -0,0 +1,18 @@
---
prelude: >
[`blueprint whitelist-extension-for-app-creds <https://blueprints.launchpad.net/keystone/+spec/whitelist-extension-for-app-creds>`_]
This release adds support for delegating fine-grained privileges to
application credentials via access rules. Access rules act as a whitelist
of APIs that an application credential is allowed to use. Regular RBAC is
still enforced by oslo.policy. See the `API reference
<https://developer.openstack.org/api-ref/identity/v3/#application-credentials>`_
for details.
features:
- |
[`blueprint whitelist-extension-for-app-creds <https://blueprints.launchpad.net/keystone/+spec/whitelist-extension-for-app-creds>`_]
This release adds support for delegating fine-grained privileges to
application credentials via access rules. Access rules act as a whitelist
of APIs that an application credential is allowed to use. Regular RBAC is
still enforced by oslo.policy. See the `API reference
<https://developer.openstack.org/api-ref/identity/v3/#application-credentials>`_
for details.