Manage virtual hosts

LemonLDAP::NG configuration is build around Apache or Nginx virtual hosts. Each virtual host is a protected resource, with access rules, headers, POST data and options.

Apache configuration

To protect a virtual host in Apache, the LemonLDAP::NG Handler must be activated (see Apache global configuration).

Then you can take any virtual host, and simply add this line to protect it:

PerlHeaderParserHandler Lemonldap::NG::Handler

Hosted application

Example of a protected virtual host for a local application:

<VirtualHost *:80>
        ServerName localsite.example.com
 
        PerlHeaderParserHandler Lemonldap::NG::Handler
 
        DocumentRoot /var/www/localsite
 
        ErrorLog /var/log/apache2/localsite_error.log
        CustomLog /var/log/apache2/localsite_access.log combined
 
</VirtualHost>

Reverse proxy

Example of a protected virtual host with LemonLDAP::NG as reverse proxy:

<VirtualHost *:80>
        ServerName application.example.com
 
        PerlHeaderParserHandler Lemonldap::NG::Handler
 
        # Reverse-Proxy
        ProxyPass / http://private-name/
        # Change "Location" header in redirections
        ProxyPassReverse / http://private-name/
        # Change domain cookies
        ProxyPassReverseCookieDomain private-name application.example.com
 
        ErrorLog /var/log/apache2/proxysite_error.log
        CustomLog /var/log/apache2/proxysite_access.log combined
</VirtualHost>

Same with remote server configured with the same host name:

<VirtualHost *:80>
        ServerName application.example.com
 
        PerlHeaderParserHandler Lemonldap::NG::Handler
 
        # Reverse-Proxy
        ProxyPass / http://APPLICATION_IP/
 
        ProxyPreserveHost on
 
        ErrorLog /var/log/apache2/proxysite_error.log
        CustomLog /var/log/apache2/proxysite_access.log combined
</VirtualHost>
The ProxyPreserveHost directive will forward the Host header to the protected application.
To learn more about using Apache as reverse-proxy, see Apache documentation.
Some applications need the REMOTE_USER environment variable to get the connected user, which is not set in reverse-proxy mode. In this case, see how convert header into environment variable.

Add a floating menu

A little floating menu can be added to application with this simple Apache configuration:

PerlModule Lemonldap::NG::Handler::Menu
PerlOutputFilterHandler Lemonldap::NG::Handler::Menu->run

Pages where this menu is displayed can be restricted, for example:

<Location /var/www/html/index.php>
PerlOutputFilterHandler Lemonldap::NG::Handler::Menu->run
</Location>
You need to disable mod_deflate to use the floating menu

Nginx configuration

To protect a virtual host in Nginx, the LemonLDAP::NG FastCGI server must be launched (see LemonLDAP::NG FastCGI server).

Then you can take any virtual host and modify it:

  • Declare the /lmauth endpoint
  location = /lmauth {
    internal;
    include /etc/nginx/fastcgi_params;
    fastcgi_pass unix:/var/run/llng-fastcgi-server/llng-fastcgi.sock;
 
    # Drop post datas
    fastcgi_pass_request_body  off;
    fastcgi_param CONTENT_LENGTH "";
 
    # Keep original hostname
    fastcgi_param HOST $http_host;
 
    # Keep original request (LLNG server will received /llauth)
    fastcgi_param X_ORIGINAL_URI  $request_uri;
  }
  • Protect the application (/ or /path/to/protect):
  location /path/to/protect {
    auth_request /lmauth;
    auth_request_set $lmremote_user $upstream_http_lm_remote_user;
    auth_request_set $lmlocation $upstream_http_location;
    # Uncomment this if CDA is used
    #auth_request_set $cookie_value $upstream_http_set_cookie;
    #add_header Set-Cookie $cookie_value;
    error_page 401 $lmlocation;
    try_files $uri $uri/ =404;
 
    ...
  }
  • Use LUA or set manually the headers:
  location /path/to/protect {
 
    ...
 
    # IF LUA IS SUPPORTED
    #include /etc/lemonldap-ng/nginx-lua-headers.conf;
 
    # ELSE
    # Set manually your headers
    #auth_request_set $authuser $upstream_http_auth_user;
    #proxy_set_header Auth-User $authuser;
    # OR
    #fastcgi_param HTTP_AUTH_USER $authuser;
 
    # Then (if LUA not supported), change cookie header to hide LLNG cookie
    #auth_request_set $lmcookie $upstream_http_cookie;
    #proxy_set_header Cookie: $lmcookie;
    # OR in the corresponding block
    #fastcgi_param HTTP_COOKIE $lmcookie;
 
    # Set REMOTE_USER (for FastCGI apps only)
    #fastcgi_param REMOTE_USER $lmremote_user;
  }

