dani/lemonldap-ng
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Rework Browseable docs (#2320)

Browse Source
This commit is contained in:
Maxime Besson 2020-09-23 07:51:35 +02:00
parent 7e48ec702e
commit 667e7f09c4
7 changed files with 304 additions and 237 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

35
doc/sources/admin/browseableldapsessionbackend.rst Normal file
View File

@ -0,0 +1,35 @@
Browseable LDAP session backend
===============================
LemonLDAP::NG configuration
---------------------------
Go in the Manager and set the session module to ``Apache::Session::Browseable::LDAP`` for each session type you intend to use:
* ``General parameters`` » ``Sessions`` » ``Session storage`` » ``Apache::Session module``
* ``General parameters`` » ``Sessions`` » ``Persistent sessions`` » ``Apache::Session module``
* ``CAS Service`` » ``CAS sessions module name``
* ``OpenID Connect Service`` » ``Sessions`` » ``Sessions module name``
* ``SAML2 Service`` » ``Advanced`` » ``SAML sessions module name``
The fill out the corresponding module parameters:
======================== ================================= ===============================
Required parameters
======================== ================================= ===============================
Name Comment Example
**ldapServer** URI of the server ldap://localhost
**ldapConfBase** DN of sessions branch ou=sessions,dc=example,dc=com
**ldapBindDN** Connection login cn=admin,dc=example,dc=password
**ldapBindPassword** Connection password secret
**Index** Fields to index refer to :ref:`fieldstoindex`
Optional parameters
Name Comment Default value
**ldapObjectClass** Objectclass of the entry applicationProcess
**ldapAttributeId** Attribute storing session ID cn
**ldapAttributeContent** Attribute storing session content description
**ldapAttributeIndex** Attribute storing index ou
**ldapVerify** Perform certificate validation require (use none to disable)
**ldapCAFile** Path of CA file bundle (system CA bundle)
**ldapCAPath** Perform CA directory (system CA bundle)
======================== ================================= ===============================

120
doc/sources/admin/browseablemysqlsessionbackend.rst Normal file
View File

@ -0,0 +1,120 @@
Browseable MySQL session backend
================================
Prerequisites
-------------
First, make sure you have installed the ``DBD::mysql`` perl module.
On Debian-based distributions ::
apt install libdbd-mysql-perl
On Fedora-based distributions ::
yum install 'perl(DBD::mysql)'
Create database schema
----------------------
Create the following tables. You may skip the session types you are not going to use, but you need at least ``sessions`` and ``psessions``
::
CREATE TABLE sessions (
id varchar(64) not null primary key,
a_session text,
_whatToTrace varchar(64),
_session_kind varchar(15),
ipAddr varchar(64),
_utime bigint,
_httpSessionType varchar(64),
user varchar(64)
) DEFAULT CHARSET utf8;
CREATE INDEX i_s__whatToTrace ON sessions (_whatToTrace);
CREATE INDEX i_s__session_kind ON sessions (_session_kind);
CREATE INDEX i_s__utime ON sessions (_utime);
CREATE INDEX i_s_ipAddr ON sessions (ipAddr);
CREATE INDEX i_s__httpSessionType ON sessions (_httpSessionType);
CREATE INDEX i_s_user ON sessions (user);
CREATE TABLE psessions (
id varchar(64) not null primary key,
a_session text,
_session_kind varchar(15),
_httpSessionType varchar(64),
_whatToTrace varchar(64),
ipAddr varchar(64),
_session_uid varchar(64)
) DEFAULT CHARSET utf8;
CREATE INDEX i_p__session_kind ON psessions (_session_kind);
CREATE INDEX i_p__httpSessionType ON psessions (_httpSessionType);
CREATE INDEX i_p__session_uid ON psessions (_session_uid);
CREATE INDEX i_p_ipAddr ON psessions (ipAddr);
CREATE INDEX i_p__whatToTrace ON psessions (_whatToTrace);
CREATE TABLE samlsessions (
id varchar(64) not null primary key,
a_session text,
_session_kind varchar(15),
_utime bigint,
ProxyID varchar(64),
_nameID varchar(128),
_assert_id varchar(64),
_art_id varchar(64),
_saml_id varchar(64)
) DEFAULT CHARSET utf8;
CREATE INDEX i_a__session_kind ON samlsessions (_session_kind);
CREATE INDEX i_a__utime ON samlsessions (_utime);
CREATE INDEX i_a_ProxyID ON samlsessions (ProxyID);
CREATE INDEX i_a__nameID ON samlsessions (_nameID);
CREATE INDEX i_a__assert_id ON samlsessions (_assert_id);
CREATE INDEX i_a__art_id ON samlsessions (_art_id);
CREATE INDEX i_a__saml_id ON samlsessions (_saml_id);
CREATE TABLE oidcsessions (
id varchar(64) not null primary key,
a_session text,
_session_kind varchar(15),
_utime bigint
) DEFAULT CHARSET utf8;
CREATE INDEX i_o__session_kind ON oidcsessions (_session_kind);
CREATE INDEX i_o__utime ON oidcsessions (_utime);
CREATE TABLE cassessions (
id varchar(64) not null primary key,
a_session text,
_session_kind varchar(15),
_utime bigint,
_cas_id varchar(128),
pgtIou varchar(128)
) DEFAULT CHARSET utf8
CREATE INDEX i_c__session_kind ON cassessions (_session_kind);
CREATE INDEX i_c__utime ON cassessions (_utime);
CREATE INDEX i_c__cas_id ON cassessions (_cas_id);
CREATE INDEX i_c_pgtIou ON cassessions (pgtIou);
LemonLDAP::NG configuration
---------------------------
Go in the Manager and set the session module to ``Apache::Session::Browseable::PgJSON`` for each session type you intend to use:
* ``General parameters`` » ``Sessions`` » ``Session storage`` » ``Apache::Session module``
* ``General parameters`` » ``Sessions`` » ``Persistent sessions`` » ``Apache::Session module``
* ``CAS Service`` » ``CAS sessions module name``
* ``OpenID Connect Service`` » ``Sessions`` » ``Sessions module name``
* ``SAML2 Service`` » ``Advanced`` » ``SAML sessions module name``
Then, set the following module options:
=================== ================================================= =============================================================
Required parameters
=================== ================================================= =============================================================
Name Comment Example
**DataSource** The `DBI <https://metacpan.org/pod/DBI>`__ string dbi:mysql:database=lemonldap-ng
**UserName** The database username lemonldapng
**Password** The database password mysuperpassword
**TableName** Table name (optional) sessions
**Index** Fields to index refer to :ref:`fieldstoindex`
=================== ================================================= =============================================================

265
doc/sources/admin/browseablesessionbackend.rst
View File

@ -7,250 +7,53 @@ Presentation
Browseable session backend
(`Apache::Session::Browseable <https://metacpan.org/pod/Apache::Session::Browseable>`__)
works exactly like Apache::Session::\* corresponding module but add
index that increase :ref:`session explorer<session-explorer>` and
:ref:`session restrictions<session-restrictions>` performances.
If you use features like SAML (authentication and issuer), CAS (issuer)
and password reset self-service, you also need to index some fields.
index that increase the speed of some operations. It is recommended in production deployments.
.. note::
Without index, LL::NG will have to retrieve all sessions stored in
backend and parse them to find the needed sessions. With index, LL::NG
wil be able to get only wanted sessions from the backend.
backend and deserialize then filter each of them.
The following table list fields to index depending on the feature you
want to increase performance:
The following table list fields to index for each session type:
====================================== ============= ===================================================================
Feature Session Type Fields to index
====================================== ============= ===================================================================
Database cleanup *(cron)* All \_session_kind \_utime
Session explorer Global \_session_kind ipAddr \_httpSessionType *WHATTOTRACE*
Session explorer Persistent \_session_kind \_session_uid ipAddr \_httpSessionType *WHATTOTRACE*
Session restrictions Global \_session_kind ipAddr *WHATTOTRACE*
Password reset by email Global user
SAML Session SAML \_saml_id ProxyID \_nameID \_assert_id \_art_id
====================================== ============= ===================================================================
.. _fieldstoindex:
List of fields to index by session type
---------------------------------------
========================== ======================================================================
Session Type Fields to index
========================== ======================================================================
Sessions (global) \_whatToTrace \_session_kind \_utime ipAddr \_httpSessionType user
Persistent sessions \_session\_kind \_httpSessionType \_session\_uid ipAddr \_whatToTrace
CAS sessions \_cas\_id pgtIou
SAML sessions \_session_kind \_utime \_saml_id ProxyID \_nameID \_assert_id \_art_id
OpenID Connect sessions \_session_kind \_utime
========================== ======================================================================
.. note::
If you have configured LemonLDAP::NG to use something other than
`_whatToTrace` as the main session identifier, you must replace
`_whatToTrace` with the new session field in the previous list
See Apache::Session::Browseable man page to see how use indexes.
.. attention::
\ *WHATTOTRACE* must be replaced by the attribute or
macro configured in the What To Trace parameter (REMOTE_USER). By
default: **\_whatToTrace**\
.. tip::
It is advised to use separate session backends for standard
sessions, SAML sessions and CAS sessions, in order to manage index
separately.
It is advised to use separate session backends for standard sessions, SAML
sessions and CAS sessions, in order to avoid unused indexes.
.. note::
Documentation below explains how set index on ipAddr and
\_whatToTrace. Adapt it to configure the index you need.
Available backends
------------------
Browseable NoSQL
----------------
You can use Redis and set up the database like explained in
:doc:`Redis session backend<nosqlsessionbackend>`.
You then just have to add the ``Index`` parameter in
``General parameters`` » ``Sessions`` » ``Session storage`` »
``Apache::Session module`` :
=================== ============ ====================
Required parameters
=================== ============ ====================
Name Comment Example
**server** Redis server 127.0.0.1:6379
**Index** Index \_whatToTrace ipAddr
=================== ============ ====================
Browseable SQL
--------------
.. note::
This documentation concerns PostgreSQL. Some adaptations are
needed with other databases. When using
Apache::Session::Browseable::Postgres, it
is strongly recommended to use version 1.3.1 at least. See `bug
1732 <https://gitlab.ow2.org/lemonldap-ng/lemonldap-ng/issues/1732>`__.
Prepare database
~~~~~~~~~~~~~~~~
Database must be prepared exactly like in
:ref:`SQL session backend<sqlsessionbackend-prepare-the-database>`
except that a field must be added for each data to index.
.. attention::
Data written to UNLOGGED tables is not written to the
WAL, which makes them considerably faster than ordinary tables. However,
they are not crash-safe: an unlogged table is automatically truncated
after a crash or unclean shutdown. The contents of an unlogged table are
also not replicated to standby servers. Any indexes created on an
unlogged table are automatically unlogged as well.
Apache::Session::Browseable::Postgres
example:
::
CREATE UNLOGGED TABLE sessions (
id varchar(64) not null primary key,
a_session text,
_whatToTrace text,
_session_kind text,
_utime bigint,
_httpSessionType text,
ipAddr text
);
CREATE INDEX uid1 ON sessions USING BTREE (_whatToTrace text_pattern_ops);
CREATE INDEX s1 ON sessions (_session_kind);
CREATE INDEX u1 ON sessions (_utime);
CREATE INDEX ip1 ON sessions USING BTREE (ipAddr);
CREATE INDEX h1 ON sessions (_httpSessionType);
.. attention::
For Session Explorer and one-off sessions, it is
recommended to use BTREE or any index method that indexes partial
content.
"id" fieds is set to ``varchar(64)`` (instead of char(32)) to use the
now recommended SHA256 hash algorithm. See
:doc:`Sessions<sessions>` for more details.
.. tip::
With new
Apache::Session::Browseable::PgHstore
and **PgJSON**, you don't need to declare indexes in ``CREATE TABLE``
since "json" and "hstore" type are browseable. You should anyway add
some indexes *(see manpage)*.
Manager
~~~~~~~
Go in the Manager and set the session module
(`Apache::Session::Browseable::MySQL <https://metacpan.org/pod/Apache::Session::Browseable::MySQL>`__
for MySQL) in ``General parameters`` » ``Sessions`` »
``Session storage`` » ``Apache::Session module`` and add the following
parameters (case sensitive):
=================== ================================================= =============================================================
Required parameters
=================== ================================================= =============================================================
Name Comment Example
**DataSource** The `DBI <https://metacpan.org/pod/DBI>`__ string dbi:Pg:database=lemonldap-ng
**UserName** The database username lemonldapng
**Password** The database password mysuperpassword
**Index** Index \_whatToTrace ipAddr \_session_kind \_utime \_httpSessionType
**TableName** Table name (optional) sessions
=================== ================================================= =============================================================
.. tip::
Apache::Session::Browseable::MySQL doesn't use locks so performances are
keeped.
For databases like PostgreSQL, don't forget to add "Commit" with a value
of 1
Browseable LDAP
---------------
Go in the Manager and set the session module to
``Apache::Session::Browseable::LDAP``. Then configure the options like
in :doc:`LDAP session backend<ldapsessionbackend>`.
You need to add the ``Index`` field and can also configure the
``ldapAttributeIndex`` field to set the attribute name where index
values will be stored.
======================== ================================= ===============================
Required parameters
======================== ================================= ===============================
Name Comment Example
**ldapServer** URI of the server ldap://localhost
**ldapConfBase** DN of sessions branch ou=sessions,dc=example,dc=com
**ldapBindDN** Connection login cn=admin,dc=example,dc=password
**ldapBindPassword** Connection password secret
**Index** Index list \_whatToTrace ipAddr
Optional parameters
Name Comment Default value
**ldapObjectClass** Objectclass of the entry applicationProcess
**ldapAttributeId** Attribute storing session ID cn
**ldapAttributeContent** Attribute storing session content description
**ldapAttributeIndex** Attribute storing index ou
**ldapVerify** Perform certificate validation require (use none to disable)
**ldapCAFile** Path of CA file bundle (system CA bundle)
**ldapCAPath** Perform CA directory (system CA bundle)
======================== ================================= ===============================
Security
--------
Restrict network access to the backend.
You can also use different user/password for your servers by overriding
parameters ``globalStorage`` and ``globalStorageOptions`` in
lemonldap-ng.ini file.
Performances
------------
Here are some recommended configurations:
**Browseable::Postgres**:
::
CREATE UNLOGGED TABLE sessions (
id varchar(64) not null primary key,
a_session text,
_whatToTrace text,
_session_kind text,
_utime bigint,
_httpSessionType text,
ipAddr text
);
CREATE INDEX uid1 ON sessions USING BTREE (_whatToTrace text_pattern_ops);
CREATE INDEX s1 ON sessions (_session_kind);
CREATE INDEX u1 ON sessions (_utime);
CREATE INDEX ip1 ON sessions USING BTREE (ipAddr);
CREATE INDEX h1 ON sessions (_httpSessionType);
**Browseable::MySQL**:
::
CREATE TABLE sessions (
id varchar(64) not null primary key,
a_session text,
_whatToTrace varchar(64),
_session_kind varchar(15),
user text,
_utime bigint,
ipAddr varchar(64)
);
CREATE INDEX uid1 ON sessions (_whatToTrace) USING BTREE;
CREATE INDEX _s1 ON sessions (_session_kind);
CREATE INDEX _u1 ON sessions (_utime);
CREATE INDEX ip1 ON sessions (ipAddr) USING BTREE;
.. toctree::
:maxdepth: 1
PgJSON Backend (recommended) <pgjsonsessionbackend>
browseablemysqlsessionbackend
browseableldapsessionbackend
nosqlsessionbackend

1
doc/sources/admin/index_sessiondb.rst
View File

@ -6,7 +6,6 @@ Sessions database
changesessionbackend
filesessionbackend
restsessionbackend
sqlsessionbackend
ldapsessionbackend
nosqlsessionbackend

2
doc/sources/admin/nosqlsessionbackend.rst
View File

@ -30,9 +30,9 @@ Name Comment Example
**sentinels** Redis sentinels list 127.0.0.1:26379,127.0.0.2:26379,127.0.0.3:26379
**password** password (== requirepass) ChangeMe
**select** Redis DB 1
**Index** Fields to index refer to :ref:`fieldstoindex`
============= =========================== ===============================================
Security
--------

110
doc/sources/admin/pgjsonsessionbackend.rst Normal file
View File

@ -0,0 +1,110 @@
PgJSON session backend
======================
This backend is the recommended one for production installations of LemonLDAP::NG.
Prerequisites
-------------
First, make sure you have installed the ``DBD::Pg`` perl module.
On Debian-based distributions ::
apt install libdbd-pg-perl
On Fedora-based distributions ::
yum install 'perl(DBD::Pg)'
The minimum required version of PostgreSQL is 9.3 with `support for JSON column types <https://www.postgresql.org/docs/9.3/functions-json.html>`__
Make sure you are using at least version 1.2.9 of ``Apache::Session::Browseable``, this might require installing it from Debian Backports or CPAN.
Create database schema
----------------------
Create the following tables. You may skip the session types you are not going to use, but you need at least ``sessions`` and ``psessions``
::
CREATE TABLE sessions (
id varchar(64) not null primary key,
a_session jsonb
);
CREATE INDEX i_s__whatToTrace ON sessions ((a_session ->> '_whatToTrace'));
CREATE INDEX i_s__session_kind ON sessions ((a_session ->> '_session_kind'));
CREATE INDEX i_s__utime ON sessions ((cast (a_session ->> '_utime' as bigint)));
CREATE INDEX i_s_ipAddr ON sessions ((a_session ->> 'ipAddr'));
CREATE INDEX i_s__httpSessionType ON sessions ((a_session ->> '_httpSessionType'));
CREATE INDEX i_s_user ON sessions ((a_session ->> 'user'));
CREATE TABLE psessions (
id varchar(64) not null primary key,
a_session jsonb
);
CREATE INDEX i_p__session_kind ON psessions ((a_session ->> '_session_kind'));
CREATE INDEX i_p__httpSessionType ON psessions ((a_session ->> '_httpSessionType'));
CREATE INDEX i_p__session_uid ON psessions ((a_session ->> '_session_uid'));
CREATE INDEX i_p_ipAddr ON psessions ((a_session ->> 'ipAddr'));
CREATE INDEX i_p__whatToTrace ON psessions ((a_session ->> '_whatToTrace'));
CREATE TABLE samlsessions (
id varchar(64) not null primary key,
a_session jsonb
);
CREATE INDEX i_a__session_kind ON samlsessions ((a_session ->> '_session_kind'));
CREATE INDEX i_a__utime ON samlsessions ((cast(a_session ->> '_utime' as bigint)));
CREATE INDEX i_a_ProxyID ON samlsessions ((a_session ->> 'ProxyID'));
CREATE INDEX i_a__nameID ON samlsessions ((a_session ->> '_nameID'));
CREATE INDEX i_a__assert_id ON samlsessions ((a_session ->> '_assert_id'));
CREATE INDEX i_a__art_id ON samlsessions ((a_session ->> '_art_id'));
CREATE INDEX i_a__saml_id ON samlsessions ((a_session ->> '_saml_id'));
CREATE TABLE oidcsessions (
id varchar(64) not null primary key,
a_session jsonb
);
CREATE INDEX i_o__session_kind ON oidcsessions ((a_session ->> '_session_kind'));
CREATE INDEX i_o__utime ON oidcsessions ((cast(a_session ->> '_utime' as bigint )));
CREATE TABLE cassessions (
id varchar(64) not null primary key,
a_session jsonb
);
CREATE INDEX i_c__session_kind ON cassessions ((a_session ->> '_session_kind'));
CREATE INDEX i_c__utime ON cassessions ((cast(a_session ->> '_utime' as bigint)));
CREATE INDEX i_c__cas_id ON cassessions ((a_session ->> '_cas_id'));
CREATE INDEX i_c_pgtIou ON cassessions ((a_session ->> 'pgtIou'));
LemonLDAP::NG configuration
---------------------------
Go in the Manager and set the session module to ``Apache::Session::Browseable::PgJSON`` for each session type you intend to use:
* ``General parameters`` » ``Sessions`` » ``Session storage`` » ``Apache::Session module``
* ``General parameters`` » ``Sessions`` » ``Persistent sessions`` » ``Apache::Session module``
* ``CAS Service`` » ``CAS sessions module name``
* ``OpenID Connect Service`` » ``Sessions`` » ``Sessions module name``
* ``SAML2 Service`` » ``Advanced`` » ``SAML sessions module name``
Then, set the following module options:
=================== ================================================= =============================================================
Required parameters
=================== ================================================= =============================================================
Name Comment Example
**DataSource** The `DBI <https://metacpan.org/pod/DBI>`__ string dbi:Pg:database=lemonldap-ng
**UserName** The database username lemonldapng
**Password** The database password mysuperpassword
**TableName** Table name (optional) sessions
**Commit** 1 This setting is mandatory for PostgreSQL to work
=================== ================================================= =============================================================
.. tip::
Unlike other browseable modules, Pg::JSON does not require an ``Index`` parameter

8
doc/sources/admin/start.rst
View File

@ -383,16 +383,16 @@ style modules are usable except for some features.
Backend Shareable :ref:`Session explorer<session-explorer>` :ref:`Session restrictions<session-restrictions>` Session expiration Comment
================================================================ ========= ================================================ ==================================================== ================== =================================================================================================================================================================================================
:doc:`File<filesessionbackend>` ✔ ✔ ✔ Not shareable between servers except if used in conjunction with :doc:`REST session backend<restsessionbackend>` or with a shared file system (NFS,...). Selected by default during installation.
:doc:`SQL<sqlsessionbackend>` ✔ ✔ ✔ ✔ Unoptimized for :doc:`session explorer<features>` and :doc:`single session<features>` features.
:doc:`LDAP<ldapsessionbackend>` ✔ ✔ ✔ ✔
:doc:`PgJSON<pgjsonsessionbackend>` ✔ ✔ ✔ ✔ Recommended backend for production installations
:doc:`Browseable MySQL<browseablemysqlsessionbackend>` ✔ ✔ ✔ ✔ Recommended for those who prefer MySQL
:doc:`Browseable LDAP<browseableldapsessionbackend>` ✔ ✔ ✔ ✔
:doc:`Redis<nosqlsessionbackend>` ✔ ✔ ✔ ✔ The fastest. Must be secured by network access control.
:doc:`MongoDB<mongodbsessionbackend>` ✔ ✔ ✔ ✔ Must be secured by network access control.
:doc:`Browseable (SQL, Redis or LDAP)<browseablesessionbackend>` ✔ ✔ ✔ ✔ **Optimized** for :doc:`session explorer<features>` and :doc:`single session<features>` features.
:doc:`SQL<sqlsessionbackend>` ✔ ✔ ✔ ✔ Unoptimized for :doc:`session explorer<features>` and :doc:`single session<features>` features.
:doc:`REST<restsessionbackend>` |new| ✔ ✔ ✔ ✔ Proxy backend to be used in conjunction with another session backend.
:doc:`SOAP<soapsessionbackend>` |deprecated| ✔ ✔ ✔ ✔ Proxy backend to be used in conjunction with another session backend.
================================================================ ========= ================================================ ==================================================== ================== =================================================================================================================================================================================================
.. tip::
You can migrate from one session backend to another using the