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

Improve doc (#2685)

This commit is contained in:
Christophe Maudoux 2022-02-05 00:14:19 +01:00
parent caa6fc9df9
commit 398f729da9
11 changed files with 82 additions and 78 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

0
doc/sources/admin/handlerauthbasic.rst → doc/sources/admin/authbasichandler.rst
View File

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

@ -51,7 +51,7 @@ Then, go in ``Choice Parameters``:
``lmAuth``)
- **Allowed modules**: click on ``New chain`` to add a choice.
- **Choice used for password authentication**: authentication module used by
:doc:`AuthBasic handler<handlerauthbasic>` and :ref:`OAuth2.0 Password Grant <resource-owner-password-grant>`
:doc:`AuthBasic handler<authbasichandler>` and :ref:`OAuth2.0 Password Grant <resource-owner-password-grant>`
- **FindUser plugin parameter**: authentication module called by
Find user plugin (:doc:`Find user plugin<finduser>`)

17
doc/sources/admin/configvhost.rst
View File

@ -38,7 +38,7 @@ Example of a protected virtual host for a local application:
</VirtualHost>
Reverse proxy
Reverse-Proxy
~~~~~~~~~~~~~
Example of a protected virtual host with LemonLDAP::NG as reverse proxy:
@ -258,7 +258,7 @@ Example of a protected virtual host for a local application:
.. _reverse-proxy-1:
Reverse proxy
Reverse-Proxy
~~~~~~~~~~~~~
- Example of a protected reverse-proxy:
@ -452,7 +452,7 @@ A virtual host contains:
- Access rules: check user's right on URL patterns
- HTTP headers: forge information sent to protected applications
- POST data: use form replay
- Options: redirection port and protocol
- Options: redirection port, protocol, Handler type, aliases,required authentication level,...
Access rules and HTTP headers
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -464,7 +464,7 @@ application by LL::NG.
.. attention::
With **Nginx**-based ReverseProxy, header directives can
With **Nginx**-based Reverse-Proxy, header directives can
be appended by a LUA script.
To send more than **15** headers to protected applications,
@ -507,9 +507,12 @@ Some options are available:
Provide a comma separated parameters list with custom function path and args.
Args can be vars or session attributes, macros, ...
By example: My::accessToTrace, Doctor, Who, _whatToTrace
- **Type**: handler type (normal,
:doc:`ServiceToken Handler<servertoserver>`,
:doc:`DevOps Handler<devopshandler>`,...)
- **Type**: handler type (:ref:`Main<presentation-kinematics>`,
:doc:`AuthBasic<authbasichandler>`,
:doc:`ServiceToken<servertoserver>`,
:doc:`DevOps<devopshandler>`,
:doc:`DevOpsST<devopssthandler>`,
:doc:`OAuth2<oauth2handler>`,...)
- **Required authentication level**: this option avoids to reject user with
a rule based on ``$_authenticationLevel``. When user has not got the
required level, he is redirected to an upgrade page in the portal.

16
doc/sources/admin/devopshandler.rst
View File

