Merge "Remove custom auth middleware documentation"

doc/source/advanced-topics/external-auth.rst

@@ -92,88 +92,3 @@ a valid X.509 certificate from a known CA::
 
         (...)
     </VirtualHost>
-
-Developing a WSGI middleware for authentication
-===============================================
-
-In addition to the method described above, it is possible to implement other
-custom authentication mechanisms using the ``REMOTE_USER`` WSGI environment
-variable.
-
-.. ATTENTION::
-
-    Please note that even if it is possible to develop a custom authentication
-    module, it is preferable to use the modules in the HTTPD server. Such
-    authentication modules in webservers like Apache have normally undergone
-    years of development and use in production systems and are actively
-    maintained upstream. Developing a custom authentication module that
-    implements the same authentication as an existing Apache module likely
-    introduces a higher security risk.
-
-If you find you must implement a custom authentication mechanism, you will need
-to develop a custom WSGI middleware pipeline component. This middleware should
-set the environment variable ``REMOTE_USER`` to the authenticated username.
-Keystone then will assume that the user has been already authenticated upstream
-and will not try to authenticate it. However, as with HTTPD authentication, the
-user must exist in advance in the identity backend so that a proper token can
-be issued.
-
-Your code should set the ``REMOTE_USER`` if the user is properly authenticated,
-following the semantics below:
-
-.. code-block:: python
-
-    from keystone.common import wsgi
-    from keystone import exception
-
-    class MyMiddlewareAuth(wsgi.Middleware):
-        def __init__(self, *args, **kwargs):
-            super(MyMiddlewareAuth, self).__init__(*args, **kwargs)
-
-        def process_request(self, request):
-            if request.environ.get('REMOTE_USER', None) is not None:
-                # Assume that it is authenticated upstream
-                return self.application
-
-            if not self.is_auth_applicable(request):
-                # Not applicable
-                return self.application
-
-            username = self.do_auth(request)
-            if username is not None:
-                # User is authenticated
-                request.environ['REMOTE_USER'] = username
-            else:
-                # User is not authenticated, render exception
-                raise exception.Unauthorized("Invalid user")
-
-
-Pipeline configuration
-----------------------
-
-Once you have your WSGI middleware component developed you have to add it to
-your pipeline. The first step is to add the middleware to your configuration
-file. Assuming that your middleware module is
-``keystone.middleware.MyMiddlewareAuth``, you can configure it in your
-``keystone-paste.ini`` as::
-
-    [filter:my_auth]
-    paste.filter_factory = keystone.middleware.MyMiddlewareAuth.factory
-
-The second step is to add your middleware to the pipeline. The exact place
-where you should place it will depend on your code (i.e. if you need for
-example that the request body is converted from JSON before perform the
-authentication you should place it after the ``json_body`` filter) but it
-should be set before the ``public_service`` (for the ``public_api`` pipeline)
-or ``admin_service`` (for the ``admin_api`` pipeline), since they consume
-authentication.
-
-For example, if the original pipeline looks like this::
-
-    [pipeline:public_api]
-    pipeline = url_normalize token_auth json_body debug ec2_extension user_crud_extension public_service
-
-Your modified pipeline might then look like this::
-
-    [pipeline:public_api]
-    pipeline = url_normalize token_auth json_body my_auth debug ec2_extension user_crud_extension public_service