Rework Browseable docs (#2320)
This commit is contained in:
parent
7e48ec702e
commit
667e7f09c4
35
doc/sources/admin/browseableldapsessionbackend.rst
Normal file
35
doc/sources/admin/browseableldapsessionbackend.rst
Normal 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
120
doc/sources/admin/browseablemysqlsessionbackend.rst
Normal 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`
|
||||||
|
=================== ================================================= =============================================================
|
|
@ -7,250 +7,53 @@ Presentation
|
||||||
Browseable session backend
|
Browseable session backend
|
||||||
(`Apache::Session::Browseable <https://metacpan.org/pod/Apache::Session::Browseable>`__)
|
(`Apache::Session::Browseable <https://metacpan.org/pod/Apache::Session::Browseable>`__)
|
||||||
works exactly like Apache::Session::\* corresponding module but add
|
works exactly like Apache::Session::\* corresponding module but add
|
||||||
index that increase :ref:`session explorer<session-explorer>` and
|
index that increase the speed of some operations. It is recommended in production deployments.
|
||||||
: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.
|
|
||||||
|
|
||||||
|
|
||||||
.. note::
|
.. note::
|
||||||
|
|
||||||
Without index, LL::NG will have to retrieve all sessions stored in
|
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
|
backend and deserialize then filter each of them.
|
||||||
wil be able to get only wanted sessions from the backend.
|
|
||||||
|
|
||||||
The following table list fields to index depending on the feature you
|
The following table list fields to index for each session type:
|
||||||
want to increase performance:
|
|
||||||
|
|
||||||
====================================== ============= ===================================================================
|
|
||||||
Feature Session Type Fields to index
|
.. _fieldstoindex:
|
||||||
====================================== ============= ===================================================================
|
|
||||||
Database cleanup *(cron)* All \_session_kind \_utime
|
List of fields to index by session type
|
||||||
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
|
Session Type Fields to index
|
||||||
SAML Session SAML \_saml_id ProxyID \_nameID \_assert_id \_art_id
|
========================== ======================================================================
|
||||||
====================================== ============= ===================================================================
|
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.
|
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::
|
.. tip::
|
||||||
|
|
||||||
It is advised to use separate session backends for standard
|
It is advised to use separate session backends for standard sessions, SAML
|
||||||
sessions, SAML sessions and CAS sessions, in order to manage index
|
sessions and CAS sessions, in order to avoid unused indexes.
|
||||||
separately.
|
|
||||||
|
|
||||||
|
|
||||||
.. note::
|
|
||||||
|
|
||||||
Documentation below explains how set index on ipAddr and
|
Available backends
|
||||||
\_whatToTrace. Adapt it to configure the index you need.
|
------------------
|
||||||
|
|
||||||
Browseable NoSQL
|
.. toctree::
|
||||||
----------------
|
:maxdepth: 1
|
||||||
|
|
||||||
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;
|
|
||||||
|
|
||||||
|
PgJSON Backend (recommended) <pgjsonsessionbackend>
|
||||||
|
browseablemysqlsessionbackend
|
||||||
|
browseableldapsessionbackend
|
||||||
|
nosqlsessionbackend
|
||||||
|
|
|
@ -6,7 +6,6 @@ Sessions database
|
||||||
|
|
||||||
changesessionbackend
|
changesessionbackend
|
||||||
filesessionbackend
|
filesessionbackend
|
||||||
restsessionbackend
|
|
||||||
sqlsessionbackend
|
sqlsessionbackend
|
||||||
ldapsessionbackend
|
ldapsessionbackend
|
||||||
nosqlsessionbackend
|
nosqlsessionbackend
|
||||||
|
|
|
@ -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
|
**sentinels** Redis sentinels list 127.0.0.1:26379,127.0.0.2:26379,127.0.0.3:26379
|
||||||
**password** password (== requirepass) ChangeMe
|
**password** password (== requirepass) ChangeMe
|
||||||
**select** Redis DB 1
|
**select** Redis DB 1
|
||||||
|
**Index** Fields to index refer to :ref:`fieldstoindex`
|
||||||
============= =========================== ===============================================
|
============= =========================== ===============================================
|
||||||
|
|
||||||
|
|
||||||
Security
|
Security
|
||||||
--------
|
--------
|
||||||
|
|
||||||
|
|
110
doc/sources/admin/pgjsonsessionbackend.rst
Normal file
110
doc/sources/admin/pgjsonsessionbackend.rst
Normal 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
|
|
@ -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
|
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:`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:`PgJSON<pgjsonsessionbackend>` ✔ ✔ ✔ ✔ Recommended backend for production installations
|
||||||
:doc:`LDAP<ldapsessionbackend>` ✔ ✔ ✔ ✔
|
: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:`Redis<nosqlsessionbackend>` ✔ ✔ ✔ ✔ The fastest. Must be secured by network access control.
|
||||||
:doc:`MongoDB<mongodbsessionbackend>` ✔ ✔ ✔ ✔ 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:`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.
|
:doc:`SOAP<soapsessionbackend>` |deprecated| ✔ ✔ ✔ ✔ Proxy backend to be used in conjunction with another session backend.
|
||||||
================================================================ ========= ================================================ ==================================================== ================== =================================================================================================================================================================================================
|
================================================================ ========= ================================================ ==================================================== ================== =================================================================================================================================================================================================
|
||||||
|
|
||||||
|
|
||||||
.. tip::
|
.. tip::
|
||||||
|
|
||||||
You can migrate from one session backend to another using the
|
You can migrate from one session backend to another using the
|
||||||
|
|
Loading…
Reference in New Issue
Block a user