# 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.

## 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 `bind` by default. `method_names` is a list and `bind` 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`.

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.

this page last updated: 2026-06-11 21:50:20

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.

found an error? report a bug