diff options
Diffstat (limited to 'gluster/swift/common/middleware/gswauth/doc/source')
10 files changed, 1253 insertions, 0 deletions
diff --git a/gluster/swift/common/middleware/gswauth/doc/source/_static/.empty b/gluster/swift/common/middleware/gswauth/doc/source/_static/.empty new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/gluster/swift/common/middleware/gswauth/doc/source/_static/.empty diff --git a/gluster/swift/common/middleware/gswauth/doc/source/_templates/.empty b/gluster/swift/common/middleware/gswauth/doc/source/_templates/.empty new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/gluster/swift/common/middleware/gswauth/doc/source/_templates/.empty diff --git a/gluster/swift/common/middleware/gswauth/doc/source/api.rst b/gluster/swift/common/middleware/gswauth/doc/source/api.rst new file mode 100644 index 0000000..d2efa0f --- /dev/null +++ b/gluster/swift/common/middleware/gswauth/doc/source/api.rst @@ -0,0 +1,466 @@ +.. _api_top: + +---------- +Swauth API +---------- + +Overview +======== + +Swauth has its own internal versioned REST API for adding, removing, +and editing accounts. This document explains the v2 API. + +Authentication +-------------- + +Each REST request against the swauth API requires the inclusion of a +specific authorization user and key to be passed in a specific HTTP +header. These headers are defined as ``X-Auth-Admin-User`` and +``X-Auth-Admin-Key``. + +Typically, these values are ``.super_admin`` (the site super admin +user) with the key being specified in the swauth middleware +configuration as ``super_admin_key``. + +This could also be a reseller admin with the appropriate rights to +perform actions on reseller accounts. + +Endpoints +--------- + +The swauth API endpoint is presented on the proxy servers, in the +"/auth" namespace. In addition, the API is versioned, and the version +documented is version 2. API versions subdivide the auth namespace by +version, specified as a version identifier like "v2". + +The auth endpoint described herein is therefore located at "/auth/v2/" +as presented by the proxy servers. + +Bear in mind that in order for the auth management API to be +presented, it must be enabled in the proxy server config by setting +``allow_account_managment`` to ``true`` in the ``[app:proxy-server]`` +stanza of your proxy-server.conf. + +Responses +--------- + +Responses from the auth APIs are returned as a JSON structure. +Example return values in this document are edited for readability. + + +Reseller/Admin Services +======================= + +Operations can be performed against the endpoint itself to perform +general administrative operations. Currently, the only operations +that can be performed is a GET operation to get reseller or site admin +information. + +Get Admin Info +-------------- + +A GET request at the swauth endpoint will return reseller information +for the account specified in the ``X-Auth-Admin-User`` header. +Currently, the information returned is limited to a list of accounts +for the reseller or site admin. + +Valid return codes: + * 200: Success + * 403: Invalid X-Auth-Admin-User/X-Auth-Admin-Key + * 5xx: Internal error + +Example Request:: + + GET /auth/<api version>/ HTTP/1.1 + X-Auth-Admin-User: .super_admin + X-Auth-Admin-Key: swauthkey + +Example Curl Request:: + + curl -D - https://<endpoint>/auth/v2/ \ + -H "X-Auth-Admin-User: .super_admin" \ + -H "X-Auth-Admin-Key: swauthkey" + +Example Result:: + + HTTP/1.1 200 OK + + { "accounts": + [ + { "name": "account1" }, + { "name": "account2" }, + { "name": "account3" } + ] + } + + +Account Services +================ + +There are API request to get account details, create, and delete +accounts, mapping logically to the REST verbs GET, PUT, and DELETE. +These actions are performed against an account URI, in the following +general request structure:: + + METHOD /auth/<version>/<account> HTTP/1.1 + +The methods that can be used are detailed below. + +Get Account Details +------------------- + +Account details can be retrieved by performing a GET request against +an account URI. On success, a JSON dictionary will be returned +containing the keys `account_id`, `services`, and `users`. The +`account_id` is the value used when creating service accounts. The +`services` value is a dict that represents valid storage cluster +endpoints, and which endpoint is the default. The 'users' value is a +list of dicts, each dict representing a user and currently only +containing the single key 'name'. + +Valid Responses: + * 200: Success + * 403: Invalid X-Auth-Admin-User/X-Auth-Admin-Key + * 5xx: Internal error + +Example Request:: + + GET /auth/<api version>/<account> HTTP/1.1 + X-Auth-Admin-User: .super_admin + X-Auth-Admin-Key: swauthkey + +Example Curl Request:: + + curl -D - https://<endpoint>/auth/v2/<account> \ + -H "X-Auth-Admin-User: .super_admin" \ + -H "X-Auth-Admin-Key: swauthkey" + +Example Response:: + + HTTP/1.1 200 OK + + { "services": + { "storage": + { "default": "local", + "local": "https://<storage endpoint>/v1/<account_id>" }, + }, + "account_id": "<account_id>", + "users": [ { "name": "user1" }, + { "name": "user2" } ] + } + +Create Account +-------------- + +An account can be created with a PUT request against a non-existent +account. By default, a newly created UUID4 will be used with the +reseller prefix as the account ID used when creating corresponding +service accounts. However, you can provide an X-Account-Suffix header +to replace the UUDI4 part. + +Valid return codes: + * 200: Success + * 403: Invalid X-Auth-Admin-User/X-Auth-Admin-Key + * 5xx: Internal error + +Example Request:: + + GET /auth/<api version>/<new_account> HTTP/1.1 + X-Auth-Admin-User: .super_admin + X-Auth-Admin-Key: swauthkey + +Example Curl Request:: + + curl -D - https://<endpoint>/auth/v2/<new_account> \ + -H "X-Auth-Admin-User: .super_admin" \ + -H "X-Auth-Admin-Key: swauthkey" + +Example Response:: + + HTTP/1.1 201 Created + + +Delete Account +-------------- + +An account can be deleted with a DELETE request against an existing +account. + +Valid Responses: + * 204: Success + * 403: Invalid X-Auth-Admin-User/X-Auth-Admin-Key + * 404: Account not found + * 5xx: Internal error + +Example Request:: + + DELETE /auth/<api version>/<account> HTTP/1.1 + X-Auth-Admin-User: .super_admin + X-Auth-Admin-Key: swauthkey + +Example Curl Request:: + + curl -XDELETE -D - https://<endpoint>/auth/v2/<account> \ + -H "X-Auth-Admin-User: .super_admin" \ + -H "X-Auth-Admin-Key: swauthkey" + +Example Response:: + + HTTP/1.1 204 No Content + + +User Services +============= + +Each account in swauth contains zero or more users. These users can +be determined with the 'Get Account Details' API request against an +account. + +Users in an account can be created, modified, and detailed as +described below by apply the appropriate REST verbs to a user URI, in +the following general request structure:: + + METHOD /auth/<version>/<account>/<user> HTTP/1.1 + +The methods that can be used are detailed below. + +Get User Details +---------------- + +User details can be retrieved by performing a GET request against +a user URI. On success, a JSON dictionary will be returned as +described:: + + {"groups": [ # List of groups the user is a member of + {"name": "<act>:<usr>"}, + # The first group is a unique user identifier + {"name": "<account>"}, + # The second group is the auth account name + {"name": "<additional-group>"} + # There may be additional groups, .admin being a + # special group indicating an account admin and + # .reseller_admin indicating a reseller admin. + ], + "auth": "<auth-type>:<key>" + # The auth-type and key for the user; currently only + # plaintext and sha1 are implemented as auth types. + } + +For example:: + + {"groups": [{"name": "test:tester"}, {"name": "test"}, + {"name": ".admin"}], + "auth": "plaintext:testing"} + +Valid Responses: + * 200: Success + * 403: Invalid X-Auth-Admin-User/X-Auth-Admin-Key + * 404: Unknown account + * 5xx: Internal error + +Example Request:: + + GET /auth/<api version>/<account>/<user> HTTP/1.1 + X-Auth-Admin-User: .super_admin + X-Auth-Admin-Key: swauthkey + +Example Curl Request:: + + curl -D - https://<endpoint>/auth/v2/<account>/<user> \ + -H "X-Auth-Admin-User: .super_admin" \ + -H "X-Auth-Admin-Key: swauthkey" + +Example Response:: + + HTTP/1.1 200 Ok + + { "groups": [ { "name": "<account>:<user>" }, + { "name": "<user>" }, + { "name": ".admin" } ], + "auth" : "plaintext:password" } + + +Create User +----------- + +A user can be created with a PUT request against a non-existent +user URI. The new user's password must be set using the +``X-Auth-User-Key`` header. The user name MUST NOT start with a +period ('.'). This requirement is enforced by the API, and will +result in a 400 error. + +Optional Headers: + + * ``X-Auth-User-Admin: true``: create the user as an account admin + * ``X-Auth-User-Reseller-Admin: true``: create the user as a reseller + admin + +Reseller admin accounts can only be created by the site admin, while +regular accounts (or account admin accounts) can be created by an +account admin, an appropriate reseller admin, or the site admin. + +Note that PUT requests are idempotent, and the PUT request serves as +both a request and modify action. + +Valid Responses: + * 200: Success + * 400: Invalid request (missing required headers) + * 403: Invalid X-Auth-Admin-User/X-Auth-Admin-Key, or insufficient priv + * 404: Unknown account + * 5xx: Internal error + +Example Request:: + + PUT /auth/<api version>/<account>/<user> HTTP/1.1 + X-Auth-Admin-User: .super_admin + X-Auth-Admin-Key: swauthkey + X-Auth-User-Admin: true + X-Auth-User-Key: secret + +Example Curl Request:: + + curl -XPUT -D - https://<endpoint>/auth/v2/<account>/<user> \ + -H "X-Auth-Admin-User: .super_admin" \ + -H "X-Auth-Admin-Key: swauthkey" \ + -H "X-Auth-User-Admin: true" \ + -H "X-Auth-User-Key: secret" + +Example Response:: + + HTTP/1.1 201 Created + +Delete User +----------- + +A user can be deleted by performing a DELETE request against a user +URI. This action can only be performed by an account admin, +appropriate reseller admin, or site admin. + +Valid Responses: + * 200: Success + * 403: Invalid X-Auth-Admin-User/X-Auth-Admin-Key, or insufficient priv + * 404: Unknown account or user + * 5xx: Internal error + +Example Request:: + + DELETE /auth/<api version>/<account>/<user> HTTP/1.1 + X-Auth-Admin-User: .super_admin + X-Auth-Admin-Key: swauthkey + +Example Curl Request:: + + curl -XDELETE -D - https://<endpoint>/auth/v2/<account>/<user> \ + -H "X-Auth-Admin-User: .super_admin" \ + -H "X-Auth-Admin-Key: swauthkey" + +Example Response:: + + HTTP/1.1 204 No Content + + +Other Services +============== + +There are several other swauth functions that can be performed, mostly +done via "pseudo-user" accounts. These are well-known user names that +are unable to be actually provisioned. These pseudo-users are +described below. + +.. _api_set_service_endpoints: + +Set Service Endpoints +--------------------- + +Service endpoint information can be retrived using the _`Get Account +Details` API method. + +This function allows setting values within this section for +the <account>, allowing the addition of new service end points +or updating existing ones by performing a POST to the URI +corresponding to the pseudo-user ".services". + +The body of the POST request should contain a JSON dict with +the following format:: + + {"service_name": {"end_point_name": "end_point_value"}} + +There can be multiple services and multiple end points in the +same call. + +Any new services or end points will be added to the existing +set of services and end points. Any existing services with the +same service name will be merged with the new end points. Any +existing end points with the same end point name will have +their values updated. + +The updated services dictionary will be returned on success. + +Valid Responses: + + * 200: Success + * 403: Invalid X-Auth-Admin-User/X-Auth-Admin-Key + * 404: Account not found + * 5xx: Internal error + +Example Request:: + + POST /auth/<api version>/<account>/.services HTTP/1.0 + X-Auth-Admin-User: .super_admin + X-Auth-Admin-Key: swauthkey + + {"storage": { "local": "<new endpoint>" }} + +Example Curl Request:: + + curl -XPOST -D - https://<endpoint>/auth/v2/<account>/.services \ + -H "X-Auth-Admin-User: .super_admin" \ + -H "X-Auth-Admin-Key: swauthkey" --data-binary \ + '{ "storage": { "local": "<new endpoint>" }}' + +Example Response:: + + HTTP/1.1 200 OK + + {"storage": {"default": "local", "local": "<new endpoint>" }} + +Get Account Groups +------------------ + +Individual user group information can be retrieved using the `Get User Details`_ API method. + +This function allows retrieving all group information for all users in +an existing account. This can be achieved using a GET action against +a user URI with the pseudo-user ".groups". + +The JSON dictionary returned will be a "groups" dictionary similar to +that documented in the `Get User Details`_ method, but representing +the summary of all groups utilized by all active users in the account. + +Valid Responses: + * 200: Success + * 403: Invalid X-Auth-Admin-User/X-Auth-Admin-Key + * 404: Account not found + * 5xx: Internal error + +Example Request:: + + GET /auth/<api version>/<account>/.groups + X-Auth-Admin-User: .super_admin + X-Auth-Admin-Key: swauthkey + +Example Curl Request:: + + curl -D - https://<endpoint>/auth/v2/<account>/.groups \ + -H "X-Auth-Admin-User: .super_admin" \ + -H "X-Auth-Admin-Key: swauthkey" + +Example Response:: + + HTTP/1.1 200 OK + + { "groups": [ { "name": ".admin" }, + { "name": "<account>" }, + { "name": "<account>:user1" }, + { "name": "<account>:user2" } ] } + diff --git a/gluster/swift/common/middleware/gswauth/doc/source/authtypes.rst b/gluster/swift/common/middleware/gswauth/doc/source/authtypes.rst new file mode 100644 index 0000000..a19ee22 --- /dev/null +++ b/gluster/swift/common/middleware/gswauth/doc/source/authtypes.rst @@ -0,0 +1,10 @@ +.. _swauth_authtypes_module: + +swauth.authtypes +================= + +.. automodule:: swauth.authtypes + :members: + :undoc-members: + :show-inheritance: + :noindex: diff --git a/gluster/swift/common/middleware/gswauth/doc/source/conf.py b/gluster/swift/common/middleware/gswauth/doc/source/conf.py new file mode 100644 index 0000000..ab0645a --- /dev/null +++ b/gluster/swift/common/middleware/gswauth/doc/source/conf.py @@ -0,0 +1,233 @@ +# -*- coding: utf-8 -*- +# Copyright (c) 2010-2011 OpenStack, LLC. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or +# implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +# +# Swauth documentation build configuration file, created by +# sphinx-quickstart on Mon Feb 14 19:34:51 2011. +# +# This file is execfile()d with the current directory set to its containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys, os + +import swauth + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +#sys.path.insert(0, os.path.abspath('.')) + +# -- General configuration ----------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be extensions +# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode'] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'Swauth' +copyright = u'2010-2011, OpenStack, LLC' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '.'.join(str(v) for v in swauth.version_info[:2]) +# The full version, including alpha/beta/rc tags. +release = swauth.version + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +#language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = [] + +# The reST default role (used for this markup: `text`) to use for all documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + + +# -- Options for HTML output --------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'default' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# "<project> v<release> documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a <link> tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = 'Swauthdoc' + + +# -- Options for LaTeX output -------------------------------------------------- + +# The paper size ('letter' or 'a4'). +#latex_paper_size = 'letter' + +# The font size ('10pt', '11pt' or '12pt'). +#latex_font_size = '10pt' + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass [howto/manual]). +latex_documents = [ + ('index', 'Swauth.tex', u'Swauth Documentation', + u'OpenStack, LLC', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Additional stuff for the LaTeX preamble. +#latex_preamble = '' + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output -------------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('index', 'swauth', u'Swauth Documentation', + [u'OpenStack, LLC'], 1) +] diff --git a/gluster/swift/common/middleware/gswauth/doc/source/details.rst b/gluster/swift/common/middleware/gswauth/doc/source/details.rst new file mode 100644 index 0000000..3b14ad8 --- /dev/null +++ b/gluster/swift/common/middleware/gswauth/doc/source/details.rst @@ -0,0 +1,159 @@ +---------------------- +Implementation Details +---------------------- + +The Swauth system is a scalable authentication and authorization system that +uses Swift itself as its backing store. This section will describe how it +stores its data. + +.. note:: + + You can access Swauth's internal .auth account by using the account:user of + .super_admin:.super_admin and the super admin key you have set in your + configuration. Here's an example using `st` on a standard SAIO: ``st -A + http://127.0.0.1:8080/auth/v1.0 -U .super_admin:.super_admin -K swauthkey + stat`` + +At the topmost level, the auth system has its own Swift account it stores its +own account information within. This Swift account is known as +self.auth_account in the code and its name is in the format +self.reseller_prefix + ".auth". In this text, we'll refer to this account as +<auth_account>. + +The containers whose names do not begin with a period represent the accounts +within the auth service. For example, the <auth_account>/test container would +represent the "test" account. + +The objects within each container represent the users for that auth service +account. For example, the <auth_account>/test/bob object would represent the +user "bob" within the auth service account of "test". Each of these user +objects contain a JSON dictionary of the format:: + + {"auth": "<auth_type>:<auth_value>", "groups": <groups_array>} + +The `<auth_type>` specifies how the user key is encoded. The default is `plaintext`, +which saves the user's key in plaintext in the `<auth_value>` field. +The value `sha1` is supported as well, which stores the user's key as a salted +SHA1 hash. Note that using a one-way hash like SHA1 will likely inhibit future use of key-signing request types, assuming such support is added. The `<auth_type>` can be specified in the swauth section of the proxy server's +config file, along with the salt value in the following way:: + + auth_type = <auth_type> + auth_type_salt = <salt-value> + +Both fields are optional. auth_type defaults to `plaintext` and auth_type_salt defaults to "swauthsalt". Additional auth types can be implemented along with existing ones in the authtypes.py module. + +The `<groups_array>` contains at least two groups. The first is a unique group +identifying that user and it's name is of the format `<user>:<account>`. The +second group is the `<account>` itself. Additional groups of `.admin` for +account administrators and `.reseller_admin` for reseller administrators may +exist. Here's an example user JSON dictionary:: + + {"auth": "plaintext:testing", + "groups": ["name": "test:tester", "name": "test", "name": ".admin"]} + +To map an auth service account to a Swift storage account, the Service Account +Id string is stored in the `X-Container-Meta-Account-Id` header for the +<auth_account>/<account> container. To map back the other way, an +<auth_account>/.account_id/<account_id> object is created with the contents of +the corresponding auth service's account name. + +Also, to support a future where the auth service will support multiple Swift +clusters or even multiple services for the same auth service account, an +<auth_account>/<account>/.services object is created with its contents having a +JSON dictionary of the format:: + + {"storage": {"default": "local", "local": <url>}} + +The "default" is always "local" right now, and "local" is always the single +Swift cluster URL; but in the future there can be more than one cluster with +various names instead of just "local", and the "default" key's value will +contain the primary cluster to use for that account. Also, there may be more +services in addition to the current "storage" service right now. + +Here's an example .services dictionary at the moment:: + + {"storage": + {"default": "local", + "local": "http://127.0.0.1:8080/v1/AUTH_8980f74b1cda41e483cbe0a925f448a9"}} + +But, here's an example of what the dictionary may look like in the future:: + + {"storage": + {"default": "dfw", + "dfw": "http://dfw.storage.com:8080/v1/AUTH_8980f74b1cda41e483cbe0a925f448a9", + "ord": "http://ord.storage.com:8080/v1/AUTH_8980f74b1cda41e483cbe0a925f448a9", + "sat": "http://ord.storage.com:8080/v1/AUTH_8980f74b1cda41e483cbe0a925f448a9"}, + "servers": + {"default": "dfw", + "dfw": "http://dfw.servers.com:8080/v1/AUTH_8980f74b1cda41e483cbe0a925f448a9", + "ord": "http://ord.servers.com:8080/v1/AUTH_8980f74b1cda41e483cbe0a925f448a9", + "sat": "http://ord.servers.com:8080/v1/AUTH_8980f74b1cda41e483cbe0a925f448a9"}} + +Lastly, the tokens themselves are stored as objects in the +`<auth_account>/.token_[0-f]` containers. The names of the objects are the +token strings themselves, such as `AUTH_tked86bbd01864458aa2bd746879438d5a`. +The exact `.token_[0-f]` container chosen is based on the final digit of the +token name, such as `.token_a` for the token +`AUTH_tked86bbd01864458aa2bd746879438d5a`. The contents of the token objects +are JSON dictionaries of the format:: + + {"account": <account>, + "user": <user>, + "account_id": <account_id>, + "groups": <groups_array>, + "expires": <time.time() value>} + +The `<account>` is the auth service account's name for that token. The `<user>` +is the user within the account for that token. The `<account_id>` is the +same as the `X-Container-Meta-Account-Id` for the auth service's account, +as described above. The `<groups_array>` is the user's groups, as described +above with the user object. The "expires" value indicates when the token is no +longer valid, as compared to Python's time.time() value. + +Here's an example token object's JSON dictionary:: + + {"account": "test", + "user": "tester", + "account_id": "AUTH_8980f74b1cda41e483cbe0a925f448a9", + "groups": ["name": "test:tester", "name": "test", "name": ".admin"], + "expires": 1291273147.1624689} + +To easily map a user to an already issued token, the token name is stored in +the user object's `X-Object-Meta-Auth-Token` header. + +Here is an example full listing of an <auth_account>:: + + .account_id + AUTH_2282f516-559f-4966-b239-b5c88829e927 + AUTH_f6f57a3c-33b5-4e85-95a5-a801e67505c8 + AUTH_fea96a36-c177-4ca4-8c7e-b8c715d9d37b + .token_0 + .token_1 + .token_2 + .token_3 + .token_4 + .token_5 + .token_6 + AUTH_tk9d2941b13d524b268367116ef956dee6 + .token_7 + .token_8 + AUTH_tk93627c6324c64f78be746f1e6a4e3f98 + .token_9 + .token_a + .token_b + .token_c + .token_d + .token_e + AUTH_tk0d37d286af2c43ffad06e99112b3ec4e + .token_f + AUTH_tk766bbde93771489982d8dc76979d11cf + reseller + .services + reseller + test + .services + tester + tester3 + test2 + .services + tester2 diff --git a/gluster/swift/common/middleware/gswauth/doc/source/index.rst b/gluster/swift/common/middleware/gswauth/doc/source/index.rst new file mode 100644 index 0000000..87b22d5 --- /dev/null +++ b/gluster/swift/common/middleware/gswauth/doc/source/index.rst @@ -0,0 +1,142 @@ +.. Swauth documentation master file, created by + sphinx-quickstart on Mon Feb 14 19:34:51 2011. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Swauth +====== + + Copyright (c) 2010-2012 OpenStack, LLC + + An Auth Service for Swift as WSGI Middleware that uses Swift itself as a + backing store. Sphinx-built docs at: http://gholt.github.com/swauth/ + Source available at: https://github.com/gholt/swauth + + See also https://github.com/openstack/keystone for the standard OpenStack + auth service. + +Overview +-------- + +Before discussing how to install Swauth within a Swift system, it might help to understand how Swauth does it work first. + +1. Swauth is middleware installed in the Swift Proxy's WSGI pipeline. + +2. It intercepts requests to ``/auth/`` (by default). + +3. It also uses Swift's `authorize callback <http://swift.openstack.org/development_auth.html>`_ and `acl callback <http://swift.openstack.org/misc.html#module-swift.common.middleware.acl>`_ features to authorize Swift requests. + +4. Swauth will also make various internal calls to the Swift WSGI pipeline it's installed in to manipulate containers and objects within an ``AUTH_.auth`` (by default) Swift account. These containers and objects are what store account and user information. + +5. Instead of #4, Swauth can be configured to call out to another remote Swauth to perform #4 on its behalf (using the swauth_remote config value). + +6. When managing accounts and users with the various ``swauth-`` command line tools, these tools are actually just performing HTTP requests against the ``/auth/`` end point referenced in #2. You can make your own tools that use the same :ref:`API <api_top>`. + +7. In the special case of creating a new account, Swauth will do its usual WSGI-internal requests as per #4 but will also call out to the Swift cluster to create the actual Swift account. + + a. This Swift cluster callout is an account PUT request to the URL defined by the ``swift_default_cluster`` config value. + + b. This callout end point is also saved when the account is created so that it can be given to the users of that account in the future. + + c. Sometimes, due to public/private network routing or firewalling, the URL Swauth should use should be different than the URL Swauth should give the users later. That is why the ``default_swift_cluster`` config value can accept two URLs (first is the one for users, second is the one for Swauth). + + d. Once an account is created, the URL given to users for that account will not change, even if the ``default_swift_cluster`` config value changes. This is so that you can use multiple clusters with the same Swauth system; ``default_swift_cluster`` just points to the one where you want new users to go. + + f. You can change the stored URL for an account if need be with the ``swauth-set-account-service`` command line tool or a POST request (see :ref:`API <api_set_service_endpoints>`). + + +Install +------- + +1) Install Swauth with ``sudo python setup.py install`` or ``sudo python + setup.py develop`` or via whatever packaging system you may be using. + +2) Alter your ``proxy-server.conf`` pipeline to have ``swauth`` instead of ``tempauth``: + + Was:: + + [pipeline:main] + pipeline = catch_errors cache tempauth proxy-server + + Change To:: + + [pipeline:main] + pipeline = catch_errors cache swauth proxy-server + +3) Add to your ``proxy-server.conf`` the section for the Swauth WSGI filter:: + + [filter:swauth] + use = egg:swauth#swauth + set log_name = swauth + super_admin_key = swauthkey + default_swift_cluster = <your setting as discussed below> + + The ``default_swift_cluster`` setting can be confusing. + + a. If you're using an all-in-one type configuration where everything will be run on the local host on port 8080, you can omit the ``default_swift_cluster`` completely and it will default to ``local#http://127.0.0.1:8080/v1``. + + b. If you're using a single Swift proxy you can just set the ``default_swift_cluster = cluster_name#https://<public_ip>:<port>/v1`` and that URL will be given to users as well as used by Swauth internally. (Quick note: be sure the ``http`` vs. ``https`` is set right depending on if you're using SSL.) + + c. If you're using multiple Swift proxies behind a load balancer, you'll probably want ``default_swift_cluster = cluster_name#https://<load_balancer_ip>:<port>/v1#http://127.0.0.1:<port>/v1`` so that Swauth gives out the first URL but uses the second URL internally. Remember to double-check the ``http`` vs. ``https`` settings for each of the URLs; they might be different if you're terminating SSL at the load balancer. + + Also see the ``proxy-server.conf-sample`` for more config options, such as the ability to have a remote Swauth in a multiple Swift cluster configuration. + +4) Be sure your Swift proxy allows account management in the ``proxy-server.conf``:: + + [app:proxy-server] + ... + allow_account_management = true + + For greater security, you can leave this off any public proxies and just have one or two private proxies with it turned on. + +5) Restart your proxy server ``swift-init proxy reload`` + +6) Initialize the Swauth backing store in Swift ``swauth-prep -K swauthkey`` + +7) Add an account/user ``swauth-add-user -A http[s]://<host>:<port>/auth/ -K + swauthkey -a test tester testing`` + +8) Ensure it works ``swift -A http[s]://<host>:<port>/auth/v1.0 -U test:tester -K testing stat -v`` + + +If anything goes wrong, it's best to start checking the proxy server logs. The client command line utilities often don't get enough information to help. I will often just ``tail -F`` the appropriate proxy log (``/var/log/syslog`` or however you have it configured) and then run the Swauth command to see exactly what requests are happening to try to determine where things fail. + +General note, I find I occasionally just forget to reload the proxies after a config change; so that's the first thing you might try. Or, if you suspect the proxies aren't reloading properly, you might try ``swift-init proxy stop``, ensure all the processes died, then ``swift-init proxy start``. + +Also, it's quite common to get the ``/auth/v1.0`` vs. just ``/auth/`` URL paths confused. Usual rule is: Swauth tools use just ``/auth/`` and Swift tools use ``/auth/v1.0``. + + +Web Admin Install +----------------- + +1) If you installed from packages, you'll need to cd to the webadmin directory + the package installed. This is ``/usr/share/doc/python-swauth/webadmin`` + with the Lucid packages. If you installed from source, you'll need to cd to + the webadmin directory in the source directory. + +2) Upload the Web Admin files with ``swift -A http[s]://<host>:<port>/auth/v1.0 + -U .super_admin:.super_admin -K swauthkey upload .webadmin .`` + +3) Open ``http[s]://<host>:<port>/auth/`` in your browser. + + +Contents +-------- + +.. toctree:: + :maxdepth: 2 + + license + details + swauth + middleware + api + authtypes + + +Indices and tables +------------------ + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/gluster/swift/common/middleware/gswauth/doc/source/license.rst b/gluster/swift/common/middleware/gswauth/doc/source/license.rst new file mode 100644 index 0000000..590a9b4 --- /dev/null +++ b/gluster/swift/common/middleware/gswauth/doc/source/license.rst @@ -0,0 +1,225 @@ +.. _license: + +******* +LICENSE +******* + +:: + + Copyright (c) 2010-2011 OpenStack, LLC + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied. + See the License for the specific language governing permissions and + limitations under the License. + + + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/gluster/swift/common/middleware/gswauth/doc/source/middleware.rst b/gluster/swift/common/middleware/gswauth/doc/source/middleware.rst new file mode 100644 index 0000000..a25acd4 --- /dev/null +++ b/gluster/swift/common/middleware/gswauth/doc/source/middleware.rst @@ -0,0 +1,9 @@ +.. _swauth_middleware_module: + +swauth.middleware +================= + +.. automodule:: swauth.middleware + :members: + :undoc-members: + :show-inheritance: diff --git a/gluster/swift/common/middleware/gswauth/doc/source/swauth.rst b/gluster/swift/common/middleware/gswauth/doc/source/swauth.rst new file mode 100644 index 0000000..c50c350 --- /dev/null +++ b/gluster/swift/common/middleware/gswauth/doc/source/swauth.rst @@ -0,0 +1,9 @@ +.. _swauth_module: + +swauth +====== + +.. automodule:: swauth + :members: + :undoc-members: + :show-inheritance: |