Merge "Adding documentation for ACLs operations."
This commit is contained in:
Jenkins
@@ -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. |
|
||||
+------+-----------------------------------------------------------------------------+
|
||||
Reference in New Issue
Block a user