diff options
Diffstat (limited to 'keystonemiddleware-moon/doc/source')
| -rw-r--r-- | keystonemiddleware-moon/doc/source/audit.rst | 81 | ||||
| -rw-r--r-- | keystonemiddleware-moon/doc/source/conf.py | 237 | ||||
| -rw-r--r-- | keystonemiddleware-moon/doc/source/images/audit.png | bin | 0 -> 48742 bytes | |||
| -rw-r--r-- | keystonemiddleware-moon/doc/source/images/graphs_authComp.svg | 48 | ||||
| -rw-r--r-- | keystonemiddleware-moon/doc/source/images/graphs_authCompDelegate.svg | 53 | ||||
| -rw-r--r-- | keystonemiddleware-moon/doc/source/index.rst | 46 | ||||
| -rw-r--r-- | keystonemiddleware-moon/doc/source/middlewarearchitecture.rst | 459 |
7 files changed, 924 insertions, 0 deletions
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 +# "<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. +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 <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 = '' + +# 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 Binary files differnew file mode 100644 index 00000000..5c2b1305 --- /dev/null +++ b/keystonemiddleware-moon/doc/source/images/audit.png 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 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" + "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"> +<!-- Generated by graphviz version 2.27.20101213.0545 (20101213.0545) + --> +<!-- Title: AuthComp Pages: 1 --> +<svg width="510pt" height="118pt" + viewBox="0.00 0.00 510.00 118.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"> +<g id="graph1" class="graph" transform="scale(1 1) rotate(0) translate(4 114)"> +<title>AuthComp</title> +<polygon fill="white" stroke="white" points="-4,5 -4,-114 507,-114 507,5 -4,5"/> +<!-- AuthComp --> +<g id="node2" class="node"><title>AuthComp</title> +<polygon fill="#fdefe3" stroke="#c00000" points="292,-65 194,-65 194,-25 292,-25 292,-65"/> +<text text-anchor="middle" x="243" y="-48.4" font-family="Helvetica,sans-Serif" font-size="14.00">Auth</text> +<text text-anchor="middle" x="243" y="-32.4" font-family="Helvetica,sans-Serif" font-size="14.00">Component</text> +</g> +<!-- Reject --> +<!-- AuthComp->Reject --> +<g id="edge3" class="edge"><title>AuthComp->Reject</title> +<path fill="none" stroke="black" d="M193.933,-51.2787C157.514,-55.939 108.38,-62.2263 73.8172,-66.649"/> +<polygon fill="black" stroke="black" points="73.0637,-63.2168 63.5888,-67.9578 73.9522,-70.1602 73.0637,-63.2168"/> +<text text-anchor="middle" x="129" y="-97.4" font-family="Times,serif" font-size="14.00">Reject</text> +<text text-anchor="middle" x="129" y="-82.4" font-family="Times,serif" font-size="14.00">Unauthenticated</text> +<text text-anchor="middle" x="129" y="-67.4" font-family="Times,serif" font-size="14.00">Requests</text> +</g> +<!-- Service --> +<g id="node6" class="node"><title>Service</title> +<polygon fill="#d1ebf1" stroke="#1f477d" points="502,-65 408,-65 408,-25 502,-25 502,-65"/> +<text text-anchor="middle" x="455" y="-48.4" font-family="Helvetica,sans-Serif" font-size="14.00">OpenStack</text> +<text text-anchor="middle" x="455" y="-32.4" font-family="Helvetica,sans-Serif" font-size="14.00">Service</text> +</g> +<!-- AuthComp->Service --> +<g id="edge5" class="edge"><title>AuthComp->Service</title> +<path fill="none" stroke="black" d="M292.17,-45C323.626,-45 364.563,-45 397.52,-45"/> +<polygon fill="black" stroke="black" points="397.917,-48.5001 407.917,-45 397.917,-41.5001 397.917,-48.5001"/> +<text text-anchor="middle" x="350" y="-77.4" font-family="Times,serif" font-size="14.00">Forward</text> +<text text-anchor="middle" x="350" y="-62.4" font-family="Times,serif" font-size="14.00">Authenticated</text> +<text text-anchor="middle" x="350" y="-47.4" font-family="Times,serif" font-size="14.00">Requests</text> +</g> +<!-- Start --> +<!-- Start->AuthComp --> +<g id="edge7" class="edge"><title>Start->AuthComp</title> +<path fill="none" stroke="black" d="M59.1526,-21.4745C90.4482,-25.4792 142.816,-32.1802 183.673,-37.4084"/> +<polygon fill="black" stroke="black" points="183.43,-40.9057 193.793,-38.7034 184.318,-33.9623 183.43,-40.9057"/> +</g> +</g> +</svg> 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 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" + "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"> +<!-- Generated by graphviz version 2.27.20101213.0545 (20101213.0545) + --> +<!-- Title: AuthCompDelegate Pages: 1 --> +<svg width="588pt" height="104pt" + viewBox="0.00 0.00 588.00 104.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"> +<g id="graph1" class="graph" transform="scale(1 1) rotate(0) translate(4 100)"> +<title>AuthCompDelegate</title> +<polygon fill="white" stroke="white" points="-4,5 -4,-100 585,-100 585,5 -4,5"/> +<!-- AuthComp --> +<g id="node2" class="node"><title>AuthComp</title> +<polygon fill="#fdefe3" stroke="#c00000" points="338,-65 240,-65 240,-25 338,-25 338,-65"/> +<text text-anchor="middle" x="289" y="-48.4" font-family="Helvetica,sans-Serif" font-size="14.00">Auth</text> +<text text-anchor="middle" x="289" y="-32.4" font-family="Helvetica,sans-Serif" font-size="14.00">Component</text> +</g> +<!-- Reject --> +<!-- AuthComp->Reject --> +<g id="edge3" class="edge"><title>AuthComp->Reject</title> +<path fill="none" stroke="black" d="M239.6,-50.1899C191.406,-55.2531 118.917,-62.8686 73.5875,-67.6309"/> +<polygon fill="black" stroke="black" points="73.0928,-64.1635 63.5132,-68.6893 73.8242,-71.1252 73.0928,-64.1635"/> +<text text-anchor="middle" x="152" y="-83.4" font-family="Times,serif" font-size="14.00">Reject Requests</text> +<text text-anchor="middle" x="152" y="-68.4" font-family="Times,serif" font-size="14.00">Indicated by the Service</text> +</g> +<!-- Service --> +<g id="node6" class="node"><title>Service</title> +<polygon fill="#d1ebf1" stroke="#1f477d" points="580,-65 486,-65 486,-25 580,-25 580,-65"/> +<text text-anchor="middle" x="533" y="-48.4" font-family="Helvetica,sans-Serif" font-size="14.00">OpenStack</text> +<text text-anchor="middle" x="533" y="-32.4" font-family="Helvetica,sans-Serif" font-size="14.00">Service</text> +</g> +<!-- AuthComp->Service --> +<g id="edge5" class="edge"><title>AuthComp->Service</title> +<path fill="none" stroke="black" d="M338.009,-49.0804C344.065,-49.4598 350.172,-49.7828 356,-50 405.743,-51.8535 418.259,-51.9103 468,-50 470.523,-49.9031 473.101,-49.7851 475.704,-49.6504"/> +<polygon fill="black" stroke="black" points="476.03,-53.1374 485.807,-49.0576 475.62,-46.1494 476.03,-53.1374"/> +<text text-anchor="middle" x="412" y="-68.4" font-family="Times,serif" font-size="14.00">Forward Requests</text> +<text text-anchor="middle" x="412" y="-53.4" font-family="Times,serif" font-size="14.00">with Identiy Status</text> +</g> +<!-- Service->AuthComp --> +<g id="edge7" class="edge"><title>Service->AuthComp</title> +<path fill="none" stroke="black" d="M495.062,-24.9037C486.397,-21.2187 477.064,-17.9304 468,-16 419.314,-5.63183 404.743,-5.9037 356,-16 349.891,-17.2653 343.655,-19.116 337.566,-21.2803"/> +<polygon fill="black" stroke="black" points="336.234,-18.0426 328.158,-24.9003 338.748,-24.5757 336.234,-18.0426"/> +<text text-anchor="middle" x="412" y="-33.4" font-family="Times,serif" font-size="14.00">Send Response OR</text> +<text text-anchor="middle" x="412" y="-18.4" font-family="Times,serif" font-size="14.00">Reject Message</text> +</g> +<!-- Start --> +<!-- Start->AuthComp --> +<g id="edge9" class="edge"><title>Start->AuthComp</title> +<path fill="none" stroke="black" d="M59.0178,-20.8384C99.2135,-25.0613 175.782,-33.1055 229.492,-38.7482"/> +<polygon fill="black" stroke="black" points="229.265,-42.2435 239.576,-39.8076 229.997,-35.2818 229.265,-42.2435"/> +</g> +</g> +</svg> 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=<None> + + # API version of the admin Identity API endpoint (string + # value) + #auth_version=<None> + + # 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=<None> + + # 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=<None> + + # Keystone account username (string value) + #admin_user=<None> + + # 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=<None> + + # Required if Keystone server requires client certificate + # (string value) + #certfile=<None> + + # Required if Keystone server requires client certificate + # (string value) + #keyfile=<None> + + # A PEM encoded Certificate Authority to use when verifying + # HTTPs connections. Defaults to system CAs. (string value) + #cafile=<None> + + # Verify HTTPS connections. (boolean value) + #insecure=false + + # Directory used to cache files related to PKI tokens (string + # value) + #signing_dir=<None> + + # If defined, the memcache server(s) to use for caching (list + # value) + # Deprecated group/name - [DEFAULT]/memcache_servers + #memcached_servers=<None> + + # 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=<None> + + # (optional, mandatory if memcache_security_strategy is + # defined) this string is used for key derivation. (string + # value) + #memcache_secret_key=<None> + + # (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/. |
