diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml index 8140c9fff9..b1ae69be51 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 @@ -528,7 +553,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 @@ -536,6 +563,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 @@ -583,7 +613,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 @@ -592,6 +624,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 8834c1a6db..b3c19b765c 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 3c96a60e76..27afd5b1f9 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 0000000000..f8cc67b54c --- /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 e98526e7ad..88bf550e49 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`.