openstack/barbican
Code Issues Proposed changes
aafeb7aa91
barbican/api-guide/source/acls.rst
chenxing 2a58454289 Update the documentation link for doc migration 
These links need to be updated due to the doc migration. Current
links are no longer effective.

Change-Id: I218995d5c8cde34286e2133a53bd7d19ae46c75d
2017-10-11 18:11:17 +08:00

11 KiB
Raw Blame History

ACL API User Guide

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 development guide

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.
  • `project-access`: Flag to mark a secret or a container private for an operation. Pass false to mark private.

To accomplish 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 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 project-access as true and no users in ACL settings. That's why every secret and container by default has following implicit ACL.

{
  "read":{
    "project-access": true
  }
}

Above default ACL is also returned on GET on secret/container acl resource when no explicit ACL is set on it.

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:

Request:

curl -X PUT -H 'content-type:application/json' \
-H 'X-Auth-Token:b06183778aa64b17beb6215e60686a60' \
-d '
{
  "read":{
    "users":[
      "2d0ee7c681cc4549b6d76769c320d91f",
      "721e27b8505b499e8ab3b38154705b9e",
      "c1d20e4b7e7d4917aee6f0832152269b"
    ],
    "project-access":false
  }
}' \
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:

Request:

curl -X PUT -H 'content-type:application/json' \
-H 'X-Auth-Token:b06183778aa64b17beb6215e60686a60' \
-d '
{
  "read":{
    "users":[
      "2d0ee7c681cc4549b6d76769c320d91f",
      "721e27b8505b499e8ab3b38154705b9e",
      "c1d20e4b7e7d4917aee6f0832152269b"
    ],
    "project-access":false
  }
}' \
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 Set Secret ACL or Set Container ACL documentation.

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:

Request:

curl -X PUT -H 'content-type:application/json' \
-H 'X-Auth-Token:e1f540bc6def456dbb0f8c11f21a74ae' \
-d '
{
  "read":{
    "users":[
      "2d0ee7c681cc4549b6d76769c320d91f",
      "721e27b8505b499e8ab3b38154705b9e"
    ],
    "project-access":true
  }
}' \
 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):

Request:

curl -X PUT -H 'content-type:application/json' \
-H 'X-Auth-Token:e1f540bc6def456dbb0f8c11f21a74ae' \
-d '
{
  "read":{
    "users":[],
    "project-access":true
  }
}' \
 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 project-access flag for container ACL (use PATCH):

Request:

curl -X PATCH -H 'content-type:application/json' \
-H 'X-Auth-Token:e1f540bc6def456dbb0f8c11f21a74ae' \
-d '
{
  "read":{
    "project-access":false
  }
}' \
 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):

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 Update Secret ACL , Update Container ACL , Partial Update Secret ACL or Partial Update Container ACL documentation.

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:

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"
    ],
    "project-access":false
  }
}

To get container ACL data:

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"
    ],
    "project-access":false
  }
}

To get more details on ACL lookup APIs you can reference the Get Secret ACL , Get Container ACL documentation.

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 Default ACL setting. That's why invoking delete multiple times on this resource will not result in error.

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 Delete Secret ACL , Delete Container ACL documentation.