Add a full listing of all auth plugins and there options

A commonly requested document is what auth plugins are available and
what parameters do they accept. Create an extension that can iterate
through the stevedore namespace and render all its available options.

Change-Id: Id0d0983c9803ce4e0ce201310a1603bc0ff30ca0
Jamie Lennox 6 years ago committed by Steve Martinelli
parent 9d3ae3ef94
commit c21ef89a88

@ -0,0 +1,93 @@
# 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
# 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.
import inspect
from docutils import nodes
from docutils.parsers import rst
from docutils.parsers.rst import directives
from docutils.statemachine import ViewList
from sphinx.util.nodes import nested_parse_with_titles
from stevedore import extension
class ListAuthPluginsDirective(rst.Directive):
"""Present a simple list of the plugins in a namespace."""
option_spec = {
'class': directives.class_option,
'overline-style': directives.single_char_or_unicode,
'underline-style': directives.single_char_or_unicode,
has_content = True
def app(self):
def report_load_failure(mgr, ep, err):'Failed to load %s: %s' % (ep.module_name, err))
def display_plugin(self, ext):
overline_style = self.options.get('overline-style', '')
underline_style = self.options.get('underline-style', '=')
if overline_style:
yield overline_style * len(
if underline_style:
yield underline_style * len(
yield "\n"
doc = inspect.getdoc(ext.obj)
if doc:
yield doc
yield "\n"
yield "------"
yield "\n"
for opt in ext.obj.get_options():
yield ":%s: %s" % (,
yield "\n"
def run(self):
mgr = extension.ExtensionManager(
result = ViewList()
for name in sorted(mgr.names()):
for line in self.display_plugin(mgr[name]):
for l in line.splitlines():
result.append(l, mgr[name].entry_point.module_name)
# Parse what we have into a new section.
node = nodes.section()
node.document = self.state.document
nested_parse_with_titles(self.state, result, node)
return node.children
def setup(app):'loading keystoneauth1 plugins')
app.add_directive('list-auth-plugins', ListAuthPluginsDirective)

@ -24,6 +24,8 @@ import pbr.version
sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__),
'..', '..')))
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
@ -40,6 +42,7 @@ extensions = ['sphinx.ext.autodoc',
todo_include_todos = True

@ -13,6 +13,7 @@ Contents:

@ -0,0 +1,92 @@
Plugin Options
Using plugins via config file
When using the plugins via config file you define the plugin name as
``auth_type``. The options of the plugin are then specified while replacing
``-`` with ``_`` to be valid in configuration.
For example to use the password_ plugin in a config file you would specify:
.. code-block:: ini
auth_url =
auth_type = password
username = myuser
password = mypassword
project_name = myproject
default_domain_name = mydomain
Using plugins via CLI
When using auth plugins via CLI via ``os-client-config`` or ``shade`` you can
specify parameters via environment configuration by using the pattern ``OS_``
followed by the uppercase parameter name replacing ``-`` with ``_``.
For example to use the password_ plugin via environment variable you specify:
.. code-block:: bash
export OS_AUTH_TYPE=password
export OS_AUTH_URL=
export OS_USERNAME=myuser
export OS_PASSWORD=mypassword
export OS_PROJECT_NAME=myproject
export OS_DEFAULT_DOMAIN_NAME=mydomain
Specifying operations via CLI parameter will override the environment
parameter. These are specified with the pattern ``--os-`` and the parameter
name. Using the password_ example again:
.. code-block:: bash
openstack --os-auth-type password \
--os-auth-url \
--os-username myuser \
--os-password mypassword \
--os-project-name myproject \
--os-default-domain-name mydomain \
Additional loaders
The configuration and CLI loaders are quite commonly used however similar
concepts are found in other situations such as ``os-client-config`` in which
you specify authentication and other cloud parameters in a ``clouds.yaml``
Loaders such as these use the same plugin options listed below, but via their
own mechanism. In ``os-client-config`` the password_ plugin looks like:
.. code-block:: yaml
auth_type: password
auth_type: password
username: myuser
password: mypassword
project_name: myproject
default_domain_name: mydomain
However different services may implement loaders in their own way and you
should consult their relevant documentation. The same auth options will be
Available Plugins
This is a listing of all included plugins and the options that they accept.
Plugins are listed alphabetically and not in any order of priority.
.. list-auth-plugins::

@ -15,6 +15,17 @@ from keystoneauth1 import token_endpoint
class AdminToken(loading.BaseLoader):
"""Use an existing token and a known endpoint to perform requests.
This plugin is primarily useful for development or for use with identity
service ADMIN tokens. Because this token is used directly there is no
fetching a service catalog or determining scope information and so it
cannot be used by clients that expect use this scope information.
Because there is no service catalog the endpoint that is supplied with
initialization is used for all operations performed with this plugin so
must be the full base URL to an actual service.
def plugin_class(self):

@ -15,6 +15,18 @@ from keystoneauth1 import loading
class Token(loading.BaseGenericLoader):
"""Given an existing token rescope it to another target.
This plugin uses the Identity service's rescope mechanism to get a new
token based upon an existing token. Because an auth plugin requires a
service catalog and scope information it is often easier to fetch a new
token based on an existing one than validate and reuse the one you already
As a generic plugin this plugin is identity version independent and will
discover available versions before use. This means it expects to be
providen an unversioned URL to operate against.
def plugin_class(self):
@ -32,6 +44,15 @@ class Token(loading.BaseGenericLoader):
class Password(loading.BaseGenericLoader):
"""Authenticate via a username and password.
Authenticate to the identity service using an inbuilt username and
password. This is the standard and most common form of authentication.
As a generic plugin this plugin is identity version independent and will
discover available versions before use. This means it expects to be
providen an unversioned URL to operate against.
def plugin_class(self):