=====================================
Larpe - Administrator Guide
=====================================

:author: Damien Laniel
:contact: dlaniel@entrouvert.com
:copyright: Copyright © 2006 Entr'ouvert

.. contents:: Table of contents

Overview
========

Larpe is a Liberty Alliance Reverse Proxy. It allow any service provider
(that is a website) to use Liberty Alliance features (Identity federation,
Single Sign On and Single Sign Logout) without changing the code of
the service provider itself. It uses the Lasso_ library
which is certified by the `Liberty Alliance`_ consortium. Lasso_ and Larpe
are released under the terms of the `GNU/GPL license`_.

What is identity federation ?
+++++++++++++++++++++++++++++

Identity federation is the combination of technological and business needs to 
enable exchanges between different networks and domains in a secure and reliable
manner.
The main purpose of federation is to share identity information across 
heterogeneous systems and identity platforms.

An identity federation based system enables the users connexion with a singthe
username and password (or any other authentication mean) instead of having one
for each service. This username and this password are typed only once at the
time of connection to the first service. The user is then automatically
authenticated on all the services sharing the federated identity.

We can compare a federated identity with a passport used to prove your identity
and to allow you to travel from one country to the other.

What are the benefits of identity federation ?
++++++++++++++++++++++++++++++++++++++++++++++

There can be a lot of advantages :

* to secure the accesses to your applications on all the networks, public and
  private (and particularly concerning a possible extension of extranet
  transactions);

* to simplify the access to your applications using Single Sign-On
  (simplification for the users and the administrators);

* to reduce the costs (costs of helpdesk in particular, costs related to the
  management of a partner's or a customer's users);

* some federation protocols guarantee, in addition, the respect of the user's
  private life (the user controls the exchanged data, no unique username is
  exchanged).

Different federation identity procotocols and standards
+++++++++++++++++++++++++++++++++++++++++++++++++++++++

There are a lot of them, often linked with each other.
SAML_ (Security Assertion Markup Language) is for example the common base of
ID-FF (` Liberty Alliance`_ Identity Federation Framework) and of Shibboleth_.
In addition a new layer came on top of the pile of existing standards : the
"identity services". They are network distributed services which work with a
user controlled identity. This controlled identity services defines which
specific information (or attributes) can be used by those services to bring a
customized and adapted answer. This allows an increased customisation of the
services, intelligent transactions based on identity information.

SAML_
-----

the Security Assertion Markup Language (SAML _) designed by OASIS_ was the
first standard allowing the exchange of protected assertion. Most of the
big companies offering access management solutions took part in its development
and it was explicitly conceived for the business-to-business relations.

SAML_ 1.1 undoubtedly proposes less superfluous functionalities than other
standards. It is a clean, simple and concise protocol. However this concision
which makes it relatively easy to implement is a handicap when it comes to using
SAML_ within another environment, business-to-consumer or business-to-employee
for example. SAML_ 1.1 lack some functionalities concerning the confidentiality,
the safety and mobile clients support. The release of SAML_ 2.0 should largely
cure it.

SAML_ 2.0 is a form of convergence between SAML_ 1.1, Liberty ID-FF 1.2 and
Shibboleth_. The  OASIS_ will was to take the best in each of these protocols
and to include it in a single and coherent framework.

Liberty ID-FF
-------------

Liberty Identity Federation Framework (ID-FF 1.2 and its predecessor ID-FF 1.1)
was worked out by the `Liberty Alliance`_ consortium, founded mid 2001 by Sun,
and joined by several hundreds of companies (France Telecom, Vodafone, VeriSign,
Mastercard, etc).

ID-FF is based on SAML_ and allows more complex deployment scenarios. It
introduces mainly:

* the user control on the operated federations;

* true Single Sign-On and Single Logout;

* a true anonymisation (no unique username circulating between the Service
  Providers and the Identity Providers);

* an authentication context (allowing to provide information on the
  authentication used itself and on what surrounds it, like the inscription
  procedure);

* the metadata exchange.

Designed for companies, ID-FF allows to couple the requirements for a strong
authentication with the respect of the users private life, this is why the
ADAÉ_ very strongly encourages its use within the French administrations.

Shibboleth_
-----------

Like ID-FF, Shibboleth_ is based on SAML_. Shibboleth_ is an Internet2_ project.
Internet2_ is a consortium leaded by american universities working in
partnership with industry and the government. It is an open source
implementation (specific licence, non free) authorising the inter-institutional
sharing of web resources subjected to an access control.

Shibboleth_ provides a standardized gateway between the existing authentication
on campuses and resources suppliers of all kind. Today, there is no deployment
out of the higher education field. Shibboleth_ supports the attribute exchange
in a wider way than SAML_ 1.1. It includes metadata exchange and privacy
rules allowing agreements between small groups of partners.

WS-Federation_
--------------

WS-federation Microsoft, IBM, and VeriSign work on a set of specifications
(called "WS-Security roadmap" or "WS -\*") for their next generation platform of
Web services.

WS-federation_ is one of these specifications, it defines a model for the
federation and the functions related to the identity.

WS-federation_ is designed for companies, the business-to-business and
business-to-employee relations. The use of privacy is optional there and it
misses the multi-client support, which makes it not very suitable with the
business-to-consumer envorionment at the moment.

Because it is relatively recent WS-Federation_ was not tested and deployed
as much as other protocols, it is thus advisable to use it with caution.

Liberty ID-WSF
--------------

the Identity-based Web Services Framework (ID-WSF) of `Liberty Alliance`_ is on
top of the pile of the federation protocols. The specificity of ID-WSF is the
identity service discovery which allows attribute sharing under the user
control.

