# HG changeset patch
# User Christophe de Vienne <christophe@unlish.com>
# Date 1424900439 -3600
# Node ID 6398be12f8e65554c4d559739300206be0ed5b47
# Parent  a6547ff97ce017d180bc82c65cebef05973f78e7
[doc] Document the new authentication stack

diff -r a6547ff97ce0 -r 6398be12f8e6 docs/api/auth.rst
--- a/docs/api/auth.rst	Tue Apr 28 11:04:03 2015 +0200
+++ b/docs/api/auth.rst	Wed Feb 25 22:40:39 2015 +0100
@@ -7,6 +7,6 @@
 
     .. autofunction:: includeme
 
-    .. autoclass:: CubicWebAuthTktAuthenticationPolicy
+    .. autoclass:: UpdateLoginTimeAuthenticationPolicy
         :show-inheritance:
         :members:
diff -r a6547ff97ce0 -r 6398be12f8e6 docs/index.rst
--- a/docs/index.rst	Tue Apr 28 11:04:03 2015 +0200
+++ b/docs/index.rst	Wed Feb 25 22:40:39 2015 +0100
@@ -23,6 +23,7 @@
     narr/quickstart
     narr/ctl
     narr/settings
+    narr/auth
     narr/profiling
 
 Api Documentation
diff -r a6547ff97ce0 -r 6398be12f8e6 docs/narr/auth.rst
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/narr/auth.rst	Wed Feb 25 22:40:39 2015 +0100
@@ -0,0 +1,40 @@
+Authentication
+==============
+
+Overview
+--------
+
+A default authentication stack is provided by the :mod:`pyramid_cubicweb.auth`
+module, which is included by :mod:`pyramid_cubicweb.default`.
+
+The authentication stack is built around `pyramid_multiauth`_, and provides a
+few default policies that reproduce the default cubicweb behavior.
+
+.. note::
+
+    Note that this module only provides an authentication policy, not the views
+    that handle the login form. See :ref:`login_module`
+
+Customize
+---------
+
+The default policies can be individually deactivated, as well as the default
+authentication callback that returns the current user groups as :term:`principals`.
+
+The following settings can be set to `False`:
+
+-   :confval:`cubicweb.auth.update_login_time`. Activate the policy that update
+    the user `login_time` when `remember` is called.
+-   :confval:`cubicweb.auth.authtkt` and all its subvalues.
+-   :confval:`cubicweb.auth.groups_principals`
+
+Additionnal policies can be added by accessing the MultiAuthenticationPolicy
+instance in the registry:
+
+.. code-block:: python
+
+    mypolicy = SomePolicy()
+    authpolicy = config.registry['cubicweb.authpolicy']
+    authpolicy._policies.append(mypolicy)
+
+.. _pyramid_multiauth: https://github.com/mozilla-services/pyramid_multiauth
diff -r a6547ff97ce0 -r 6398be12f8e6 docs/narr/settings.rst
--- a/docs/narr/settings.rst	Tue Apr 28 11:04:03 2015 +0200
+++ b/docs/narr/settings.rst	Wed Feb 25 22:40:39 2015 +0100
@@ -86,3 +86,57 @@
 .. confval:: cubicweb.profile (bool)
 
     (False) Enable/disable profiling. See :ref:`profiling`.
+
+.. confval:: cubicweb.auth.update_login_time (bool)
+
+    (True) Add a :class:`pyramid_cubicweb.auth.UpdateLoginTimeAuthenticationPolicy`
+    policy, that update the CWUser.login_time attribute when a user login.
+    
+.. confval:: cubicweb.auth.authtkt (bool)
+
+    (True) Enables the 2 cookie-base auth policies, which activate/deactivate
+    depending on the `persistent` argument passed to `remember`.
+
+    The default login views set persistent to True if a `__setauthcookie`
+    parameters is passed to them, and evals to True in
+    :func:`pyramid.settings.asbool`.
+
+    The configuration values of the policies are arguments for
+    :class:`pyramid.authentication.AuthTktAuthenticationPolicy`.
+
+    The first policy handles session authentication. It doesn't get
+    activated if `remember()` is called with `persistent=False`:
+
+    .. confval:: cubicweb.auth.authtkt.session.cookie_name (str)
+
+        ('auth_tkt') The cookie name. Must be different from the persistent
+        authentication cookie name.
+
+    .. confval:: cubicweb.auth.authtkt.session.timeout (int)
+
+        (1200) Cookie timeout.
+
+    .. confval:: cubicweb.auth.authtkt.session.reissue_time (int)
+
+        (120) Reissue time.
+
+    The second policy handles persistent authentication. It doesn't get
+    activated if `remember()` is called with `persistent=True`:
+
+    .. confval:: cubicweb.auth.authtkt.persistent.cookie_name (str)
+
+        ('auth_tkt') The cookie name. Must be different from the session
+        authentication cookie name.
+
+    .. confval:: cubicweb.auth.authtkt.persistent.max_age (int)
+
+        (30 days) Max age in seconds.
+
+    .. confval:: cubicweb.auth.authtkt.persistent.reissue_time (int)
+
+        (1 day) Reissue time in seconds.
+
+.. confval:: cubicweb.auth.groups_principals (bool)
+
+    (True) Setup a callback on the authentication stack that inject the user
+    groups in the principals.