Larpe Administrator Guide¶

Contenu
Larpe Administrator Guide

Overview¶

Larpe is a Liberty Alliance Reverse Proxy. It allows any service provider (that is a website) to use Liberty Alliance features (Identity federation, Single Sign On and Single Logout) without changing the code of the service provider itself. It uses the Lasso library which is certified by the Liberty Alliance consortium.

Licenses¶

Lasso and Larpe are released under the terms of the GNU GPL license.

Sites tested with Larpe¶

The following site engines have been tested and fully work with Larpe (non-exhaustive) :

Mediawiki (ex: http://fr.wikipedia.org/wiki/Accueil) ;
Sympa (ex : http://demo.sympa.org/sympa) ;
Egroupware (ex: http://www.stylite.de/egroupware_demo) ;
Docuwiki (ex: http://www.dokuwiki.org/dokuwiki);
GForge (ex: http://gforge.org/gf/project/test/) ;
Dacode (ex: http://linuxfr.org/pub/) ;
Iconito (ex: http://demo.iconito.fr/index.php?module=kernel) ;
Espace-famille Concerto (ex: http://demonstration.espace-famille.net/demo/index.do) ;
Agirhe (ex: http://www.agirhe-cdg.fr/accueil.aspx) ;
Ciril net RH ;
Integra RH (Pré-remplissage de formulaires) ;

as well as other specific and not public sites.

Installation¶

Required softwares¶

Larpe needs the following softwares:

Lasso (0.6.3 or later) with its Python binding;
Python (2.3 or later);
Python SCGI;
Quixote (2.0 or later);
Apache (2.0 or later) and the following modules: * Proxy; * Proxy HTML; * Proxy HTTP (for Apache 2.2 only); * SCGI; * Python; * Rewrite; * Headers;
libxml2.
You will also need a Liberty Alliance Identity Provider, be it on the same server or not. We recommend [[http://authentic.labs.libre-entreprise.org/|Authentic]] for that need.

Installation on Debian GNU/Linux Sarge¶

Add the following line in the file /etc/apt/sources.list, this will give you access to the repository where Larpe is stored:

deb http://deb.entrouvert.org/ sarge main

As root type:

# apt-get update
# apt-get install larpe

Installation on another GNU/Linux distribution¶

First install these softwares:

Python (2.4 or later);
Python SCGI;
Apache (2.0 or later) and the following modules: * Proxy HTML; * SCGI; * Python;
libxml2.

Then download and install these additional softwares:

Uncompress the sources you have downloaded

$ tar xzf larpe*.tar.gz
$ cd larpe*

Check the few variables at the begining of the Makefile and change them if needed.

Then install Larpe, as root:

# make install

Larpe is installed (but not configured yet), you can run it with:

# su www-data
$ /usr/sbin/larpectl.py start

You may want to create an init.d script to start it at boot time later.

When you want to uninstall Larpe, just type, as root:

# make uninstall

Apache 2 configuration¶

Preamble for other distributions than Debian¶

Load the following Apache 2 modules, using your distribution specific tools :

proxy;
proxy_html;
proxy_http (for Apache 2.2 only);
scgi;
mod_python;
rewrite;
headers.
If it is your first installation of Larpe, the file /etc/apache2/sites-available/apache2-vhost-larpe will not exist. Copy it from Larpe sources, as root:

# cp apache2-vhost-larpe /etc/apache2/sites-available/apache2-vhost-larpe

For all distributions¶

Edit the file /etc/apache2/sites-available/apache2-vhost-larpe to configure Apache 2 for Larpe. You will see these lines:

ServerName localhost
ServerAdmin root@localhost

Replace these values with your domain name for Larpe and your email address.

You may also need to change this line, depending on your general Apache 2 configuration:

<VirtualHost*:80>

If the hostname you chose is not served by your DNS, don’t forget to add en entry to your /etc/hosts file.

If you intend to use SSL (https) for Larpe or for any site you will configure in Larpe, you will have to configure SSL support on your Apache 2 server first.

Activate this virtual host, as root:

# a2ensite apache2-vhost-larpe

You can then reload Apache (still as root). In most distributions, it is:

# /etc/init.d/apache2 reload

In Fedora:

# /etc/init.d/httpd reload

Larpe now works, the administration interface is reachable at http://your_domain_name/admin/.

Larpe configuration¶

Identity Provider configuration¶

If you don't have an Identity Provider yet, you can install Authentic. You can find information to install and configure it on Authentic manual.

In Larpe administration interface, click on "Settings", then "Identity Provider".

Fill in the metadata file that you've got from your Identity Provider then click Submit. Your Identity Provider is now configured in Larpe, you can then configure as many Service Providers as you want.

Service Provider configuration¶

In order to restrict access to Larpe administration, you must configure Larpe as a Service Provider.

Click on "Settings", then "Service Provider".

Fill an "Organisation Name" then click "Submit".

Save the Service Provider Metadata (for ID-FF 1.2) (right click then "Save as"). Configure this Service Provider on your Identity Provider with this metadata file.

Creation of a user account¶

Now, you must create a user account, who will be given access rights on the administration interface.

In Larpe administration interface, click on "Users", then "New User".

Give it a name and optionnaly his email address.

Then click on the "token" button (with gear icon), then "generate" button, then "send by email" button.

After that, get your email on the address you just gave, and click on the link in this email.

A Single Sign On will be initiated to the Identity Provider. If you, or the user you created the account for, were not authenticated yet, it will ask for your password. After that, your account is federated, and the administration interface will be restricted.

Next time you go unauthenticated on the administration interface, it will initiate an SSO to the identity provider as well.

Host configuration¶

This section explains how to configure new Service Providers (also named "Hosts") with Larpe.

Host settings¶

Click on "Hosts" then "New Host".

Fill in the following parameters:

Site name : the name you want to give to your Service Provider;
Original site root address : the root url of your Service Provider. If the url of your main page page is something like http://sp.example.com/index.html, just put http://sp.example.com/;
Authentication page: if the page which contains the authentication form for your Service Provider is on a separate page, fill the url of this page here;
Authentication form page: if you didn't fill the previous field and if the authentication form if not on the first page of your Service Provider either, fill the url of the page which contains the authentication form here;
Logout address : when you want Single Sign On and Identity Federation, you probably want Single Logout too. If so, fill the logout url of your original site here;
Reversed host name : the domain name where you want to access your Service Provider through the reverse proxy. If you use Larpe's domain name here, you must set a reversed directory;
Reversed directory : a subdirectory where you want to access your Service Provider through the reverse proxy. If you set a reversed directory, your service provider will be accessible at http://reversed_host_name/reversed_directory/. If you don't set one, it will be accessible at http://reversed_host_name/.
Then click "Submit".

You will see all the current parameters for this host. Your new host is probably not fully configured for SSO but you should already be able to access its home page. If you have a warning message telling it's not fully configured, just ignore it for the moment and check if this hosts is accessible already:

Add this new hostname to your DNS (or locally in /etc/hosts).

Then click on the "New url for this host" field on the current page to check you can access this new host.

Host example : Linuxfr¶

To help you setup your own Service Provider, we provide an example of a working Service Provider to guide you.

To setup Linuxfr, fill in the following parameters:

Site name: Linuxfr;
Original site address : http://linuxfr.org/;
Authentication page: Nothing here;
Authentication form page: http://linuxfr.org/pub/;
Logout address: http://linuxfr.org/close_session.html;
Reversed host name: linuxfr.reverse-proxy.example.com;
Reversed directory: Nothing here.
With "reverse-proxy.example.com" being the hostname you've set up before for your reverse-proxy.

Don't forget to add this new hostname to your DNS (or locally in /etc/hosts) as well.

You can then go to the reversed Linuxfr at http://linuxfr.reverse-proxy.example.com/.

Host final setup¶

Now that you can access your Service Provider, you need a final step to use Liberty Alliance features. Click on "Hosts", then click on the "Edit" icon of the Service Provider you've just configured. Save the Service Provider Metadata (for ID-FF 1.2) (right click then "Save as"). Configure this Service Provider on your Identity Provider with this metadata file.