From e2ebb3c41ad739a16e903f21c4b0c8eea3715711 Mon Sep 17 00:00:00 2001 From: Lance Bragstad Date: Tue, 18 Jul 2017 15:50:01 +0000 Subject: [PATCH] Move auth plugin development doc to contrib guide The operator documentation had a section specific to developing authentication plugins. This type of documentation is better suited to the contributor guide. This commit moves it there. Change-Id: I74337e8b3d8c9031fa3cb7fb709cc41042161bb9 --- doc/source/configuration.rst | 72 ------------------------- doc/source/devref/auth-plugins.rst | 87 ++++++++++++++++++++++++++++++ doc/source/devref/index.rst | 1 + 3 files changed, 88 insertions(+), 72 deletions(-) create mode 100644 doc/source/devref/auth-plugins.rst diff --git a/doc/source/configuration.rst b/doc/source/configuration.rst index 8186a060e5..a97cc7163f 100644 --- a/doc/source/configuration.rst +++ b/doc/source/configuration.rst @@ -401,78 +401,6 @@ following property: invalid, so typically the generator selection should be considered immutable for a given installation. -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 -* ```` - 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 :doc:`External Authentication -`. - -How to Implement an Authentication Plugin ------------------------------------------ - -All authentication plugins must extend the -:class:`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 -:class:`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 :doc:`External Authentication -`. - Certificates for PKI ==================== diff --git a/doc/source/devref/auth-plugins.rst b/doc/source/devref/auth-plugins.rst new file mode 100644 index 0000000000..fbf6fe4043 --- /dev/null +++ b/doc/source/devref/auth-plugins.rst @@ -0,0 +1,87 @@ +.. + Copyright 2011-2012 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. + +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 +* ```` - 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 :doc:`External Authentication +<../advanced-topics/external-auth>`. + +How to Implement an Authentication Plugin +----------------------------------------- + +All authentication plugins must extend the +:class:`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 +:class:`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 :doc:`External Authentication +<../advanced-topics/external-auth>`. + diff --git a/doc/source/devref/index.rst b/doc/source/devref/index.rst index a129418f64..0939114e27 100644 --- a/doc/source/devref/index.rst +++ b/doc/source/devref/index.rst @@ -33,6 +33,7 @@ Contributor Documentation doctor-checks.rst http-api.rst api_change_tutorial.rst + auth-plugins.rst database-migrations.rst id-manage.rst translated-responses.rst