From 03bf0c32a0c656d4b91bebedc87a005e6d7563bb Mon Sep 17 00:00:00 2001 From: WuKong Date: Wed, 1 Jul 2015 08:54:55 +0200 Subject: migrate openstack hook to opnfv Change-Id: I1e828dae38820fdff93966e57691b344af01140f Signed-off-by: WuKong --- keystonemiddleware-moon/doc/source/audit.rst | 81 ++++ keystonemiddleware-moon/doc/source/conf.py | 237 +++++++++++ .../doc/source/images/audit.png | Bin 0 -> 48742 bytes .../doc/source/images/graphs_authComp.svg | 48 +++ .../doc/source/images/graphs_authCompDelegate.svg | 53 +++ keystonemiddleware-moon/doc/source/index.rst | 46 +++ .../doc/source/middlewarearchitecture.rst | 459 +++++++++++++++++++++ 7 files changed, 924 insertions(+) create mode 100644 keystonemiddleware-moon/doc/source/audit.rst create mode 100644 keystonemiddleware-moon/doc/source/conf.py create mode 100644 keystonemiddleware-moon/doc/source/images/audit.png create mode 100644 keystonemiddleware-moon/doc/source/images/graphs_authComp.svg create mode 100644 keystonemiddleware-moon/doc/source/images/graphs_authCompDelegate.svg create mode 100644 keystonemiddleware-moon/doc/source/index.rst create mode 100644 keystonemiddleware-moon/doc/source/middlewarearchitecture.rst (limited to 'keystonemiddleware-moon/doc/source') diff --git a/keystonemiddleware-moon/doc/source/audit.rst b/keystonemiddleware-moon/doc/source/audit.rst new file mode 100644 index 00000000..d23f8168 --- /dev/null +++ b/keystonemiddleware-moon/doc/source/audit.rst @@ -0,0 +1,81 @@ +.. + Copyright 2014 IBM Corp + + 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. + +.. _middleware: + +================= + Audit middleware +================= + +The Keystone middleware library provides an optional WSGI middleware filter +which allows the ability to audit API requests for each component of OpenStack. + +The audit middleware filter utilises environment variables to build the CADF +event. + +.. figure:: ./images/audit.png + :width: 100% + :align: center + :alt: Figure 1: Audit middleware in Nova pipeline + +The figure above shows the middleware in Nova's pipeline. + +Enabling audit middleware +========================= +To enable auditing, oslo.messaging_ should be installed. If not, the middleware +will log the audit event instead. Auditing can be enabled for a specific +project by editing the project's api-paste.ini file to include the following +filter definition: + +:: + + [filter:audit] + paste.filter_factory = keystonemiddleware.audit:filter_factory + audit_map_file = /etc/nova/api_audit_map.conf + +The filter should be included after Keystone middleware's auth_token middleware +so it can utilise environment variables set by auth_token. Below is an example +using Nova's WSGI pipeline:: + + [composite:openstack_compute_api_v2] + use = call:nova.api.auth:pipeline_factory + noauth = faultwrap sizelimit noauth ratelimit osapi_compute_app_v2 + keystone = faultwrap sizelimit authtoken keystonecontext ratelimit audit osapi_compute_app_v2 + keystone_nolimit = faultwrap sizelimit authtoken keystonecontext audit osapi_compute_app_v2 + +.. _oslo.messaging: http://www.github.com/openstack/oslo.messaging + +Configure audit middleware +========================== +To properly audit api requests, the audit middleware requires an +api_audit_map.conf to be defined. The project's corresponding +api_audit_map.conf file is included in the `pyCADF library`_. + +The location of the mapping file should be specified explicitly by adding the +path to the 'audit_map_file' option of the filter definition:: + + [filter:audit] + paste.filter_factory = keystonemiddleware.audit:filter_factory + audit_map_file = /etc/nova/api_audit_map.conf + +Additional options can be set:: + + [filter:audit] + paste.filter_factory = pycadf.middleware.audit:filter_factory + audit_map_file = /etc/nova/api_audit_map.conf + service_name = test # opt to set HTTP_X_SERVICE_NAME environ variable + ignore_req_list = GET,POST # opt to ignore specific requests + +.. _pyCADF library: https://github.com/openstack/pycadf/tree/master/etc/pycadf diff --git a/keystonemiddleware-moon/doc/source/conf.py b/keystonemiddleware-moon/doc/source/conf.py new file mode 100644 index 00000000..069382be --- /dev/null +++ b/keystonemiddleware-moon/doc/source/conf.py @@ -0,0 +1,237 @@ +# -*- coding: utf-8 -*- +# +# keystonemiddleware documentation build configuration file, created by +# sphinx-quickstart on Sun Dec 6 14:19:25 2009. +# +# 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. + +from __future__ import unicode_literals + +import os +import sys + +import pbr.version + + +sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), + '..', '..'))) + +# NOTE(blk-u): Path for our Sphinx extension, remove when +# https://launchpad.net/bugs/1260495 is fixed. +sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), + '..'))) + + +# 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.append(os.path.abspath('.')) + +# -- General configuration ---------------------------------------------------- + +# 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.todo', + 'sphinx.ext.coverage', + 'sphinx.ext.intersphinx', + # NOTE(blk-u): Uncomment the [pbr] section in setup.cfg and + # remove this Sphinx extension when + # https://launchpad.net/bugs/1260495 is fixed. + 'ext.apidoc', + 'oslosphinx' + ] + +todo_include_todos = True + +# 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' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = 'keystonemiddleware' +copyright = 'OpenStack Contributors' + +# 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. +version_info = pbr.version.VersionInfo('keystonemiddleware') +# The short X.Y version. +version = version_info.version_string() +# The full version, including alpha/beta/rc tags. +release = version_info.release_string() + +# 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 documents that shouldn't be included in the build. +#unused_docs = [] + +# List of directories, relative to source directory, that shouldn't be searched +# for source files. +exclude_trees = [] + +# 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 = [] + +# Grouping the document tree for man pages. +# List of tuples 'sourcefile', 'target', 'title', 'Authors name', 'manual' + +man_pages = [] + +# -- Options for HTML output -------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. Major themes that come with +# Sphinx are currently 'default' and 'sphinxdoc'. +#html_theme_path = ["."] +#html_theme = '_theme' + +# 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 +# " v 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. +git_cmd = "git log --pretty=format:'%ad, commit %h' --date=local -n1" +html_last_updated_fmt = os.popen(git_cmd).read() + +# 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_use_modindex = 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, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = '' + +# Output file base name for HTML help builder. +htmlhelp_basename = 'keystonemiddlewaredoc' + + +# -- 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', 'keystonmiddleware.tex', + 'keystonemiddleware Documentation', + 'Nebula Inc, based on work by Rackspace and Jacob Kaplan-Moss', + '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 + +# 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_use_modindex = True + +keystoneclient = 'http://docs.openstack.org/developer/python-keystoneclient/' + +intersphinx_mapping = {'keystoneclient': (keystoneclient, None), + } diff --git a/keystonemiddleware-moon/doc/source/images/audit.png b/keystonemiddleware-moon/doc/source/images/audit.png new file mode 100644 index 00000000..5c2b1305 Binary files /dev/null and b/keystonemiddleware-moon/doc/source/images/audit.png differ diff --git a/keystonemiddleware-moon/doc/source/images/graphs_authComp.svg b/keystonemiddleware-moon/doc/source/images/graphs_authComp.svg new file mode 100644 index 00000000..6be629c1 --- /dev/null +++ b/keystonemiddleware-moon/doc/source/images/graphs_authComp.svg @@ -0,0 +1,48 @@ + + + + + + +AuthComp + + +AuthComp + +Auth +Component + + + +AuthComp->Reject + + +Reject +Unauthenticated +Requests + + +Service + +OpenStack +Service + + +AuthComp->Service + + +Forward +Authenticated +Requests + + + +Start->AuthComp + + + + + diff --git a/keystonemiddleware-moon/doc/source/images/graphs_authCompDelegate.svg b/keystonemiddleware-moon/doc/source/images/graphs_authCompDelegate.svg new file mode 100644 index 00000000..4788829a --- /dev/null +++ b/keystonemiddleware-moon/doc/source/images/graphs_authCompDelegate.svg @@ -0,0 +1,53 @@ + + + + + + +AuthCompDelegate + + +AuthComp + +Auth +Component + + + +AuthComp->Reject + + +Reject Requests +Indicated by the Service + + +Service + +OpenStack +Service + + +AuthComp->Service + + +Forward Requests +with Identiy Status + + +Service->AuthComp + + +Send Response OR +Reject Message + + + +Start->AuthComp + + + + + diff --git a/keystonemiddleware-moon/doc/source/index.rst b/keystonemiddleware-moon/doc/source/index.rst new file mode 100644 index 00000000..9092ec79 --- /dev/null +++ b/keystonemiddleware-moon/doc/source/index.rst @@ -0,0 +1,46 @@ +Python Middleware for OpenStack Identity API (Keystone) +======================================================= + +This is the middleware provided for integrating with the OpenStack +Identity API and handling authorization enforcement based upon the +data within the OpenStack Identity tokens. Also included is middleware that +provides the ability to create audit events based on API requests. + +Contents: + +.. toctree:: + :maxdepth: 1 + + middlewarearchitecture + audit + +Related Identity Projects +========================= + +In addition to creating the Python Middleware for OpenStack Identity +API, the Keystone team also provides `Identity Service`_, as well as +`Python Client Library`_. + +.. _`Identity Service`: http://docs.openstack.org/developer/keystone/ +.. _`Python Client Library`: http://docs.openstack.org/developer/python-keystoneclient/ + +Contributing +============ + +Code is hosted `on GitHub`_. Submit bugs to the Keystone project on +`Launchpad`_. Submit code to the ``openstack/keystonemiddleware`` project +using `Gerrit`_. + +.. _on GitHub: https://github.com/openstack/keystonemiddleware +.. _Launchpad: https://launchpad.net/keystonemiddleware +.. _Gerrit: http://docs.openstack.org/infra/manual/developers.html#development-workflow + +Run tests with ``python setup.py test``. + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + diff --git a/keystonemiddleware-moon/doc/source/middlewarearchitecture.rst b/keystonemiddleware-moon/doc/source/middlewarearchitecture.rst new file mode 100644 index 00000000..e02aad45 --- /dev/null +++ b/keystonemiddleware-moon/doc/source/middlewarearchitecture.rst @@ -0,0 +1,459 @@ +.. + Copyright 2011-2013 OpenStack Foundation + All Rights Reserved. + + 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. + +======================= +Middleware Architecture +======================= + +Abstract +======== + +The Keystone middleware architecture supports a common authentication protocol +in use between the OpenStack projects. By using keystone as a common +authentication and authorization mechanism, the OpenStack project can plug in +to existing authentication and authorization systems in use by existing +environments. + +In this document, we describe the architecture and responsibilities of the +authentication middleware which acts as the internal API mechanism for +OpenStack projects based on the WSGI standard. + +This documentation describes the implementation in +:class:`keystonemiddleware.auth_token` + +Specification Overview +====================== + +'Authentication' is the process of determining that users are who they say they +are. Typically, 'authentication protocols' such as HTTP Basic Auth, Digest +Access, public key, token, etc, are used to verify a user's identity. In this +document, we define an ''authentication component'' as a software module that +implements an authentication protocol for an OpenStack service. OpenStack is +using a token based mechanism to represent authentication and authorization. + +At a high level, an authentication middleware component is a proxy that +intercepts HTTP calls from clients and populates HTTP headers in the request +context for other WSGI middleware or applications to use. The general flow +of the middleware processing is: + +* clear any existing authorization headers to prevent forgery +* collect the token from the existing HTTP request headers +* validate the token + + * if valid, populate additional headers representing the identity that has + been authenticated and authorized + * if invalid, or no token present, reject the request (HTTPUnauthorized) + or pass along a header indicating the request is unauthorized (configurable + in the middleware) + * if the keystone service is unavailable to validate the token, reject + the request with HTTPServiceUnavailable. + +.. _authComponent: + +Authentication Component +------------------------ + +Figure 1. Authentication Component + +.. image:: images/graphs_authComp.svg + :width: 100% + :height: 180 + :alt: An Authentication Component + +The middleware may also be configured to operate in a 'delegated mode'. +In this mode, the decision to reject an unauthenticated client is delegated to +the OpenStack service, as illustrated in :ref:`authComponentDelegated`. + +Here, requests are forwarded to the OpenStack service with an identity status +message that indicates whether the client's identity has been confirmed or is +indeterminate. It is the OpenStack service that decides whether or not a reject +message should be sent to the client. + +.. _authComponentDelegated: + +Authentication Component (Delegated Mode) +----------------------------------------- + +Figure 2. Authentication Component (Delegated Mode) + +.. image:: images/graphs_authCompDelegate.svg + :width: 100% + :height: 180 + :alt: An Authentication Component (Delegated Mode) + +.. _deployStrategies: + +Deployment Strategy +=================== + +The middleware is intended to be used inline with OpenStack wsgi components, +based on the Oslo WSGI middleware class. It is typically deployed +as a configuration element in a paste configuration pipeline of other +middleware components, with the pipeline terminating in the service +application. The middleware conforms to the python WSGI standard [PEP-333]_. +In initializing the middleware, a configuration item (which acts like a python +dictionary) is passed to the middleware with relevant configuration options. + +Configuration +------------- + +The middleware is configured within the config file of the main application as +a WSGI component. Example for the auth_token middleware: + +.. code-block:: ini + + [app:myService] + paste.app_factory = myService:app_factory + + [pipeline:main] + pipeline = authtoken myService + + [filter:authtoken] + paste.filter_factory = keystonemiddleware.auth_token:filter_factory + + # Prefix to prepend at the beginning of the path (string + # value) + #auth_admin_prefix= + + # Host providing the admin Identity API endpoint (string + # value) + auth_host=127.0.0.1 + + # Port of the admin Identity API endpoint (integer value) + auth_port=35357 + + # Protocol of the admin Identity API endpoint(http or https) + # (string value) + auth_protocol=https + + # Complete public Identity API endpoint (string value) + #auth_uri= + + # API version of the admin Identity API endpoint (string + # value) + #auth_version= + + # Do not handle authorization requests within the middleware, + # but delegate the authorization decision to downstream WSGI + # components (boolean value) + #delay_auth_decision=false + + # Request timeout value for communicating with Identity API + # server. (boolean value) + #http_connect_timeout= + + # How many times are we trying to reconnect when communicating + # with Identity API Server. (integer value) + #http_request_max_retries=3 + + # Single shared secret with the Keystone configuration used + # for bootstrapping a Keystone installation, or otherwise + # bypassing the normal authentication process. (string value) + #admin_token= + + # Keystone account username (string value) + #admin_user= + + # Keystone account password (string value) + admin_password=SuperSekretPassword + + # Keystone service account tenant name to validate user tokens + # (string value) + #admin_tenant_name=admin + + # Env key for the swift cache (string value) + #cache= + + # Required if Keystone server requires client certificate + # (string value) + #certfile= + + # Required if Keystone server requires client certificate + # (string value) + #keyfile= + + # A PEM encoded Certificate Authority to use when verifying + # HTTPs connections. Defaults to system CAs. (string value) + #cafile= + + # Verify HTTPS connections. (boolean value) + #insecure=false + + # Directory used to cache files related to PKI tokens (string + # value) + #signing_dir= + + # If defined, the memcache server(s) to use for caching (list + # value) + # Deprecated group/name - [DEFAULT]/memcache_servers + #memcached_servers= + + # In order to prevent excessive requests and validations, the + # middleware uses an in-memory cache for the tokens the + # Keystone API returns. This is only valid if memcache_servers + # is defined. Set to -1 to disable caching completely. + # (integer value) + #token_cache_time=300 + + # Value only used for unit testing (integer value) + #revocation_cache_time=1 + + # (optional) if defined, indicate whether token data should be + # authenticated or authenticated and encrypted. Acceptable + # values are MAC or ENCRYPT. If MAC, token data is + # authenticated (with HMAC) in the cache. If ENCRYPT, token + # data is encrypted and authenticated in the cache. If the + # value is not one of these options or empty, auth_token will + # raise an exception on initialization. (string value) + #memcache_security_strategy= + + # (optional, mandatory if memcache_security_strategy is + # defined) this string is used for key derivation. (string + # value) + #memcache_secret_key= + + # (optional) indicate whether to set the X-Service-Catalog + # header. If False, middleware will not ask for service + # catalog on token validation and will not set the X-Service- + # Catalog header. (boolean value) + #include_service_catalog=true + + # Used to control the use and type of token binding. Can be + # set to: "disabled" to not check token binding. "permissive" + # (default) to validate binding information if the bind type + # is of a form known to the server and ignore it if not. + # "strict" like "permissive" but if the bind type is unknown + # the token will be rejected. "required" any form of token + # binding is needed to be allowed. Finally the name of a + # binding method that must be present in tokens. (string + # value) + #enforce_token_bind=permissive + +For services which have a separate paste-deploy ini file, auth_token middleware +can be alternatively configured in [keystone_authtoken] section in the main +config file. For example in Nova, all middleware parameters can be removed +from ``api-paste.ini``: + +.. code-block:: ini + + [filter:authtoken] + paste.filter_factory = keystonemiddleware.auth_token:filter_factory + +and set in ``nova.conf``: + +.. code-block:: ini + + [DEFAULT] + auth_strategy=keystone + + [keystone_authtoken] + auth_host = 127.0.0.1 + auth_port = 35357 + auth_protocol = http + admin_user = admin + admin_password = SuperSekretPassword + admin_tenant_name = service + # Any of the options that could be set in api-paste.ini can be set here. + +Note that middleware parameters in paste config take priority, they must be +removed to use values in [keystone_authtoken] section. + +Configuration Options +--------------------- + +* ``auth_admin_prefix``: Prefix to prepend at the beginning of the path +* ``auth_host``: (required) the host providing the keystone service API endpoint + for validating and requesting tokens +* ``auth_port``: (optional, default `35357`) the port used to validate tokens +* ``auth_protocol``: (optional, default `https`) +* ``auth_uri``: (optional, defaults to + `auth_protocol`://`auth_host`:`auth_port`) +* ``auth_version``: API version of the admin Identity API endpoint +* ``delay_auth_decision``: (optional, default `0`) (off). If on, the middleware + will not reject invalid auth requests, but will delegate that decision to + downstream WSGI components. +* ``http_connect_timeout``: (optional) Request timeout value for communicating + with Identity API server. +* ``http_request_max_retries``: (default 3) How many times are we trying to + reconnect when communicating with Identity API Server. +* ``http_handler``: (optional) Allows to pass in the name of a fake + http_handler callback function used instead of `httplib.HTTPConnection` or + `httplib.HTTPSConnection`. Useful for unit testing where network is not + available. + +* ``admin_token``: either this or the following three options are required. If + set, this is a single shared secret with the keystone configuration used to + validate tokens. +* ``admin_user``, ``admin_password``, ``admin_tenant_name``: if ``admin_token`` + is not set, or invalid, then admin_user, admin_password, and + admin_tenant_name are defined as a service account which is expected to have + been previously configured in Keystone to validate user tokens. + +* ``cache``: (optional) Env key for the swift cache + +* ``certfile``: (required, if Keystone server requires client cert) +* ``keyfile``: (required, if Keystone server requires client cert) This can be + the same as the certfile if the certfile includes the private key. +* ``cafile``: (optional, defaults to use system CA bundle) the path to a PEM + encoded CA file/bundle that will be used to verify HTTPS connections. +* ``insecure``: (optional, default `False`) Don't verify HTTPS connections + (overrides `cafile`). + +* ``signing_dir``: (optional) Directory used to cache files related to PKI + tokens + +* ``memcached_servers``: (optional) If defined, the memcache server(s) to use + for caching +* ``token_cache_time``: (default 300) In order to prevent excessive requests + and validations, the middleware uses an in-memory cache for the tokens the + Keystone API returns. This is only valid if memcache_servers s defined. Set + to -1 to disable caching completely. +* ``memcache_security_strategy``: (optional) if defined, indicate whether token + data should be authenticated or authenticated and encrypted. Acceptable + values are MAC or ENCRYPT. If MAC, token data is authenticated (with HMAC) + in the cache. If ENCRYPT, token data is encrypted and authenticated in the + cache. If the value is not one of these options or empty, auth_token will + raise an exception on initialization. +* ``memcache_secret_key``: (mandatory if memcache_security_strategy is defined) + this string is used for key derivation. +* ``include_service_catalog``: (optional, default `True`) Indicate whether to + set the X-Service-Catalog header. If False, middleware will not ask for + service catalog on token validation and will not set the X-Service-Catalog + header. +* ``enforce_token_bind``: (default ``permissive``) Used to control the use and + type of token binding. Can be set to: "disabled" to not check token binding. + "permissive" (default) to validate binding information if the bind type is of + a form known to the server and ignore it if not. "strict" like "permissive" + but if the bind type is unknown the token will be rejected. "required" any + form of token binding is needed to be allowed. Finally the name of a binding + method that must be present in tokens. + +Caching for improved response +----------------------------- + +In order to prevent excessive requests and validations, the middleware uses an +in-memory cache for the tokens the keystone API returns. Keep in mind that +invalidated tokens may continue to work if they are still in the token cache, +so token_cache_time is configurable. For larger deployments, the middleware +also supports memcache based caching. + +* ``memcached_servers``: (optonal) if defined, the memcache server(s) to use for + cacheing. It will be ignored if Swift MemcacheRing is used instead. +* ``token_cache_time``: (optional, default 300 seconds) Set to -1 to disable + caching completely. + +When deploying auth_token middleware with Swift, user may elect +to use Swift MemcacheRing instead of the local Keystone memcache. +The Swift MemcacheRing object is passed in from the request environment +and it defaults to 'swift.cache'. However it could be +different, depending on deployment. To use Swift MemcacheRing, you must +provide the ``cache`` option. + +* ``cache``: (optional) if defined, the environment key where the Swift + MemcacheRing object is stored. + +Memcached dependencies +====================== + +In order to use `memcached`_ it is necessary to install the `python-memcached`_ +library. If data stored in `memcached`_ will need to be encrypted it is also +necessary to install the `pycrypto`_ library. These libs are not listed in +the requirements.txt file. + +.. _`memcached`: http://memcached.org/ +.. _`python-memcached`: https://pypi.python.org/pypi/python-memcached +.. _`pycrypto`: https://pypi.python.org/pypi/pycrypto + +Memcached and System Time +========================= + +When using `memcached`_ with ``auth_token`` middleware, ensure that the system +time of memcached hosts is set to UTC. Memcached uses the host's system +time in determining whether a key has expired, whereas Keystone sets +key expiry in UTC. The timezone used by Keystone and memcached must +match if key expiry is to behave as expected. + +Memcache Protection +=================== + +When using memcached, we are storing user tokens and token validation +information into the cache as raw data. Which means that anyone who +has access to the memcache servers can read and modify data stored +there. To mitigate this risk, ``auth_token`` middleware provides an +option to authenticate and optionally encrypt the token data stored in +the cache. + +* ``memcache_security_strategy``: (optional) if defined, indicate + whether token data should be authenticated or authenticated and + encrypted. Acceptable values are ``MAC`` or ``ENCRYPT``. If ``MAC``, + token data is authenticated (with HMAC) in the cache. If + ``ENCRYPT``, token data is encrypted and authenticated in the + cache. If the value is not one of these options or empty, + ``auth_token`` will raise an exception on initialization. +* ``memcache_secret_key``: (optional, mandatory if + ``memcache_security_strategy`` is defined) this string is used for + key derivation. If ``memcache_security_strategy`` is defined and + ``memcache_secret_key`` is absent, ``auth_token`` will raise an + exception on initialization. + +Exchanging User Information +=========================== + +The middleware expects to find a token representing the user with the header +``X-Auth-Token`` or ``X-Storage-Token``. `X-Storage-Token` is supported for +swift/cloud files and for legacy Rackspace use. If the token isn't present and +the middleware is configured to not delegate auth responsibility, it will +respond to the HTTP request with HTTPUnauthorized, returning the header +``WWW-Authenticate`` with the value `Keystone uri='...'` to indicate where to +request a token. The auth_uri returned is configured with the middleware. + +The authentication middleware extends the HTTP request with the header +``X-Identity-Status``. If a request is successfully authenticated, the value +is set to `Confirmed`. If the middleware is delegating the auth decision to the +service, then the status is set to `Invalid` if the auth request was +unsuccessful. + +An ``X-Service-Token`` header may also be included with a request. If present, +and the value of ``X-Auth-Token`` or ``X-Storage-Token`` has not caused the +request to be denied, then the middleware will attempt to validate the value of +``X-Service-Token``. If valid, the authentication middleware extends the HTTP +request with the header ``X-Service-Identity-Status`` having value `Confirmed` +and also extends the request with additional headers representing the identity +authenticated and authorised by the token. + +If ``X-Service-Token`` is present and its value is invalid and the +``delay_auth_decision`` option is True then the value of +``X-Service-Identity-Status`` is set to `Invalid` and no further headers are +added. Otherwise if ``X-Service-Token`` is present and its value is invalid +then the middleware will respond to the HTTP request with HTTPUnauthorized, +regardless of the validity of the ``X-Auth-Token`` or ``X-Storage-Token`` +values. + +Extended the request with additional User Information +----------------------------------------------------- + +:py:class:`keystonemiddleware.auth_token.AuthProtocol` extends the +request with additional information if the user has been authenticated. See the +"What we add to the request for use by the OpenStack service" section in +:py:mod:`keystonemiddleware.auth_token` for the list of fields set by +the auth_token middleware. + + +References +========== + +.. [PEP-333] pep0333 Phillip J Eby. 'Python Web Server Gateway Interface + v1.0.'' http://www.python.org/dev/peps/pep-0333/. -- cgit 1.2.3-korg