Hosted application

Example of a protected virtual host for a local application:

# Log format
include /path/to/lemonldap-ng/nginx-lmlog.conf;
server {
  listen 80;
  server_name myserver;
  root /var/www/html;
  # Internal authentication request
  location = /lmauth {
    internal;
    include /etc/nginx/fastcgi_params;
    fastcgi_pass /path/to/llng-fastcgi-server.sock;
    # Drop post datas
    fastcgi_pass_request_body  off;
    fastcgi_param CONTENT_LENGTH "";
    # Keep original hostname
    fastcgi_param HOST $http_host;
    # Keep original request (LLNG server will received /llauth)
    fastcgi_param X_ORIGINAL_URI  $request_uri;
  } 
 
  # Client requests
  location ~ \.php$ {
    auth_request /lmauth;
    auth_request_set $lmremote_user $upstream_http_lm_remote_user;
    auth_request_set $lmlocation $upstream_http_location;
    error_page 401 $lmlocation;
    try_files $uri $uri/ =404;
    include fastcgi_params;
    try_files $fastcgi_script_name =404;
    fastcgi_pass /path/to/php-fpm/socket;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    fastcgi_intercept_errors on;
    fastcgi_split_path_info ^(.+\.php)(/.+)$;
    fastcgi_hide_header X-Powered-By;
 
    ##################################
    # PASSING HEADERS TO APPLICATION #
    ##################################
    # IF LUA IS SUPPORTED
    #include /path/to/nginx-lua-headers.conf
 
    # ELSE
    # Set manually your headers
    #auth_request_set $authuser $upstream_http_auth_user;
    #fastcgi_param HTTP_AUTH_USER $authuser;
  }
  location / {
    try_files $uri $uri/ =404;
  }
}

Reverse proxy

Example of a protected reverse-proxy:

# Log format
include /path/to/lemonldap-ng/nginx-lmlog.conf;
server {
  listen 80;
  server_name myserver;
  root /var/www/html;
  # Internal authentication request
  location = /lmauth {
    internal;
    include /etc/nginx/fastcgi_params;
    fastcgi_pass /path/to/llng-fastcgi-server.sock;
    # Drop post datas
    fastcgi_pass_request_body  off;
    fastcgi_param CONTENT_LENGTH "";
    # Keep original hostname
    fastcgi_param HOST $http_host;
    # Keep original request (LLNG server will received /llauth)
    fastcgi_param X_ORIGINAL_URI  $request_uri;
  } 
 
  # Client requests
  location / {
    auth_request /lmauth;
    auth_request_set $lmremote_user $upstream_http_lm_remote_user;
    auth_request_set $lmlocation $upstream_http_location;
    error_page 401 $lmlocation;
 
    proxy_pass http://remote.server/;
    include /etc/nginx/proxy_params;
 
    ##################################
    # PASSING HEADERS TO APPLICATION #
    ##################################
    # IF LUA IS SUPPORTED
    #include /path/to/nginx-lua-headers.conf
 
    # ELSE
    # Set manually your headers
    #auth_request_set $authuser $upstream_http_auth_user;
    #proxy_set_header HTTP_AUTH_USER $authuser;
  }
}

LemonLDAP::NG configuration

An apache virtual host protected by LemonLDAP::NG Handler must be registered in LemonLDAP::NG configuration.

To do this, use the Manager, and go in Virtual Hosts branch. You can add, delete or modify a virtual host here.

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

Access rules and HTTP headers

See Writing rules and headers to learn how to configure access control and HTTP headers sent to application by LL::NG.

POST data

See Form replay to learn how to configure form replay to POST data on protected applications.

Options

Some options are available:

  • Port
  • HTTPS
  • Maintenance mode

These options are used to build redirection URL (when user is not logged, or for CDA requests). By default, default values are used. These options are only here to override default values.