From 9f812939d4b05384b0a7d48e6b916baeca0477dc Mon Sep 17 00:00:00 2001 From: Guang Yee Date: Tue, 8 Jan 2013 08:46:20 -0800 Subject: v3 token API Also implemented the following: blueprint pluggable-identity-authentication-handlers blueprint stop-ids-in-uris blueprint multi-factor-authn (just the plumbing) What's missing? * domain scoping (will be implemented by Henry?) Change-Id: I191c0b2cb3367b2a5f8a2dc674c284bb13ea97e3 --- doc/source/configuration.rst | 54 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) (limited to 'doc') diff --git a/doc/source/configuration.rst b/doc/source/configuration.rst index b810050e..377dfbe8 100644 --- a/doc/source/configuration.rst +++ b/doc/source/configuration.rst @@ -75,6 +75,7 @@ values are organized into the following sections: * ``[policy]`` - policy system driver configuration for RBAC * ``[signing]`` - cryptographic signatures for PKI based tokens * ``[ssl]`` - SSL configuration +* ``[auth]`` - Authentication plugin configuration The Keystone configuration file is expected to be named ``keystone.conf``. When starting keystone, you can specify a different configuration file to @@ -88,6 +89,59 @@ order: * ``/etc/`` +Authentication Plugins +---------------------- + +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 +* ```` - specify the class which handles to authentication method, in the same manner as one would specify a backend driver. + +Keystone provides two authentication methods by default. ``password`` handles password authentication and ``token`` handles token authentication. + +How to Implement an Authentication Plugin +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +All authentication plugins must extend the +``keystone.auth.core.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 require addition 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``. + Certificates for PKI -------------------- -- cgit