# Manage virtual hosts

LemonLDAP::NG configuration is build around Apache 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 My::Package

For example, a protected virtual host for a local application:

    <VirtualHost *:80>
            ServerName localsite.example.com

            PerlHeaderParserHandler My::Package

            DocumentRoot /var/www/localsite

            ErrorLog /var/log/apache2/localsite_error.log
            CustomLog /var/log/apache2/localsite_access.log combined

    </VirtualHost>

And a protected virtual host with LemonLDAP::NG as reverse proxy:

    <VirtualHost *:80>
            ServerName proxysite.example.com

            PerlHeaderParserHandler My::Package

            ProxyPreserveHost on
            ProxyPass / http://APPLICATION_IP/
            ProxyPassReverse / http://APPLICATION_IP/

            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

Using the reverse proxy mode, you will not have the `REMOTE_USER` environment variable set. Indeed, this variable is set by the Handler on the physical server hosting the Handler, and not on other servers where the Handler is not installed.

But this magic Apache configuration will let you transform the Auth-User HTTP header in `REMOTE_USER` envronment variable:

    SetEnvIfNoCase Auth-User "(.*)" REMOTE_USER=$1

## 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

There is a `default` access rule which is used if no other access rule match the current URL. Else, each access rule refers to an URL pattern.

Access rule value is an expression, evaluated for each request, and returning 1 if user is authorized, 0 else.

Access rules examples:

    ^/site/.*$ => $uid eq "admin" or $groups =~ /\bgroup2\b/
    ^/(js|css) => accept
    default => deny

Access rules accepts special targets:

- accept: all authenticated users can pass
- deny: nobody is welcomed
- unprotect: all is open!
- logout_sso: request is not forwarded to application, SSO session is closed
- logout_app: request is forwarded to application, SSO session remains open
- logout_app_sso: request is forwarded to application, SSO session is closed

The logout* targets can have an URL as parameter. By default, user will be redirected on portal if no URL defined, or on the specified URL if any.

### HTTP headers

Headers are sent to application, they are not visible to users.

Headers value can be a single session key or a full Perl expression. For example:

    Auth-User => $uid
    Unit => 'Unit-'.$ou

By default, SSO cookie is hidden, so protected applications cannot get SSO session key. But you can forward this key if it is really needed:

    Session-ID => $_session_id

### POST data

Add link to form replay page

### Options

Two options are available:

- Port
- HTTPS

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.