ID-WSF gathers the following elements:

* permission based attribute sharing (the user determines which attributes can
  be published and who can use them);

* identity service discovery (determines how the Service Providers learn where
  to find identity information);

* interaction service (allows the Service Providers and Identity Providers to
  interact in real time with the user to obtain its assent and the necessary
  authorisations);

* Extended client support (gives the option for client devices to host their own
  identity service or act as an Identity Provider);

* Identity service templates (a reusable mechanism for building new identity
  services that can leverage the web services framework);

* usage directives (which provide a means for including privacy directives in
  the attribute exchange);

ID-WSF is well-suited for business-to-business and business-to-consumer
deployments where it is crucial to share attribute information in a
privacy-oriented manner. Relying parties in the transaction will be able to
search and discover identity information from distributed identity services that
the end-user has registered. Polices related to attribute release can be
defined ahead of time or on the fly via an interaction service that can
communicate with the end user to obtain permissions.

How to get and install Larpe
============================

Installation under Debian_ Sarge
++++++++++++++++++++++++++++++++

To work correctly Larpe relies on :

* Apache2_ ;

* Lasso_ (0.6.3) ;

* Quixote_ (2.0) ;

* SCGI_ ;

* mod_python_ ;

* libxml2 ;

* mod_proxy_html.

You will also need a Liberty Alliance Identity Provider, be it on the same server or not.
We recommend Authentic_ for that need.

Package Installation
--------------------

You need to add the following line to your /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

And follow the debconf wizard to set it up.

All the required packages are now installed and configured.

You might need to change the "<VirtualHost \*>" in your apache2 configuration
(/etc/apache2/sites-available/apache2-vhost-larpe) depending on how you
previously configured apache.

Don't forget to modify your /etc/hosts file if necessary. Larpe now works, the
administration interface is reachable at http://your_domain_name/admin. The username
and password are the ones you entered during the installation wizard.

If you don't want to modify your sources.list file, you can manually dowload and
install the required packages with the dpkg -i command :

* Larpe, Authentic and Lasso on http://deb.entrouvert.org/ ;

* Quixote 2.0 on http://authentic.labs.libre-entreprise.org/.

Installation with another Linux distribution
++++++++++++++++++++++++++++++++++++++++++++

We suppose Apache2_, SCGI_, mod_python_, libxml2 and mod_proxy_html are already installed. You need then to
download and install the following sources :

* Lasso http://lasso.entrouvert.org ;

* Quixote http://www.mems-exchange.org/software/Quixote/ ;

* Authentic http://authentic.labs.libre-entreprise.org/ ;

* Larpe http://labs.libre-entreprise.org/frs/?group_id=108.

To install Larpe, uncompress the sources you have downloaded and launch the
setup.py script ::

 tar xzf larpe*.tar.gz
 cd larpe*
 python setup.py install

You need then to configure Apache2_ correctly. You should use the provided apache2-vhost-larpe template and adapt to your configuration.

Don't forget to modify your /etc/hosts file if necessary. Larpe now works, the
administration interface is reachable at http://your_domain_name/admin.

Basic Larpe configuration
=========================

Identity Provider configuration
+++++++++++++++++++++++++++++++

If you don't have a configured Identity Provider yet, please read Authentic
manual to set it up. Then you must have the metadata and public key of the Identity
Provider to begin with Larpe.

Then in Larpe administration interface, click on "Settings", then "Identity Provider".
Fill in the metadata and public key 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
++++++++++++++++++++++++++++++

Service Provider configuration
------------------------------

Click on "Hosts" then "New Host".

Fill in the following parameters :

* Label : the name you want to give to your Service Provider ;

* Original Site Address : the root URL of your Service Provider ;

* 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. It can be the domain name of Larpe or not ;

Then click "Submit". Wait a few seconds then go to http://reversed_host_name/reverse_directory/
to check if it works. If not, wait a bit more and try again. If it really doesn't work,
please submit a bug report at http://labs.libre-entreprise.org/tracker/?func=add&group_id=108&atid=512

Service Provider 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 :

* Label : 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.

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 /etc/hosts as well.

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

Service Provider Liberty Alliance final setup
---------------------------------------------

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

Licenses
========

Larpe, Authentic_, Candle_ and Lasso_ are released under the terms of the
`GNU/GPL license`_.

.. _Lasso: http://lasso.entrouvert.org/
.. _`Liberty Alliance`: http://projectliberty.org/
.. _`GNU/GPL License`: http://www.gnu.org/copyleft/gpl.html
.. _SAML: http://www.oasis-open.org/specs/index.php#samlv2.0
.. _Shibboleth: http://shibboleth.internet2.edu/
.. _OASIS: http://www.oasis-open.org/
.. _ADAÉ: http://www.adae.gouv.fr/
.. _Internet2: http://internet2.edu/
.. _WS-Federation: http://msdn.microsoft.com/webservices/understanding/gxa/default.aspx?pull=/library/en-us/dnglobspec/html/ws-federation.asp
.. _Debian: http://www.debian.org/
.. _Apache2: http://httpd.apache.org/
.. _Quixote: http://www.mems-exchange.org/software/Quixote
.. _mod_python: http://www.modpython.org/
.. _SCGI: http://www.mems-exchange.org/software/scgi/
.. _OpenSSL: http://www.openssl.org
.. _Candle: http://candle.labs.libre-entreprise.org/
.. _Authentic: http://www.entrouvert.com/fr/authentic/
