Using a single chapter for the API docs and a single chapter for the ZCML directives made it hard to read.

1 files changed, 53 insertions, 0 deletions

diff --git a/docs/zcml/remoteuserauthenticationpolicy.rst b/docs/zcml/remoteuserauthenticationpolicy.rst
new file mode 100644
index 000000000..61f519e4c
--- /dev/null
+++ b/docs/zcml/remoteuserauthenticationpolicy.rst
@@ -0,0 +1,53 @@
+.. _remoteuserauthenticationpolicy_directive:
+
+``remoteuserauthenticationpolicy``
+----------------------------------
+
+When this directive is used, authentication information is obtained
+from a ``REMOTE_USER`` key in the WSGI environment, assumed to
+be set by a WSGI server or an upstream middleware component.
+
+Attributes
+~~~~~~~~~~
+
+``environ_key``
+
+    The ``environ_key`` is the name that will be used to obtain the
+    remote user value from the WSGI environment.  It defaults to
+    ``REMOTE_USER``.
+
+``callback``
+
+    The ``callback`` is a Python dotted name to a function passed the
+    string representing the remote user and the request as positional
+    arguments.  The callback is expected to return None if the user
+    represented by the string doesn't exist or a sequence of group
+    identifiers (possibly empty) if the user does exist.  If
+    ``callback`` is None, the userid will be assumed to exist with no
+    groups.  It defaults to ``None``.
+
+Example
+~~~~~~~
+
+.. code-block:: xml
+   :linenos:
+
+   <remoteuserauthenticationpolicy
+    environ_key="REMOTE_USER"
+    callback=".somemodule.somefunc"
+    />
+
+Alternatives
+~~~~~~~~~~~~
+
+You may create an instance of the
+:class:`repoze.bfg.authentication.RemoteUserAuthenticationPolicy` and
+pass it to the :class:`repoze.bfg.configuration.Configurator`
+constructor as the ``authentication_policy`` argument during initial
+application configuration.
+
+See Also
+~~~~~~~~
+
+See also :ref:`authentication_policies_directives_section` and
+:class:`repoze.bfg.authentication.RemoteUserAuthenticationPolicy`.