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 | 48742 -> 0 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 | 472 |
7 files changed, 0 insertions, 937 deletions
diff --git a/keystonemiddleware-moon/doc/source/audit.rst b/keystonemiddleware-moon/doc/source/audit.rst deleted file mode 100644 index d23f8168..00000000 --- a/keystonemiddleware-moon/doc/source/audit.rst +++ /dev/null @@ -1,81 +0,0 @@ -.. - 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 deleted file mode 100644 index ff4b24cc..00000000 --- a/keystonemiddleware-moon/doc/source/conf.py +++ /dev/null @@ -1,237 +0,0 @@ -# -*- 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 = ['keystonemiddleware.'] - -# 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 differdeleted file mode 100644 index 5c2b1305..00000000 --- a/keystonemiddleware-moon/doc/source/images/audit.png +++ /dev/null diff --git a/keystonemiddleware-moon/doc/source/images/graphs_authComp.svg b/keystonemiddleware-moon/doc/source/images/graphs_authComp.svg deleted file mode 100644 index 6be629c1..00000000 --- a/keystonemiddleware-moon/doc/source/images/graphs_authComp.svg +++ /dev/null @@ -1,48 +0,0 @@ -<?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 deleted file mode 100644 index 4788829a..00000000 --- a/keystonemiddleware-moon/doc/source/images/graphs_authCompDelegate.svg +++ /dev/null @@ -1,53 +0,0 @@ -<?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 deleted file mode 100644 index 9092ec79..00000000 --- a/keystonemiddleware-moon/doc/source/index.rst +++ /dev/null @@ -1,46 +0,0 @@ -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 deleted file mode 100644 index e543be47..00000000 --- a/keystonemiddleware-moon/doc/source/middlewarearchitecture.rst +++ /dev/null @@ -1,472 +0,0 @@ -.. 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 memcached 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. - -If the service doesn't use the global oslo.config object (CONF), then the -olso config project name can be set it in paste config and -keystonemiddleware will load the project configuration itself. -Optionally the location of the configuration file can be set if oslo.config -is not able to discover it. - -.. code-block:: ini - - [filter:authtoken] - paste.filter_factory = keystonemiddleware.auth_token:filter_factory - oslo_config_project = nova - # oslo_config_file = /not_discoverable_location/nova.conf - - -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 memcached 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 memcached 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 memcached 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/. |
