Risk based authentication doc (#2593)

doc/sources/admin/index_advanced.rst

@@ -4,11 +4,14 @@ Advanced features
 .. toctree::
    :maxdepth: 1
 
+   rbac
+   ssoaas
+   servertoserver
+   riskbased
    smtp
    notifications
    passwordstore
    cda
-   rbac
    customfunctions
    extendedfunctions
    resetpassword
@@ -16,8 +19,6 @@ Advanced features
    logoutforward
    securetoken
    handlerauthbasic
-   ssoaas
-   servertoserver
    safejail
    loginhistory
    fastcgi

doc/sources/admin/riskbased.rst

@@ -0,0 +1,77 @@
+Risk-based Authentication
+=========================
+
+Our definition
+--------------
+
+Risk-based authentication is the ability to take into account the context of
+the authentication process, and react accordingly, by increasing the
+authentication challenge (second factor, email confirmation) or trigger out of
+band actions (email notifications, alerts..).
+
+.. warning::
+
+   All the features presented on this page are not natively supported by
+   LemonLDAP::NG but can be added through custom plugins or configuration
+
+The authentication context can include:
+
+* Source IP address
+* Access time
+* Previous authentications (history)
+* Using the same browser as previous logins
+
+Reactions can include:
+
+* Triggering or skipping the second factor
+* Sending an email to warn the user of a suspicious login
+* Denying attempt if the suspicion level is too high
+
+Implementation in LemonLDAP::NG
+-------------------------------
+
+LemonLDAP::NG uses the ``_riskLevel`` and ``_riskDetails`` session variables to
+keep track of the risk associated to the current authentication.
+
+Detection plugins will raise or lower the risk level, and store fine-grained
+details in the risk details object.
+
+Action plugins may use the risk level to trigger certain actions, and can
+translate the risk detail items into user-friendly messages.
+
+
+Compatible plugins
+------------------
+
+Detection
+~~~~~~~~~
+
+New location warning
+^^^^^^^^^^^^^^^^^^^^
+
+.. versionadded:: 2.0.14
+
+The :doc:`New Location warning <newlocationwarning>` plugin will increase the risk level by 1 when triggered, and will store the **Session attribute to display** in ``$_riskDetail->{newLocation}``.
+
+Action
+~~~~~~
+
+Forbidding/triggering second factors
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You can use the following activation rule to trigger second factors if the risk level is high::
+
+    $_riskLevel > 0
+
+Or, if you use self registration::
+
+    has2f('TOTP') and $_riskLevel > 0
+
+Denying login
+^^^^^^^^^^^^^
+
+You can use :doc:`session opening conditions <grantsession>` to deny access if the risk level is too high with a rule like this ::
+
+    $_riskLevel < 2
+
+This will forbid sessions from being opened if the risk level is greater or equal to 2

doc/sources/admin/secondfactor.rst

@@ -43,7 +43,7 @@ Registration on first use
 If you want to force a 2F registration on first login, you can use the *Force
 2FA registration at login* option.
 
-You can use a `rule<writingrulesand_headers>` to enable this behavior only for
+You can use a :doc:`rule <writingrulesand_headers>` to enable this behavior only for
 some users.
 
 Session upgrade through 2FA