openstack/keystone
Code Issues Proposed changes
b43b402ca9
keystone/doc/source/contributor/auth-plugins.rst
Lance Bragstad 429e115686 Add contributor/ directory for docs 
The specification detailing the great documentation migration
requires a doc/source/contributor/ directory for all contributor
documentation. Keystone had a directory specifically for this type
of content but it was in doc/source/devref/.

This commit renames devref/ to contributor/ because the term
`contributor` is more inclusive of other community members that
aren't necessarily developers. The specification also requires this
convention for consistency with other projects.

Change-Id: Id6363213dc6ba6946bd272ca5ee67b4604afc5ac
Partial-Bug: 1694460
2017-08-01 21:14:46 +00:00

4.0 KiB
Raw Blame History

Authentication Plugins

Note

This feature is only supported by keystone for the Identity API v3 clients.

Keystone supports authentication plugins and they are specified in the [auth] section of the configuration file. However, an authentication plugin may also have its own section in the configuration file. It is up to the plugin to register its own configuration options.

  • methods - comma-delimited list of authentication plugin names
  • <plugin name> - specify the class which handles to authentication method, in the same manner as one would specify a backend driver.

Keystone provides three authentication methods by default. password handles password authentication and token handles token authentication. external is used in conjunction with authentication performed by a container web server that sets the REMOTE_USER environment variable. For more details, refer to External Authentication <../advanced-topics/external-auth>.

How to Implement an Authentication Plugin

All authentication plugins must extend the keystone.auth.plugins.base.AuthMethodHandler class and implement the authenticate() method. The authenticate() method expects the following parameters.

  • context - keystone's request context
  • auth_payload - the content of the authentication for a given method
  • auth_context - user authentication context, a dictionary shared by all plugins. It contains method_names and extras by default. method_names is a list and extras is a dictionary.

If successful, the authenticate() method must provide a valid user_id in auth_context and return None. method_name is used to convey any additional authentication methods in case authentication is for re-scoping. For example, if the authentication is for re-scoping, a plugin must append the previous method names into method_names. Also, a plugin may add any additional information into extras. Anything in extras will be conveyed in the token's extras field.

If authentication requires multiple steps, the authenticate() method must return the payload in the form of a dictionary for the next authentication step.

If authentication is unsuccessful, the authenticate() method must raise a keystone.exception.Unauthorized exception.

Simply add the new plugin name to the methods list along with your plugin class configuration in the [auth] sections of the configuration file to deploy it.

If the plugin requires additional configurations, it may register its own section in the configuration file.

Plugins are invoked in the order in which they are specified in the methods attribute of the authentication request body. If multiple plugins are invoked, all plugins must succeed in order to for the entire authentication to be successful. Furthermore, all the plugins invoked must agree on the user_id in the auth_context.

The REMOTE_USER environment variable is only set from a containing webserver. However, to ensure that a user must go through other authentication mechanisms, even if this variable is set, remove external from the list of plugins specified in methods. This effectively disables external authentication. For more details, refer to External Authentication <../advanced-topics/external-auth>.