From c0fdc53b4999528791ff7e57cecf74d2208a7f00 Mon Sep 17 00:00:00 2001 From: Donagh McCabe Date: Wed, 21 Sep 2016 15:23:03 +0100 Subject: Document access control lists (ACLs) Documents the syntax and meaning of container ACLs. Account ACLs were already pretty well documented. However the account ACL text was moved as part of this change. TempAuth and keystoneauth have diffent ACLs. However, I decided to describe both in one section/table because there are many "examples" of ACLs in other documents, and it's better that someone coming here from those sources become aware that the specific ACL might not apply to them. In addition, the referrer and .rlistings is common to both. Some changes were also made to the api-ref document. The doc and api-ref documents are published as seperate documents, so the cross references from the api-ref section will not work until this patch merges and the documents are rebuilt. Change-Id: Icd2d6c278050c263b833ae76545c041f54fae68d --- api-ref/source/parameters.yaml | 39 +++- api-ref/source/storage-account-services.inc | 10 +- doc/source/index.rst | 1 + doc/source/overview_acl.rst | 300 ++++++++++++++++++++++++++++ doc/source/overview_auth.rst | 134 ++++++------- 5 files changed, 400 insertions(+), 84 deletions(-) create mode 100644 doc/source/overview_acl.rst diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml index 23ab88a1a..52dccd6cf 100644 --- a/api-ref/source/parameters.yaml +++ b/api-ref/source/parameters.yaml @@ -259,6 +259,31 @@ Transfer-Encoding: in: header required: false type: string +X-Account-Access-Control_req: + description: | + **Note**: `X-Account-Access-Control` is not supported by Keystone auth. + + Sets an account access control list (ACL) that grants access to + containers and objects in the account. + See `Account ACLs + `_ + for more information. + in: header + required: false + type: string +X-Account-Access-Control_resp: + description: | + **Note**: `X-Account-Access-Control` is not supported by Keystone auth. + + The account access control list (ACL) that grants access to + containers and objects in the account. + If there is no ACL, this header is not returned by this operation. + See `Account ACLs + `_ + for more information. + in: header + required: false + type: string X-Account-Bytes-Used: description: | The total number of bytes that are stored in @@ -527,7 +552,9 @@ X-Container-Read: or to perform a GET or HEAD operation on the container itself. The format and scope of the ACL is dependent on the authorization system - used by the Object Storage service. + used by the Object Storage service. See `Container ACLs + `_ + for more information. in: header required: false type: string @@ -535,6 +562,9 @@ X-Container-Read_resp: description: | The ACL that grants read access. If there is no ACL, this header is not returned by this operation. + See `Container ACLs + `_ + for more information. in: header required: false type: string @@ -582,7 +612,9 @@ X-Container-Write: metadata. The format of the ACL is dependent on the authorization system - used by the Object Storage service. + used by the Object Storage service. See `Container ACLs + `_ + for more information. in: header required: false @@ -591,6 +623,9 @@ X-Container-Write_resp: description: The ACL that grants write access. If there is no ACL, this header is not returned by this operation. + See `Container ACLs + `_ + for more information. in: header required: false type: string diff --git a/api-ref/source/storage-account-services.inc b/api-ref/source/storage-account-services.inc index 8834c1a6d..b3c19b765 100644 --- a/api-ref/source/storage-account-services.inc +++ b/api-ref/source/storage-account-services.inc @@ -109,6 +109,7 @@ Response Parameters - X-Account-Storage-Policy-name-Container-Count: X-Account-Storage-Policy-name-Container-Count - X-Account-Storage-Policy-name-Object-Count: X-Account-Storage-Policy-name-Object-Count - X-Account-Meta-Quota-Bytes: X-Account-Meta-Quota-Bytes_resp + - X-Account-Access-Control: X-Account-Access-Control_resp - Content-Type: Content-Type_listing_resp - count: count - bytes: bytes @@ -257,6 +258,7 @@ Request - X-Account-Meta-Temp-URL-Key-2: X-Account-Meta-Temp-URL-Key-2_req - X-Account-Meta-name: X-Account-Meta-name_req - X-Remove-Account-name: X-Remove-Account-name + - X-Account-Access-Control: X-Account-Access-Control_req - X-Trans-Id-Extra: X-Trans-Id-Extra @@ -359,9 +361,5 @@ Response Parameters - X-Account-Storage-Policy-name-Container-Count: X-Account-Storage-Policy-name-Container-Count - X-Account-Storage-Policy-name-Object-Count: X-Account-Storage-Policy-name-Object-Count - X-Account-Meta-Quota-Bytes: X-Account-Meta-Quota-Bytes_resp - - Content-Type: Content-Type_cud_resp - - - - - + - X-Account-Access-Control: X-Account-Access-Control_resp + - Content-Type: Content-Type_cud_resp \ No newline at end of file diff --git a/doc/source/index.rst b/doc/source/index.rst index 3c96a60e7..27afd5b1f 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -48,6 +48,7 @@ Overview and Concepts overview_policies overview_reaper overview_auth + overview_acl overview_replication ratelimit overview_large_objects diff --git a/doc/source/overview_acl.rst b/doc/source/overview_acl.rst new file mode 100644 index 000000000..f8cc67b54 --- /dev/null +++ b/doc/source/overview_acl.rst @@ -0,0 +1,300 @@ + +=========================== +Access Control Lists (ACLs) +=========================== + +Normally to create, read and modify containers and objects, you must have the +appropriate roles on the project associated with the account, i.e., you +must be the owner of the account. However, an owner can grant access to +other users by using an Access Control List (ACL). + +There are two types of ACLs: + +- :ref:`container_acls`. These are specified on a container and + apply to that container only and the objects in the container. +- :ref:`account_acls`. These are specified at the account level and + apply to all containers and objects in the account. + +.. _container_acls: + +-------------- +Container ACLs +-------------- + +Container ACLs are stored in the ``X-Container-Write`` and ``X-Container-Read`` +metadata. The scope of the ACL is limited to the container where the +metadata is set and the objects in the container. In addition: + +- ``X-Container-Write`` grants the ability to perform PUT, POST and DELETE + operations on objects within a container. It does not grant the ability + to perform POST or DELETE operations on the container itself. Some ACL + elements also grant the ability to perform HEAD or GET operations on the + container. + +- ``X-Container-Read`` grants the ability to perform GET and HEAD + operations on objects within a container. Some of the ACL elements also grant + the ability to perform HEAD or GET operations on the container itself. + However, a container ACL does not allow access to privileged metadata (such + as ``X-Container-Sync-Key``). + +Container ACLs use the "V1" ACL syntax which is a comma separated string +of elements as shown in the following example:: + + .r:*,.rlistings,7ec59e87c6584c348b563254aae4c221:* + +Spaces may occur between elements as shown in the following example:: + + + .r : *, .rlistings, 7ec59e87c6584c348b563254aae4c221:* + +However, these spaces are removed from the value stored in the +``X-Container-Write`` and ``X-Container-Read`` metadata. In addition, +the ``.r:`` string can be written as ``.referrer:``, but is stored as ``.r:``. + +While all auth systems use +the same syntax, the meaning of some elements +is different because of the different concepts used by different +auth systems as explained in the following sections: + +- :ref:`acl_common_elements` +- :ref:`acl_keystone_elements` +- :ref:`acl_tempauth_elements` + + +.. _acl_common_elements: + +Common ACL Elements +------------------- + +The following table describes elements of an ACL that are +supported by both Keystone auth and TempAuth. These elements +should only be used with ``X-Container-Read`` (with the exception +of ``.rlistings``, an error will occur if used with +``X-Container-Write``): + +============================== ================================================ +Element Description +============================== ================================================ +``.r:*`` Any user has access to objects. No token is + required in the request. +``.r:`` The referrer is granted access to objects. The + referrer is identified by the ``Referer`` + request header in the request. No token is + required. +``.r:-`` This syntax (with "-" prepended to the + referrer) is supported. However, it does not + deny access if another element (e.g., ``.r:*``) + grants access. +``.rlistings`` Any user can perform a HEAD or GET operation + on the container provided the user also has + read access on objects (e.g., also has ``.r:*`` + or ``.r:``. No token is required. +============================== ================================================ + +.. _acl_keystone_elements: + +Keystone Auth ACL Elements +-------------------------- + +The following table describes elements of an ACL that are +supported only by Keystone auth. Keystone auth also supports +the elements described in :ref:`acl_common_elements`. + +A token must be included in the request for any of these ACL elements +to take effect. + +============================== ================================================ +Element Description +============================== ================================================ +``:`` The specified user, provided a token + scoped to the project is included + in the request, is granted access. + Access to the container is also granted + when used in ``X-Container-Read``. +``:*`` Any user with a role in the specified Keystone + project has access. A token scoped to the + project must be included in the request. + Access to the container is also granted + when used in ``X-Container-Read``. +``*:`` The specified user has access. A token + for the user (scoped to any + project) must be included in the request. + Access to the container is also granted + when used in ``X-Container-Read``. +``*:*`` Any user has access. + Access to the container is also granted + when used in ``X-Container-Read``. + The ``*:*`` element differs from the ``.r:*`` + element because + ``*:*`` requires that a valid token is + included in the request whereas ``.r:*`` + does not require a token. In addition, + ``.r:*`` does not grant access to the + container listing. +============================== ================================================ + +.. note:: + + Keystone project (tenant) or user *names* (i.e., + ``:`` The named user is granted access. The + wildcard ("*") character is not supported. + A token from the user must be included in the + request. +============================== ================================================ + +---------------------- +Container ACL Examples +---------------------- + +Container ACLs may be set by including ``X-Container-Write`` and/or +``X-Container-Read`` headers with a PUT or a POST request to the container URL. +The following examples use the ``swift`` command line client which support +these headers being set via its ``--write-acl`` and ``--read-acl`` options. + +Example: Public Container +------------------------- + +The following allows anybody to list objects in the ``www`` container and +download objects. The users do not need to include a token in +their request. This ACL is commonly referred to as making the +container "public". It is useful when used with :ref:`staticweb`:: + + swift post www --read-acl ".r:*,.rlistings" + + +Example: Shared Writable Container +---------------------------------- + +The following allows anybody to upload or download objects. However, to +download an object, the exact name of the object must be known since +users cannot list the objects in the container. +The users must include a Keystone token in the upload request. However, it does not +need to be scoped to the project associated with the container:: + + swift post www --read-acl ".r:*" --write-acl "*:*" + + +Example: Sharing a Container with Project Members +------------------------------------------------- + +The following allows any member of the ``77b8f82565f14814bece56e50c4c240f`` +project to upload and download objects or to list the contents +of the ``www`` container. A token scoped to the ``77b8f82565f14814bece56e50c4c240f`` +project must be included in the request:: + + swift post www --read-acl "77b8f82565f14814bece56e50c4c240f:*" \ + --write-acl "77b8f82565f14814bece56e50c4c240f:*" + + +Example: Allowing a Referrer Domain to Download Objects +------------------------------------------------------- + +The following allows any request from +the ``example.com`` domain to access an object in the container:: + + swift post www --read-acl ".r:.example.com" + +However, the request from the user **must** contain the appropriate +`Referer` header as shown in this example request:: + + curl -i $publicURL/www/document --head -H "Referer: http://www.example.com/index.html" + +.. note:: + + The `Referer` header is included in requests by many browsers. However, + since it is easy to create a request with any desired value in the + `Referer` header, the referrer ACL has very weak security. + + +.. _account_acls: + +------------ +Account ACLs +------------ + +.. note:: + + Account ACLs are not currently supported by Keystone auth + +The ``X-Account-Access-Control`` header is used to specify +account-level ACLs in a format specific to the auth system. +These headers are visible and settable only by account owners (those for whom +``swift_owner`` is true). +Behavior of account ACLs is auth-system-dependent. In the case of TempAuth, +if an authenticated user has membership in a group which is listed in the +ACL, then the user is allowed the access level of that ACL. + +Account ACLs use the "V2" ACL syntax, which is a JSON dictionary with keys +named "admin", "read-write", and "read-only". (Note the case sensitivity.) +An example value for the ``X-Account-Access-Control`` header looks like this, +where ``a``, ``b`` and ``c`` are user names:: + + {"admin":["a","b"],"read-only":["c"]} + +Keys may be absent (as shown in above example). + +The recommended way to generate ACL strings is as follows:: + + from swift.common.middleware.acl import format_acl + acl_data = { 'admin': ['alice'], 'read-write': ['bob', 'carol'] } + acl_string = format_acl(version=2, acl_dict=acl_data) + +Using the :func:`format_acl` method will ensure +that JSON is encoded as ASCII (using e.g. '\u1234' for Unicode). While +it's permissible to manually send ``curl`` commands containing +``X-Account-Access-Control`` headers, you should exercise caution when +doing so, due to the potential for human error. + +Within the JSON dictionary stored in ``X-Account-Access-Control``, the keys +have the following meanings: + +============ ============================================================== +Access Level Description +============ ============================================================== +read-only These identities can read *everything* (except privileged + headers) in the account. Specifically, a user with read-only + account access can get a list of containers in the account, + list the contents of any container, retrieve any object, and + see the (non-privileged) headers of the account, any + container, or any object. +read-write These identities can read or write (or create) any container. + A user with read-write account access can create new + containers, set any unprivileged container headers, overwrite + objects, delete containers, etc. A read-write user can NOT + set account headers (or perform any PUT/POST/DELETE requests + on the account). +admin These identities have "swift_owner" privileges. A user with + admin account access can do anything the account owner can, + including setting account headers and any privileged headers + -- and thus granting read-only, read-write, or admin access + to other users. +============ ============================================================== + + +For more details, see :mod:`swift.common.middleware.tempauth`. For details +on the ACL format, see :mod:`swift.common.middleware.acl`. \ No newline at end of file diff --git a/doc/source/overview_auth.rst b/doc/source/overview_auth.rst index e98526e7a..88bf550e4 100644 --- a/doc/source/overview_auth.rst +++ b/doc/source/overview_auth.rst @@ -3,12 +3,11 @@ The Auth System =============== -------- -TempAuth +Overview -------- -The auth system for Swift is loosely based on the auth system from the existing -Rackspace architecture -- actually from a few existing auth systems -- and is -therefore a bit disjointed. The distilled points about it are: +Swift supports a number of auth systems that share the following common +characteristics: * The authentication/authorization part can be an external system or a subsystem run within Swift as WSGI middleware @@ -26,91 +25,69 @@ validation. Swift will make calls to the auth system, giving the auth token to be validated. For a valid token, the auth system responds with an overall -expiration in seconds from now. Swift will cache the token up to the expiration +expiration time in seconds from now. To avoid the overhead in validating the same +token over and over again, Swift will cache the +token for a configurable time, but no longer than the expiration time. -The included TempAuth also has the concept of admin and non-admin users +The Swift project includes two auth systems: + +- :ref:`temp_auth` +- :ref:`keystone_auth` + +It is also possible to write your own auth system as described in +:ref:`extending_auth`. + +.. _temp_auth: + +-------- +TempAuth +-------- + +The included TempAuth has the concept of admin and non-admin users within an account. Admin users can do anything within the account. -Non-admin users can only perform operations per container based on the -container's X-Container-Read and X-Container-Write ACLs. Container ACLs -use the "V1" ACL syntax, which looks like this: -``name1, name2, .r:referrer1.com, .r:-bad.referrer1.com, .rlistings`` -For more information on ACLs, see :mod:`swift.common.middleware.acl`. - -Additionally, if the auth system sets the request environ's swift_owner key to -True, the proxy will return additional header information in some requests, -such as the X-Container-Sync-Key for a container GET or HEAD. - -In addition to container ACLs, TempAuth allows account-level ACLs. Any auth -system may use the special header ``X-Account-Access-Control`` to specify -account-level ACLs in a format specific to that auth system. (Following the -TempAuth format is strongly recommended.) These headers are visible and -settable only by account owners (those for whom ``swift_owner`` is true). -Behavior of account ACLs is auth-system-dependent. In the case of TempAuth, -if an authenticated user has membership in a group which is listed in the -ACL, then the user is allowed the access level of that ACL. - -Account ACLs use the "V2" ACL syntax, which is a JSON dictionary with keys -named "admin", "read-write", and "read-only". (Note the case sensitivity.) -An example value for the ``X-Account-Access-Control`` header looks like this: -``{"admin":["a","b"],"read-only":["c"]}`` Keys may be absent (as shown). -The recommended way to generate ACL strings is as follows:: - - from swift.common.middleware.acl import format_acl - acl_data = { 'admin': ['alice'], 'read-write': ['bob', 'carol'] } - acl_string = format_acl(version=2, acl_dict=acl_data) - -Using the :func:`format_acl` method will ensure -that JSON is encoded as ASCII (using e.g. '\u1234' for Unicode). While -it's permissible to manually send ``curl`` commands containing -``X-Account-Access-Control`` headers, you should exercise caution when -doing so, due to the potential for human error. - -Within the JSON dictionary stored in ``X-Account-Access-Control``, the keys -have the following meanings: - -============ ============================================================== -Access Level Description -============ ============================================================== -read-only These identities can read *everything* (except privileged - headers) in the account. Specifically, a user with read-only - account access can get a list of containers in the account, - list the contents of any container, retrieve any object, and - see the (non-privileged) headers of the account, any - container, or any object. -read-write These identities can read or write (or create) any container. - A user with read-write account access can create new - containers, set any unprivileged container headers, overwrite - objects, delete containers, etc. A read-write user can NOT - set account headers (or perform any PUT/POST/DELETE requests - on the account). -admin These identities have "swift_owner" privileges. A user with - admin account access can do anything the account owner can, - including setting account headers and any privileged headers - -- and thus granting read-only, read-write, or admin access - to other users. -============ ============================================================== - - -For more details, see :mod:`swift.common.middleware.tempauth`. For details -on the ACL format, see :mod:`swift.common.middleware.acl`. +Non-admin users can only perform read operations. However, some +privileged metadata such as X-Container-Sync-Key is not accessible to +non-admin users. Users with the special group ``.reseller_admin`` can operate on any account. For an example usage please see :mod:`swift.common.middleware.tempauth`. If a request is coming from a reseller the auth system sets the request environ reseller_request to True. This can be used by other middlewares. +Other users may be granted the ability to perform operations on +an account or container via ACLs. TempAuth supports two types of ACL: + +- Per container ACLs based on the + container's ``X-Container-Read`` and ``X-Container-Write`` metadata. See + :ref:`container_acls` for more information. + +- Per account ACLs based on the account's ``X-Account-Access-Control`` + metadata. For more information see :ref:`account_acls`. + TempAuth will now allow OPTIONS requests to go through without a token. -The user starts a session by sending a REST request to the auth system to -receive the auth token and a URL to the Swift system. +The TempAuth middleware is responsible for creating its own tokens. A user +makes a request containing their username and password and TempAuth +responds with a token. This token is then used to perform subsequent +requests on the user's account, containers and objects. + +.. _keystone_auth: ------------- Keystone Auth ------------- -Swift is able to authenticate against OpenStack Keystone_ via the -:ref:`keystoneauth` middleware. +Swift is able to authenticate against OpenStack Keystone_. In this +environment, Keystone is responsible for creating and validating +tokens. The :ref:`keystoneauth` middleware is responsible for +implementing the auth system within Swift as described here. + +The :ref:`keystoneauth` middleware supports per container based ACLs on the +container's ``X-Container-Read`` and ``X-Container-Write`` metadata. +For more information see :ref:`container_acls`. + +The account-level ACL is not supported by Keystone auth. In order to use the ``keystoneauth`` middleware the ``auth_token`` middleware from KeystoneMiddleware_ will need to be configured. @@ -383,13 +360,18 @@ keystone with Swift: If this ``openstack`` command fails then it is likely that there is a problem with the ``authtoken`` configuration. +.. _extending_auth: + -------------- Extending Auth -------------- TempAuth is written as wsgi middleware, so implementing your own auth is as easy as writing new wsgi middleware, and plugging it in to the proxy server. -The Keystone project and the Swauth project are examples of additional auth -services. +The `Swauth `_ project is an example of +an additional auth service. + +See :doc:`development_auth` for detailed information on extending the +auth system. + -Also, see :doc:`development_auth`. -- cgit v1.2.1