Adding documentation for ACLs operations.
Added Secret and Container ACL API reference. Also added ACL related quick start page. ACL docs have been updated to account for ACL API changes e.g. removed per ACL operations. These doc changes are dependent on code changes in review https://review.openstack.org//#/c/180888/ Change-Id: Ia8173e7407cc77d4d4a561905ffe8f9f603eb9cb
This commit is contained in:
Arun Kant
parent
0bf1268d77
commit
d435f7cf2e
@ -10,6 +10,7 @@ Quick Start
|
||||
|
||||
./quickstart/secrets
|
||||
./quickstart/containers
|
||||
./quickstart/acls
|
||||
|
||||
|
||||
API Reference
|
||||
@ -20,3 +21,4 @@ API Reference
|
||||
|
||||
./reference/secrets
|
||||
./reference/containers
|
||||
./reference/acls
|
||||
|
||||
352
doc/source/api/quickstart/acls.rst
Normal file
352
doc/source/api/quickstart/acls.rst
Normal file
@ -0,0 +1,352 @@
|
||||
*************************
|
||||
ACL API - Quick Start
|
||||
*************************
|
||||
|
||||
By default Barbican manages access to its resources (secrets, containers) on a per project
|
||||
level, whereby a user is allowed access to project resources based on the roles a user has
|
||||
in that project.
|
||||
|
||||
Some Barbican use cases prefer a more fine-grained access control for secrets and containers,
|
||||
such as at the user level. The Access Control List (ACL) feature supports this more restrictive
|
||||
access.
|
||||
|
||||
This guide will assume you will be using a local running development environment of Barbican.
|
||||
If you need assistance with getting set up, please reference the :doc:`development guide </setup/dev>`.
|
||||
|
||||
.. warning::
|
||||
|
||||
This ACL documentation is work in progress and may change in near future.
|
||||
|
||||
|
||||
ACL Definition
|
||||
##############
|
||||
|
||||
ACL defines a set of attributes which are used in policy-based authorization to determine
|
||||
access to a target resource. ACL definition is operation specific and is defined per
|
||||
secret or per container.
|
||||
|
||||
Currently only the 'read' operation is defined. This supports allowing users on the ACL for a
|
||||
secret to retrieve its metadata or to decrypt its payload. This also allows users on the ACL
|
||||
for a container to retrieve its list of secret references.
|
||||
|
||||
ACL allow a secret or a container to be marked private. Private secret/container means that only
|
||||
the user who created the secret/container can extract secret. Users with necessary roles on a
|
||||
secret/container project will not have access. To allow access to other users, their user ids
|
||||
need to be added in related ACL users list.
|
||||
|
||||
An operation specific ACL definition has following attribute:
|
||||
* `users`: Whitelist of users who are allowed access to target resource. In this case a user means
|
||||
a Keystone user id.
|
||||
* `creator-only`: Flag to mark a secret or a container private for an operation. Pass `true` to
|
||||
mark private.
|
||||
|
||||
To acommplish above mentioned behavior for a secret/container resource, having ACL data populated
|
||||
alone is not sufficient.
|
||||
|
||||
Following ACL rules are defined and used as `OR` in resource access policy:
|
||||
* ACL based access is allowed when token user is present in secret/container operation specific
|
||||
ACL user list e.g. token user present in `read` users list.
|
||||
* When secret/container resource is marked private, then project-level RBAC users access is not
|
||||
allowed.
|
||||
|
||||
.. note::
|
||||
|
||||
Currently Barbican default policy just makes use of `read` ACL data only. So only **GET**
|
||||
calls for a secret and a container resource will make use of ACL data. Other request methods on
|
||||
secret and container resource still uses project level RBAC checks in policy.
|
||||
|
||||
As per default policy rules, a user with `admin` role in a secret/container project or a user who
|
||||
has created the secret/container can manage ACL for that secret/container.
|
||||
|
||||
.. _default_implicit_acl:
|
||||
|
||||
Default ACL
|
||||
-----------
|
||||
|
||||
By default when no ACL is explicitly set on a secret or a container, then clients with necessary
|
||||
roles on secret's project or container's project can access it. This default access pattern translates
|
||||
to `creator-only` as False and no `users` in ACL settings. That's why every secret and container by
|
||||
default has following implicit ACL.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"read":{
|
||||
"creator-only": false
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
Above default ACL is also returned on **GET** on secret/container **acl** resource when no
|
||||
explicit ACL is set on it.
|
||||
|
||||
|
||||
.. _set_acl:
|
||||
|
||||
How to Set/Replace ACL
|
||||
######################
|
||||
|
||||
The ACL for an existing secret or container can be modified via a **PUT** to the **acl** resource.
|
||||
This update completely replaces existing ACL settings for this secret or container.
|
||||
|
||||
|
||||
To set/replace an ACL for a secret:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
Request:
|
||||
|
||||
curl -X PUT -H 'content-type:application/json' \
|
||||
-H 'X-Auth-Token:b06183778aa64b17beb6215e60686a60' \
|
||||
-d '
|
||||
{
|
||||
"read":{
|
||||
"users":[
|
||||
"2d0ee7c681cc4549b6d76769c320d91f",
|
||||
"721e27b8505b499e8ab3b38154705b9e",
|
||||
"c1d20e4b7e7d4917aee6f0832152269b"
|
||||
],
|
||||
"creator-only":true
|
||||
}
|
||||
}' \
|
||||
http://localhost:9311/v1/secrets/15621a1b-efdf-41d8-92dc-356cec8e9da9/acl
|
||||
|
||||
Response (includes secret ACL reference):
|
||||
|
||||
HTTP/1.1 201 Created
|
||||
{"acl_ref": "http://localhost:9311/v1/secrets/15621a1b-efdf-41d8-92dc-356cec8e9da9/acl"}
|
||||
|
||||
|
||||
To set/replace an ACL for a container:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
Request:
|
||||
|
||||
curl -X PUT -H 'content-type:application/json' \
|
||||
-H 'X-Auth-Token:b06183778aa64b17beb6215e60686a60' \
|
||||
-d '
|
||||
{
|
||||
"read":{
|
||||
"users":[
|
||||
"2d0ee7c681cc4549b6d76769c320d91f",
|
||||
"721e27b8505b499e8ab3b38154705b9e",
|
||||
"c1d20e4b7e7d4917aee6f0832152269b"
|
||||
],
|
||||
"creator-only":true
|
||||
}
|
||||
}' \
|
||||
http://localhost:9311/v1/containers/8c077991-d524-4e15-8eaf-bc0c3bb225f2/acl
|
||||
|
||||
Response (includes container ACL reference):
|
||||
|
||||
HTTP/1.1 201 Created
|
||||
{"acl_ref": "http://localhost:9311/v1/containers/8c077991-d524-4e15-8eaf-bc0c3bb225f2/acl"}
|
||||
|
||||
To get more details on the create API you can reference the :ref:`Set Secret ACL <put_secret_acl>`
|
||||
or :ref:`Set Container ACL <put_container_acl>` documentation.
|
||||
|
||||
|
||||
.. _update_acl:
|
||||
|
||||
How to Update ACL
|
||||
#################
|
||||
|
||||
Existing ACL can be updated via **PUT** or **PATCH** methods on a given secret/container.
|
||||
**PUT** interaction replaces existing ACL with provided ACL data whereas **PATCH**
|
||||
interaction applies the provided changes on existing ACL of a secret or a container.
|
||||
|
||||
To replace an existing ACL for a container:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
Request:
|
||||
|
||||
curl -X PUT -H 'content-type:application/json' \
|
||||
-H 'X-Auth-Token:e1f540bc6def456dbb0f8c11f21a74ae' \
|
||||
-d '
|
||||
{
|
||||
"read":{
|
||||
"users":[
|
||||
"2d0ee7c681cc4549b6d76769c320d91f",
|
||||
"721e27b8505b499e8ab3b38154705b9e"
|
||||
],
|
||||
"creator-only":false
|
||||
}
|
||||
}' \
|
||||
http://localhost:9311/v1/containers/8c077991-d524-4e15-8eaf-bc0c3bb225f2/acl
|
||||
|
||||
Response (includes container ACL reference):
|
||||
|
||||
HTTP/1.1 200 OK
|
||||
{"acl_ref": "http://localhost:9311/v1/containers/8c077991-d524-4e15-8eaf-bc0c3bb225f2/acl"}
|
||||
|
||||
|
||||
To remove all users from an existing ACL for a container (pass empty list in `users`):
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
Request:
|
||||
|
||||
curl -X PUT -H 'content-type:application/json' \
|
||||
-H 'X-Auth-Token:e1f540bc6def456dbb0f8c11f21a74ae' \
|
||||
-d '
|
||||
{
|
||||
"read":{
|
||||
"users":[],
|
||||
"creator-only":false
|
||||
}
|
||||
}' \
|
||||
http://localhost:9311/v1/containers/8c077991-d524-4e15-8eaf-bc0c3bb225f2/acl
|
||||
|
||||
Response (includes container ACL reference):
|
||||
|
||||
HTTP/1.1 200 OK
|
||||
{"acl_ref": "http://localhost:9311/v1/containers/8c077991-d524-4e15-8eaf-bc0c3bb225f2/acl"}
|
||||
|
||||
|
||||
To update only the creator-only flag for container ACL (use PATCH):
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
Request:
|
||||
|
||||
curl -X PATCH -H 'content-type:application/json' \
|
||||
-H 'X-Auth-Token:e1f540bc6def456dbb0f8c11f21a74ae' \
|
||||
-d '
|
||||
{
|
||||
"read":{
|
||||
"creator-only":true
|
||||
}
|
||||
}' \
|
||||
http://localhost:9311/v1/containers/8c077991-d524-4e15-8eaf-bc0c3bb225f2/acl
|
||||
|
||||
Response:
|
||||
|
||||
HTTP/1.1 200 OK
|
||||
{"acl_ref": "http://localhost:9311/v1/containers/8c077991-d524-4e15-8eaf-bc0c3bb225f2/acl"}
|
||||
|
||||
|
||||
To update only the users list for secret ACL (use PATCH):
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
Request:
|
||||
|
||||
curl -X PATCH -H 'content-type:application/json' \
|
||||
-H 'X-Auth-Token:e1f540bc6def456dbb0f8c11f21a74ae' \
|
||||
-d '
|
||||
{
|
||||
"read":{
|
||||
"users":[
|
||||
"2d0ee7c681cc4549b6d76769c320d91f",
|
||||
"c1d20e4b7e7d4917aee6f0832152269b"
|
||||
],
|
||||
}
|
||||
}' \
|
||||
http://localhost:9311/v1/secrets/15621a1b-efdf-41d8-92dc-356cec8e9da9/acl
|
||||
|
||||
Response:
|
||||
|
||||
HTTP/1.1 200 OK
|
||||
{"acl_ref": "http://localhost:9311/v1/secrets/15621a1b-efdf-41d8-92dc-356cec8e9da9/acl"}
|
||||
|
||||
|
||||
|
||||
Container and Secret ACL(s) update operation are similar except `containers` resource is used
|
||||
instead of the `secrets` resource in URI. To get more details on ACL update APIs, you can reference
|
||||
the :ref:`Update Secret ACL <put_secret_acl>` , :ref:`Update Container ACL <put_container_acl>`
|
||||
, :ref:`Partial Update Secret ACL <patch_secret_acl>` or :ref:`Partial Update Container ACL
|
||||
<patch_container_acl>` documentation.
|
||||
|
||||
|
||||
.. _retrieve_acl:
|
||||
|
||||
How to Retrieve ACL
|
||||
###################
|
||||
|
||||
The ACL defined for a secret or container can be retrieved by using a **GET** operation on
|
||||
respective **acl** resource.
|
||||
The returned response contains ACL data.
|
||||
|
||||
To get secret ACL data:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
Request:
|
||||
|
||||
curl -X GET -H 'X-Auth-Token:b44636bff48c41bbb80f459df69c11aa' \
|
||||
http://localhost:9311/v1/secrets/15621a1b-efdf-41d8-92dc-356cec8e9da9/acl
|
||||
|
||||
Response:
|
||||
|
||||
HTTP/1.1 200 OK
|
||||
{
|
||||
"read":{
|
||||
"updated":"2015-05-12T20:08:47.644264",
|
||||
"created":"2015-05-12T19:23:44.019168",
|
||||
"users":[
|
||||
"c1d20e4b7e7d4917aee6f0832152269b",
|
||||
"2d0ee7c681cc4549b6d76769c320d91f"
|
||||
],
|
||||
"creator-only":true
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
To get container ACL data:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
Request:
|
||||
|
||||
curl -X GET -H 'X-Auth-Token:b44636bff48c41bbb80f459df69c11aa' \
|
||||
http://localhost:9311/v1/containers/8c077991-d524-4e15-8eaf-bc0c3bb225f2/acl
|
||||
|
||||
Response:
|
||||
|
||||
HTTP/1.1 200 OK
|
||||
{
|
||||
"read":{
|
||||
"updated":"2015-05-12T20:05:17.214948",
|
||||
"created":"2015-05-12T19:47:20.018657",
|
||||
"users":[
|
||||
"721e27b8505b499e8ab3b38154705b9e",
|
||||
"c1d20e4b7e7d4917aee6f0832152269b",
|
||||
"2d0ee7c681cc4549b6d76769c320d91f"
|
||||
],
|
||||
"creator-only":true
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
To get more details on ACL lookup APIs you can reference the :ref:`Get Secret ACL <get_secret_acl>` ,
|
||||
:ref:`Get Container ACL <get_container_acl>` documentation.
|
||||
|
||||
|
||||
.. _delete_acl:
|
||||
|
||||
How to Delete ACL
|
||||
#################
|
||||
|
||||
ACL defined for a secret or a container can be deleted by using the **DELETE** operation on their respective `acl`
|
||||
resource. There is no response content returned on successful deletion.
|
||||
|
||||
Delete operation removes existing ACL on a secret or a container if there. It can be treated as resetting a secret
|
||||
or a container to :ref:`Default ACL<default_implicit_acl>` setting. That's why invoking delete multiple times on
|
||||
this resource will not result in error.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
Request:
|
||||
|
||||
curl -X DELETE -H 'X-Auth-Token:b06183778aa64b17beb6215e60686a60' \
|
||||
http://localhost:9311/v1/secrets/50f5ed8e-004e-433a-939c-fa73c7fc81fd/acl
|
||||
|
||||
Response:
|
||||
|
||||
200 OK
|
||||
|
||||
|
||||
To get more details on ACL delete APIs, you can reference the :ref:`Delete Secret ACL <delete_secret_acl>` ,
|
||||
:ref:`Delete Container ACL <delete_container_acl>` documentation.
|
||||
670
doc/source/api/reference/acls.rst
Normal file
670
doc/source/api/reference/acls.rst
Normal file
@ -0,0 +1,670 @@
|
||||
***********************
|
||||
ACL API - Reference
|
||||
***********************
|
||||
|
||||
.. note::
|
||||
|
||||
This feature is applicable only when Barbican is used in an authenticated
|
||||
pipeline i.e. integrated with Keystone.
|
||||
|
||||
.. note::
|
||||
|
||||
Currently the access control list (ACL) settings defined for a container
|
||||
are not propagated down to associated secrets.
|
||||
|
||||
.. warning::
|
||||
|
||||
This ACL documentation is work in progress and may change in near future.
|
||||
|
||||
|
||||
Secret ACL API
|
||||
===============
|
||||
|
||||
.. _get_secret_acl:
|
||||
|
||||
GET /v1/secrets/{uuid}/acl
|
||||
##########################
|
||||
Retrieve the ACL settings for a given secret.
|
||||
|
||||
If no ACL is defined for that secret, then :ref:`Default ACL<default_implicit_acl>` is returned.
|
||||
|
||||
Request/Response (With ACL defined):
|
||||
************************************
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
Request:
|
||||
|
||||
GET /v1/secrets/{uuid}/acl
|
||||
Headers:
|
||||
X-Auth-Token: {token_id}
|
||||
|
||||
Response:
|
||||
|
||||
HTTP/1.1 200 OK
|
||||
{
|
||||
"read":{
|
||||
"updated":"2015-05-12T20:08:47.644264",
|
||||
"created":"2015-05-12T19:23:44.019168",
|
||||
"users":[
|
||||
{user_id1},
|
||||
{user_id2},
|
||||
.....
|
||||
],
|
||||
"creator-only":{creator-only-flag}
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
Request/Response (With no ACL defined):
|
||||
***************************************
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
Request:
|
||||
|
||||
GET /v1/secrets/{uuid}/acl
|
||||
Headers:
|
||||
X-Auth-Token: {token_id}
|
||||
|
||||
Response:
|
||||
|
||||
HTTP/1.1 200 OK
|
||||
{
|
||||
"read":{
|
||||
"creator-only": false
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
|
||||
HTTP Status Codes
|
||||
*****************
|
||||
|
||||
+------+-----------------------------------------------------------------------------+
|
||||
| Code | Description |
|
||||
+======+=============================================================================+
|
||||
| 200 | Successful request. |
|
||||
+------+-----------------------------------------------------------------------------+
|
||||
| 401 | Missing or Invalid X-Auth-Token. Authentication required. |
|
||||
+------+-----------------------------------------------------------------------------+
|
||||
| 403 | User does not have have permission to access this resource. |
|
||||
+------+-----------------------------------------------------------------------------+
|
||||
| 404 | Secret not found for the given UUID. |
|
||||
+------+-----------------------------------------------------------------------------+
|
||||
|
||||
.. _put_secret_acl:
|
||||
|
||||
PUT /v1/secrets/{uuid}/acl
|
||||
##########################
|
||||
Create new or replaces existing ACL for a given secret.
|
||||
|
||||
This call is used to add new ACL for a secret. If the ACL is already set on a secret, this
|
||||
method will replace it with the requested ACL settings. In case of create (first new explicit
|
||||
ACL) or replace existing ACL, 200 is returned in both cases. To delete existing users from
|
||||
an ACL definition, pass empty list [] for `users`.
|
||||
|
||||
Returns an ACL reference in success case.
|
||||
|
||||
Attributes
|
||||
**********
|
||||
|
||||
The ACL resource detailed in this page allows access to individual secrets to be controlled.
|
||||
This access is configured via operations on those secrets. Currently only the 'read' operation
|
||||
(which includes GET REST actions) is supported.
|
||||
|
||||
+----------------------------+----------+-----------------------------------------------+----------+
|
||||
| Attribute Name | Type | Description | Default |
|
||||
+============================+==========+===============================================+==========+
|
||||
| read | parent | ACL data for read operation. | None |
|
||||
| | element | | |
|
||||
+----------------------------+----------+-----------------------------------------------+----------+
|
||||
| users | [string] | (optional) List of user ids. This needs to be | [] |
|
||||
| | | a user id as returned by Keystone. | |
|
||||
+----------------------------+----------+-----------------------------------------------+----------+
|
||||
| creator-only | boolean | (optional) Flag to mark a secret private so | `false` |
|
||||
| | | that the user who created the secret and | |
|
||||
| | | ``users`` specified in above list can only | |
|
||||
| | | access the secret. Pass `true` to mark the | |
|
||||
| | | secret private. | |
|
||||
+----------------------------+----------+-----------------------------------------------+----------+
|
||||
|
||||
|
||||
Request/Response (Set ACL):
|
||||
***************************
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
Request:
|
||||
|
||||
PUT /v1/secrets/{uuid}/acl
|
||||
Headers:
|
||||
Content-Type: application/json
|
||||
X-Auth-Token: {token_id}
|
||||
|
||||
Body:
|
||||
{
|
||||
"read":{
|
||||
"users":[
|
||||
{user_id1},
|
||||
{user_id2},
|
||||
.....
|
||||
],
|
||||
"creator-only":{creator-only-flag}
|
||||
}
|
||||
}
|
||||
|
||||
Response:
|
||||
|
||||
HTTP/1.1 200 OK
|
||||
{"acl_ref": "https://{barbican_host}/v1/secrets/{uuid}/acl"}
|
||||
|
||||
Request/Response (Replace ACL):
|
||||
******************************
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
PUT /v1/secrets/{uuid}/acl
|
||||
Headers:
|
||||
Content-Type: application/json
|
||||
X-Auth-Token: {token_id}
|
||||
|
||||
Body:
|
||||
{
|
||||
"read":{
|
||||
"users":[
|
||||
{user_id1},
|
||||
{user_id2},
|
||||
.....
|
||||
],
|
||||
"creator-only":{creator-only-flag}
|
||||
}
|
||||
}
|
||||
|
||||
Response:
|
||||
HTTP/1.1 200 OK
|
||||
{"acl_ref": "https://{barbican_host}/v1/secrets/{uuid}/acl"}
|
||||
|
||||
|
||||
|
||||
HTTP Status Codes
|
||||
*****************
|
||||
|
||||
+------+-----------------------------------------------------------------------------+
|
||||
| Code | Description |
|
||||
+======+=============================================================================+
|
||||
| 200 | Successfully set/replaced secret ACL. |
|
||||
+------+-----------------------------------------------------------------------------+
|
||||
| 400 | Bad Request. |
|
||||
+------+-----------------------------------------------------------------------------+
|
||||
| 401 | Missing or Invalid X-Auth-Token. Authentication required. |
|
||||
+------+-----------------------------------------------------------------------------+
|
||||
| 403 | User does not have have permission to access this resource. |
|
||||
+------+-----------------------------------------------------------------------------+
|
||||
| 404 | Secret not found for the given UUID. |
|
||||
+------+-----------------------------------------------------------------------------+
|
||||
| 415 | Unsupported Media Type. |
|
||||
+------+-----------------------------------------------------------------------------+
|
||||
|
||||
|
||||
.. _patch_secret_acl:
|
||||
|
||||
PATCH /v1/secrets/{uuid}/acl
|
||||
############################
|
||||
|
||||
Updates existing ACL for a given secret. This method can be used to apply partial changes on
|
||||
existing ACL settings. Client can update the `users` list and enable or disable `creator-only`
|
||||
flag for existing ACL. List of provided users replaces existing users if any. For an existing
|
||||
list of provided users from an ACL definition, pass empty list [] for `users`.
|
||||
|
||||
Returns an ACL reference in success case.
|
||||
|
||||
.. note::
|
||||
|
||||
PATCH API support will be changing in near future.
|
||||
|
||||
Attributes
|
||||
**********
|
||||
|
||||
+----------------------------+----------+-----------------------------------------------+----------+
|
||||
| Attribute Name | Type | Description | Default |
|
||||
+============================+==========+===============================================+==========+
|
||||
| read | parent | ACL data for read operation. | None |
|
||||
| | element | | |
|
||||
+----------------------------+----------+-----------------------------------------------+----------+
|
||||
| users | [string] | (optional) List of user ids. This needs to be | None |
|
||||
| | | a user id as returned by Keystone. | |
|
||||
+----------------------------+----------+-----------------------------------------------+----------+
|
||||
| creator-only | boolean | (optional) Flag to mark a secret private so | None |
|
||||
| | | that the user who created the secret and | |
|
||||
| | | ``users`` specified in above list can only | |
|
||||
| | | access the secret. Pass `true` to mark the | |
|
||||
| | | secret private. | |
|
||||
+----------------------------+----------+-----------------------------------------------+----------+
|
||||
|
||||
Request/Response (Updating creator-only flag):
|
||||
**********************************************
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
PATCH /v1/secrets/{uuid}/acl
|
||||
Headers:
|
||||
Content-Type: application/json
|
||||
X-Auth-Token: {token_id}
|
||||
|
||||
Body:
|
||||
{
|
||||
"read":
|
||||
{
|
||||
"creator-only":true
|
||||
}
|
||||
}
|
||||
|
||||
Response:
|
||||
HTTP/1.1 200 OK
|
||||
{"acl_ref": "https://{barbican_host}/v1/secrets/{uuid}/acl"}
|
||||
|
||||
|
||||
Request/Response (Removing all users from ACL):
|
||||
***********************************************
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
PATCH /v1/secrets/{uuid}/acl
|
||||
Headers:
|
||||
Content-Type: application/json
|
||||
X-Auth-Token: {token_id}
|
||||
|
||||
Body:
|
||||
{
|
||||
"read":
|
||||
{
|
||||
"users":[]
|
||||
}
|
||||
}
|
||||
|
||||
Response:
|
||||
HTTP/1.1 200 OK
|
||||
{"acl_ref": "https://{barbican_host}/v1/secrets/{uuid}/acl"}
|
||||
|
||||
|
||||
HTTP Status Codes
|
||||
*****************
|
||||
|
||||
+------+-----------------------------------------------------------------------------+
|
||||
| Code | Description |
|
||||
+======+=============================================================================+
|
||||
| 200 | Successfully updated secret ACL. |
|
||||
+------+-----------------------------------------------------------------------------+
|
||||
| 400 | Bad Request. |
|
||||
+------+-----------------------------------------------------------------------------+
|
||||
| 401 | Missing or Invalid X-Auth-Token. Authentication required. |
|
||||
+------+-----------------------------------------------------------------------------+
|
||||
| 403 | User does not have have permission to access this resource. |
|
||||
+------+-----------------------------------------------------------------------------+
|
||||
| 404 | Secret not found for the given UUID. |
|
||||
+------+-----------------------------------------------------------------------------+
|
||||
| 415 | Unsupported Media Type. |
|
||||
+------+-----------------------------------------------------------------------------+
|
||||
|
||||
.. _delete_secret_acl:
|
||||
|
||||
DELETE /v1/secrets/{uuid}/acl
|
||||
##############################
|
||||
|
||||
Delete ACL for a given secret. No content is returned in the case of successful
|
||||
deletion.
|
||||
|
||||
Request/Response:
|
||||
*****************
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
DELETE /v1/secrets/{uuid}/acl
|
||||
Headers:
|
||||
X-Auth-Token: {token_id}
|
||||
|
||||
Response:
|
||||
HTTP/1.1 200 OK
|
||||
|
||||
|
||||
HTTP Status Codes
|
||||
*****************
|
||||
|
||||
+------+-----------------------------------------------------------------------------+
|
||||
| Code | Description |
|
||||
+======+=============================================================================+
|
||||
| 200 | Successfully deleted secret ACL. |
|
||||
+------+-----------------------------------------------------------------------------+
|
||||
| 401 | Missing or Invalid X-Auth-Token. Authentication required. |
|
||||
+------+-----------------------------------------------------------------------------+
|
||||
| 403 | User does not have have permission to access this resource. |
|
||||
+------+-----------------------------------------------------------------------------+
|
||||
| 404 | Secret not found for the given UUID. |
|
||||
+------+-----------------------------------------------------------------------------+
|
||||
|
||||
Container ACL API
|
||||
==================
|
||||
|
||||
.. _get_container_acl:
|
||||
|
||||
GET /v1/containers/{uuid}/acl
|
||||
#############################
|
||||
Retrieve the ACL settings for a given container.
|
||||
|
||||
If no ACL is defined for that container, then :ref:`Default ACL<default_implicit_acl>` is returned.
|
||||
|
||||
Request/Response (With ACL defined):
|
||||
************************************
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
Request:
|
||||
|
||||
GET /v1/containers/{uuid}/acl
|
||||
Headers:
|
||||
X-Auth-Token: {token_id}
|
||||
|
||||
Response:
|
||||
|
||||
HTTP/1.1 200 OK
|
||||
{
|
||||
"read":{
|
||||
"updated":"2015-05-12T20:08:47.644264",
|
||||
"created":"2015-05-12T19:23:44.019168",
|
||||
"users":[
|
||||
{user_id1},
|
||||
{user_id2},
|
||||
.....
|
||||
],
|
||||
"creator-only":{creator-only-flag}
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
Request/Response (With no ACL defined):
|
||||
***************************************
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
Request:
|
||||
|
||||
GET /v1/containers/{uuid}/acl
|
||||
Headers:
|
||||
X-Auth-Token: {token_id}
|
||||
|
||||
Response:
|
||||
|
||||
HTTP/1.1 200 OK
|
||||
{
|
||||
"read":{
|
||||
"creator-only": false
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
|
||||
HTTP Status Codes
|
||||
*****************
|
||||
|
||||
+------+-----------------------------------------------------------------------------+
|
||||
| Code | Description |
|
||||
+======+=============================================================================+
|
||||
| 200 | Successful request. |
|
||||
+------+-----------------------------------------------------------------------------+
|
||||
| 401 | Missing or Invalid X-Auth-Token. Authentication required. |
|
||||
+------+-----------------------------------------------------------------------------+
|
||||
| 403 | User does not have have permission to access this resource. |
|
||||
+------+-----------------------------------------------------------------------------+
|
||||
| 404 | Container not found for the given UUID. |
|
||||
+------+-----------------------------------------------------------------------------+
|
||||
|
||||
.. _put_container_acl:
|
||||
|
||||
PUT /v1/containers/{uuid}/acl
|
||||
#############################
|
||||
Create new or replaces existing ACL for a given container.
|
||||
|
||||
This call is used to add new ACL for an container. If the ACL is already set on a container,
|
||||
this method will replace it with the requested ACL settings. In case of create (first new explicit
|
||||
ACL) or replace existing ACL, 200 is returned in both cases. To delete existing users from
|
||||
an ACL definition, pass empty list [] for `users`.
|
||||
|
||||
Returns an ACL reference in success case.
|
||||
|
||||
Attributes
|
||||
**********
|
||||
|
||||
The ACL resource detailed in this page allows access to individual containers to be controlled.
|
||||
This access is configured via operations on those containers. Currently only the 'read' operation
|
||||
(which includes GET REST actions) is supported.
|
||||
|
||||
+----------------------------+----------+-----------------------------------------------+----------+
|
||||
| Attribute Name | Type | Description | Default |
|
||||
+============================+==========+===============================================+==========+
|
||||
| read | parent | ACL data for read operation. | None |
|
||||
| | element | | |
|
||||
+----------------------------+----------+-----------------------------------------------+----------+
|
||||
| users | [string] | (optional) List of user ids. This needs to be | [] |
|
||||
| | | a user id as returned by Keystone. | |
|
||||
+----------------------------+----------+-----------------------------------------------+----------+
|
||||
| creator-only | boolean | (optional) Flag to mark a container private | `false` |
|
||||
| | | so that the user who created the container and| |
|
||||
| | | ``users`` specified in above list can only | |
|
||||
| | | access the container. Pass `true` to mark the | |
|
||||
| | | container private. | |
|
||||
+----------------------------+----------+-----------------------------------------------+----------+
|
||||
|
||||
|
||||
Request/Response (Set ACL):
|
||||
***************************
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
Request:
|
||||
|
||||
PUT /v1/containers/{uuid}/acl
|
||||
Headers:
|
||||
Content-Type: application/json
|
||||
X-Auth-Token: {token_id}
|
||||
|
||||
Body:
|
||||
{
|
||||
"read":{
|
||||
"users":[
|
||||
{user_id1},
|
||||
{user_id2},
|
||||
.....
|
||||
],
|
||||
"creator-only":{creator-only-flag}
|
||||
}
|
||||
}
|
||||
|
||||
Response:
|
||||
|
||||
HTTP/1.1 201 Created
|
||||
{"acl_ref": "https://{barbican_host}/v1/containers/{uuid}/acl"}
|
||||
|
||||
Request/Response (Replace ACL):
|
||||
******************************
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
PUT /v1/containers/{uuid}/acl
|
||||
Headers:
|
||||
Content-Type: application/json
|
||||
X-Auth-Token: {token_id}
|
||||
|
||||
Body:
|
||||
{
|
||||
"read":{
|
||||
"users":[
|
||||
{user_id1},
|
||||
{user_id2},
|
||||
.....
|
||||
],
|
||||
"creator-only":{creator-only-flag}
|
||||
}
|
||||
}
|
||||
|
||||
Response:
|
||||
HTTP/1.1 200 OK
|
||||
{"acl_ref": "https://{barbican_host}/v1/containers/{uuid}/acl"}
|
||||
|
||||
|
||||
|
||||
HTTP Status Codes
|
||||
*****************
|
||||
|
||||
+------+-----------------------------------------------------------------------------+
|
||||
| Code | Description |
|
||||
+======+=============================================================================+
|
||||
| 200 | Successfully set/replaced container ACL. |
|
||||
+------+-----------------------------------------------------------------------------+
|
||||
| 400 | Bad Request. |
|
||||
+------+-----------------------------------------------------------------------------+
|
||||
| 401 | Missing or Invalid X-Auth-Token. Authentication required. |
|
||||
+------+-----------------------------------------------------------------------------+
|
||||
| 403 | User does not have have permission to access this resource. |
|
||||
+------+-----------------------------------------------------------------------------+
|
||||
| 404 | Container not found for the given UUID. |
|
||||
+------+-----------------------------------------------------------------------------+
|
||||
| 415 | Unsupported Media Type. |
|
||||
+------+-----------------------------------------------------------------------------+
|
||||
|
||||
|
||||
.. _patch_container_acl:
|
||||
|
||||
PATCH /v1/containers/{uuid}/acl
|
||||
###############################
|
||||
|
||||
Update existing ACL for a given container. This method can be used to apply partial changes
|
||||
on existing ACL settings. Client can update `users` list and enable or disable `creator-only`
|
||||
flag for existing ACL. List of provided users replaces existing users if any. For an existing
|
||||
list of provided users from an ACL definition, pass empty list [] for `users`.
|
||||
|
||||
Returns an ACL reference in success case.
|
||||
|
||||
.. note::
|
||||
|
||||
PATCH API support will be changing in near future.
|
||||
|
||||
Attributes
|
||||
**********
|
||||
|
||||
+----------------------------+----------+-----------------------------------------------+----------+
|
||||
| Attribute Name | Type | Description | Default |
|
||||
+============================+==========+===============================================+==========+
|
||||
| read | parent | ACL data for read operation. | None |
|
||||
| | element | | |
|
||||
+----------------------------+----------+-----------------------------------------------+----------+
|
||||
| users | [string] | (optional) List of user ids. This needs to be | None |
|
||||
| | | a user id as returned by Keystone. | |
|
||||
+----------------------------+----------+-----------------------------------------------+----------+
|
||||
| creator-only | boolean | (optional) Flag to mark a container private | None |
|
||||
| | | so that the user who created the container and| |
|
||||
| | | ``users`` specified in above list can only | |
|
||||
| | | access the container. Pass `true` to mark the | |
|
||||
| | | container private. | |
|
||||
+----------------------------+----------+-----------------------------------------------+----------+
|
||||
|
||||
Request/Response (Updating creator-only flag):
|
||||
**********************************************
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
PATCH /v1/containers/{uuid}/acl
|
||||
Headers:
|
||||
Content-Type: application/json
|
||||
X-Auth-Token: {token_id}
|
||||
|
||||
Body:
|
||||
{
|
||||
"read":
|
||||
{
|
||||
"creator-only":true
|
||||
}
|
||||
}
|
||||
|
||||
Response:
|
||||
HTTP/1.1 200 OK
|
||||
{"acl_ref": "https://{barbican_host}/v1/containers/{uuid}/acl"}
|
||||
|
||||
|
||||
Request/Response (Removing all users from ACL):
|
||||
***********************************************
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
PATCH /v1/containers/{uuid}/acl
|
||||
Headers:
|
||||
Content-Type: application/json
|
||||
X-Auth-Token: {token_id}
|
||||
|
||||
Body:
|
||||
{
|
||||
"read":
|
||||
{
|
||||
"users":[]
|
||||
}
|
||||
}
|
||||
|
||||
Response:
|
||||
HTTP/1.1 200 OK
|
||||
{"acl_ref": "https://{barbican_host}/v1/containers/{uuid}/acl"}
|
||||
|
||||
|
||||
HTTP Status Codes
|
||||
*****************
|
||||
|
||||
+------+-----------------------------------------------------------------------------+
|
||||
| Code | Description |
|
||||
+======+=============================================================================+
|
||||
| 200 | Successfully updated container ACL. |
|
||||
+------+-----------------------------------------------------------------------------+
|
||||
| 400 | Bad Request. |
|
||||
+------+-----------------------------------------------------------------------------+
|
||||
| 401 | Missing or Invalid X-Auth-Token. Authentication required. |
|
||||
+------+-----------------------------------------------------------------------------+
|
||||
| 403 | User does not have have permission to access this resource. |
|
||||
+------+-----------------------------------------------------------------------------+
|
||||
| 404 | Container not found for the given UUID. |
|
||||
+------+-----------------------------------------------------------------------------+
|
||||
| 415 | Unsupported Media Type. |
|
||||
+------+-----------------------------------------------------------------------------+
|
||||
|
||||
.. _delete_container_acl:
|
||||
|
||||
DELETE /v1/containers/{uuid}/acl
|
||||
################################
|
||||
|
||||
Delete ACL for a given container. No content is returned in the case of successful
|
||||
deletion.
|
||||
|
||||
Request/Response:
|
||||
*****************
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
DELETE /v1/containers/{uuid}/acl
|
||||
Headers:
|
||||
X-Auth-Token: {token_id}
|
||||
|
||||
Response:
|
||||
HTTP/1.1 200 OK
|
||||
|
||||
|
||||
HTTP Status Codes
|
||||
*****************
|
||||
|
||||
+------+-----------------------------------------------------------------------------+
|
||||
| Code | Description |
|
||||
+======+=============================================================================+
|
||||
| 200 | Successfully deleted container ACL. |
|
||||
+------+-----------------------------------------------------------------------------+
|
||||
| 401 | Missing or Invalid X-Auth-Token. Authentication required. |
|
||||
+------+-----------------------------------------------------------------------------+
|
||||
| 403 | User does not have have permission to access this resource. |
|
||||
+------+-----------------------------------------------------------------------------+
|
||||
| 404 | Container not found for the given UUID. |
|
||||
+------+-----------------------------------------------------------------------------+
|
||||
Loading…
x
Reference in New Issue
Block a user