@ -1,7 +1,7 @@
DevOps Handler
==============
This Handler is designed to retrieve vhost configuration from the website
This Handler is designed to retrieve VHost configuration from the website
itself, not from LL:NG configuration. Rules and headers are set in a
**rules.json** file stored at the website root directory (ie
``http://website/rules.json``). This file looks like:
@ -23,12 +23,14 @@ If this file is not found, the default rule "accept" is applied and just
No specific configuration is required except that:
- you have to choose this specific handler (directly by using
``VHOSTTYPE`` environment variable or in VHost options)
- you can set the loopback URL needed by the DevOps handler to get
``/rules.json`` or use ``RULES_URL`` parameter to set JSON file path
(see :doc:`SSO as a Service<ssoaas>`). Default to
``http://127.0.0.1:<server-port>``
- you have to select ``DevOps`` handler type either with
``VHOSTTYPE`` environment variable or in VHost options
- you can set in VHost options the loopback URL requested by
the DevOps handler to retrieve ``/rules.json`` or use
``RULES_URL`` environment variable to set JSON file location.
Default to ``http://127.0.0.1:<server-port>``
- HTTPS or redirection port can be set by using
``HTTP_REDIRECT`` or ``PORT_REDIRECT`` environment variables.
.. attention::

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

@ -25,7 +25,7 @@ Plack servers protection or Nginx/\ :doc:`SSOaaS<ssoaas>` FastCGI/uWSGI server S
Types are:
- *(Main)*: link between Main and platform
- :doc:`AuthBasic<handlerauthbasic>`
- :doc:`AuthBasic<authbasichandler>`
- :doc:`CDA<cda>`
- :doc:`DevOps<devopshandler>`
- :doc:`DevOps+ServiceToken<devopssthandler>`

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

@ -18,7 +18,7 @@ Advanced features
register
logoutforward
securetoken
handlerauthbasic
authbasichandler
safejail
loginhistory
fastcgi

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

@ -4,7 +4,7 @@ Handlers
.. toctree::
:maxdepth: 1
handlerauthbasic
authbasichandler
cda
ssoaas
oauth2handler

30
doc/sources/admin/psgi.rst
View File

@ -1,7 +1,7 @@
Advanced PSGI usage
===================
LLNG is build on `Plack <http://plackperl.org/>`__, so it can be used
LL::NG is built on `Plack <http://plackperl.org/>`__, so it can be used
with any compatible server:
- `Starman <https://metacpan.org/pod/starman>`__
@ -46,19 +46,18 @@ to replace exactly FastCGI server. You can use it :
.. attention::
Starman, Twiggy,... are HTTP servers, not FastCGI ones
!
Starman, Twiggy,... are HTTP servers, not FastCGI ones!
You can also replace only a part of it to create a specialized FastCGI
server (portal,...). Look at ``llng-server.psgi`` example and take the
part you want to use.
There are also some other psgi files in examples directory.
There are also some other PSGI files in examples directory.
LLNG FastCGI Server
~~~~~~~~~~~~~~~~~~~
LL::NG FastCGI Server
~~~~~~~~~~~~~~~~~~~~~
``llng-fastcgi-server`` can be launched with the following options:
``llng-fastcgi-server`` can be started with the following options:
==================== ===================== ===================== ==========================================================================================
Command-line options Environment variable Explanation
@ -98,16 +97,15 @@ FCGI::Engine::ProcManager
Using uWSGI
~~~~~~~~~~~
You must install uWSGI PSGI plugin. Then for example, launch
You have to install uWSGI PSGI plugin. Then for example, start
llng-server.psgi *(simple example)*:
::
.. code-block:: shell
/usr/bin/uwsgi --plugins psgi --socket :5000 --uid www-data --gid www-data --psgi /usr/share/lemonldap-ng/llng-server/llng-server.psgi
You will find in LLNG Nginx configuration files some comments that
explain how to configure Nginx to use uWSGI instead of LLNG FastCGI
server.
You will find in LL::NG Nginx configuration files some comments that
explain how to configure Nginx to use uWSGI instead of LL::NG FastCGI server.
Using Debian lemonldap-ng-uwsgi-app package
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -148,7 +146,7 @@ and/or Nginx init files several options. Example:
.. note::
Nginx natively includes support for upstream servers speaking the uwsgi protocol since version 0.8.40.
To improve performances, you can switch from a TCP socket to an Unix Domain Socket by editing
To improve performances, you can switch from a TCP socket to an UDS socket by editing
``llng-server.yaml``:
.. code-block:: ini
@ -161,7 +159,7 @@ and/or Nginx init files several options. Example:
.. code-block:: nginx
# OR TO USE uWSGI
# With uWSGI
include /etc/nginx/uwsgi_params;
uwsgi_pass unix:///tmp/uwsgi.sock;
uwsgi_param LLTYPE psgi;
@ -174,8 +172,8 @@ and/or Nginx init files several options. Example:
Protect a PSGI application
--------------------------
LLNG provides ``Plack::Middleware::Auth::LemonldapNG`` that can be used
to protect any PSGI application: it acts exactly like a LLNG handler.
LL::NG provides ``Plack::Middleware::Auth::LemonldapNG`` that can be used
to protect any PSGI application: it works exactly like a LL::NG handler.
Simple example:
.. code-block:: perl

81
doc/sources/admin/ssoaas.rst
View File

@ -1,4 +1,4 @@
SSO as a service (SSOaaS)
SSO as a Service (SSOaaS)
=========================
Our concept of SSOaaS
@ -13,45 +13,46 @@ Access management provides 3 services:
results)*
LL::NG affords all these services (except application logs of course,
but headers are provided to permit this).
but headers are provided to allow this).
Headers setting is an another LL::NG service. LL::NG can provide any
user attributes to an application (see
:doc:`Rules and headers<writingrulesand_headers>`)
user attributes to an application
(see :doc:`Rules and headers<writingrulesand_headers>`)
``*aaS`` means that application can drive underlying layer (IaaS for
infrastructure, PaaS for platform,…). So for us, ``SSOaaS`` must provide
the ability for an app to manage authorizations and choose user
attributes to set. Authentication can not be really ``*aaS``: app must
just use it, not manage it.
the ability for an application to manage authorizations and choose user
attributes to set. Authentication can not be really ``*aaS``: application
must just use it but not manage it.
LL::NG affords some features that can be used for providing SSO as a
Service: a web application can manage its rules and headers. Docker or
VM images (Nginx only) includes LL::NG Nginx configuration that aims to
a global
:ref:`LL::NG authorization server<platformsoverview-external-servers-for-nginx>`.
By default, all authenticated users can access and one header is set:
``Auth-User``. If application defines a RULES_URL parameter that refers to
service. So a web application can manage its rules and headers.
Docker or VM images (Nginx only) includes LL::NG Nginx configuration that
aims to a
:ref:`central LL::NG authorization server<platformsoverview-external-servers-for-nginx>`.
By default, all authenticated users can access and just one header is set:
``Auth-User``. If application defines a ``RULES_URL`` parameter that refers to
a JSON file, authorization server will read it, apply specified rules
and set required headers (see :doc:`DevOps Handler<devopshandler>`).
There are two different architectures to do this:
Two different kind of architecture are existing to do this:
- Using a :doc:`global FastCGI (or uWSGI) server<psgi>`
- Using front reverse-proxies *(some cloud installations use
- Using a :doc:`central FastCGI (or uWSGI) server<psgi>`
- Using front Reverse-Proxies *(some cloud or HA installations use
reverse-proxies in front-end)*
.. note::
Some requests can be dropped by the FastCGI/uWSGI server.
Example below with uWSGI server to avoid Load Balancer health check requests
being forwarded to DevOps Handler:
Some requests can be dropped by the central FastCGI/uWSGI server.
Example below with an uWSGI server to prevent Load Balancer health check requests
being forwarded to the central DevOps Handler:
```route-remote-addr = ^127\.0\.0\.25[34]$ break: 403 Forbidden for IP ${REMOTE_ADDR}```
Example of a global FastCGI architecture:
Example of a central FastCGI architecture:
|image0|
@ -60,17 +61,17 @@ In both case, Handler type must be set to :doc:`DevOps<devopshandler>`.
Examples of webserver configuration for Docker/VM images
--------------------------------------------------------
Using a global FastCGI (or uWSGI) server
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Using a Central FastCGI (or uWSGI) Server
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Nginx
^^^^^
Examples below are web server templates (Nginx only) configured to
request authorization from a central FastCGI server.
With an uWSGI central server, use 'uwsgi_param' directive (Nginx only):
Examples below are web server templates customized for
requesting authorization from a central FastCGI server.
With a central uWSGI server (Nginx only), use 'uwsgi_param' directive:
.. code::
.. code-block:: nginx
server {
listen <port>;
@ -78,7 +79,7 @@ With an uWSGI central server, use 'uwsgi_param' directive (Nginx only):
location = /lmauth {
internal;
include /etc/nginx/fastcgi_params;
# Pass authorization requests to Central FastCGI server:
# Pass authorization requests to central FastCGI server
fastcgi_pass 10.1.2.3:9090;
fastcgi_param VHOSTTYPE DevOps;
# Drop post datas
@ -89,11 +90,11 @@ With an uWSGI central server, use 'uwsgi_param' directive (Nginx only):
# Keep original request (LLNG server will received /lmauth)
fastcgi_param X_ORIGINAL_URI $original_uri;
# Set redirection params
# Set redirection parameters
fastcgi_param HTTPS_REDIRECT "$https";
fastcgi_param PORT_REDIRECT $server_port;
# Set dynamically rules (LL::NG will poll it every 10 mn)
# Set rules dynamically (LL::NG will poll it every 10 mn)
fastcgi_param RULES_URL http://rulesserver/my.json;
}
location /rules.json {
@ -109,7 +110,7 @@ With an uWSGI central server, use 'uwsgi_param' directive (Nginx only):
error_page 401 $lmlocation;
include /etc/nginx/nginx-lua-headers.conf;
# ...
# Example with php-fpm:
# Example with php-fpm
include snippets/fastcgi-php.conf;
fastcgi_pass unix:/var/run/php/php7.0-fpm.sock;
}
@ -121,12 +122,12 @@ With an uWSGI central server, use 'uwsgi_param' directive (Nginx only):
Apache
^^^^^^
There is an experimental FastCGI client in LL::NG. You just have to
install LemonLDAP::NG handler and FCGI::Client. Then, add this in
your apache2.conf, web applications or reverse-proxies.
LL::NG provides an experimental FastCGI client. You have to
install LemonLDAP::NG handler (LL::NG FastCGI client),
FCGI::Client (Perl dependency) and Mod_Perl2 (Apache module)
used for parsing HTTP headers.
Then, add this in your apache2.conf web applications or reverse-proxies.
The following configuration example assumes that you are in a "central
FastCGI" configuration.
.. code-block:: apache
@ -134,7 +135,7 @@ FastCGI" configuration.
ServerName app.tls
PerlHeaderParserHandler Lemonldap::NG::Handler::ApacheMP2::FCGIClient
# This must point to the central FastCGI server
# The central FastCGI server socket
PerlSetVar LLNG_SERVER 192.0.2.1:9090
# Declare this vhost as a DevOps protected vhost. So you do not have
@ -224,15 +225,15 @@ Simple example:
$app;
};
Using front reverse-proxies
Using front Reverse-Proxies
~~~~~~~~~~~~~~~~~~~~~~~~~~~
This is a simple Nginx configuration file. It looks like a standard
LL::NG nginx configuration file except for:
LL::NG Nginx configuration file except for:
- VHOSTTYPE parameter forced to use DevOps handler
- /rules.json must not be protected by LL::NG but by the web server
itself
- /rules.json do not have to be protected by LL::NG
but by the web server itself.
This configuration handles ``*.dev.sso.my.domain`` URL and forwards
authenticated requests to ``<vhost>.internal.domain``. Rules can be

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

@ -315,7 +315,7 @@ Handlers are software control agents to be installed on your web servers
Handler type Apache LLNG FastCGI/uWSGI server (Nginx, or :doc:`SSOaaS<ssoaas>`) `Plack servers <https://plackperl.org>`__ Node.js ( `express apps <http://expressjs.com/>`__\ or :doc:`SSOaaS<ssoaas>`) :doc:`Self protected apps<selfmadeapplication>` Comment
==================================================================== ========== ============================================================= =========================================== ================================================================================== =============================================== ======================================================================================================================
Main *(default handler)* ✔ ✔ ✔ :doc:`Partial<nodehandler>` ** [16]_ ** ✔
:doc:`AuthBasic<handlerauthbasic>` ✔ ✔ ✔ ✔ Designed for some server-to-server applications
:doc:`AuthBasic<authbasichandler>` ✔ ✔ ✔ ✔ Designed for some server-to-server applications
:doc:`CDA<cda>` ✔ ✔ ✔ ✔ For Cross Domain Authentication
:doc:`DevOps<devopshandler>` (:doc:`SSOaaS<ssoaas>`) |new| ✔ ✔ ✔ ✔ Allows application developers to define their own rules and headers inside their applications
:doc:`DevOpsST<devopssthandler>` (:doc:`SSOaaS<ssoaas>`) |new| ✔ ✔ ✔ ✔ Enables both :doc:`DevOps<devopshandler>` and :doc:`Service Token<servertoserver>`
@ -464,7 +464,7 @@ Advanced features
- :doc:`Create an account (self service)<register>`
- :doc:`Forward logout to applications<logoutforward>`
- :doc:`Secure Token Handler<securetoken>`
- :doc:`AuthBasic Handler<handlerauthbasic>`
- :doc:`AuthBasic Handler<authbasichandler>`
- :doc:`SSO as a Service<ssoaas>` *(SSOaaS)* |new|
- :doc:`Handling server webservice calls<servertoserver>` |new|
- `LemonLDAP::NG kubernetes

4
doc/sources/admin/upgrade_2_0.rst
View File

@ -170,7 +170,7 @@ Handlers
- :doc:`CDA<cda>`,
:doc:`ZimbraPreAuth<applications/zimbra>`,
:doc:`SecureToken<securetoken>` and
:doc:`AuthBasic<handlerauthbasic>` are now
:doc:`AuthBasic<authbasichandler>` are now
:doc:`Handler Types<handlerarch>`. So there is no
more special file to load: you just have to choose "VirtualHost type"
in the manager/VirtualHosts.
@ -222,7 +222,7 @@ SOAP/REST services
.. attention::
\ :doc:`AuthBasic Handler<handlerauthbasic>` uses now
\ :doc:`AuthBasic Handler<authbasichandler>` uses now
REST services instead of SOAP.
CAS