Authentic — Administrator Guide

Overview

Authentic is an identity management solution (an Identity Provider) designed for identity federation and Single Sign-On in conformity with Liberty Alliance norms and standards (ID-FF 1.2 and ID-WSF). It uses the Lasso library which is certified by the Liberty Alliance consortium.

Lasso and Authentic are released under the terms of the GNU General Public 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 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 was based on SAML. The current version is now compliant with SAML 2.0. 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 (Apache licence) 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. It includes metadata exchange and privacy rules allowing agreements between small groups of partners. It is mainly used in higher education field.

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 Authentic

Installation under Debian GNU/Linux or Ubuntu

To work correctly Authentic relies on:

• Apache (1.3 or 2.x, Apache 2 recommended) ;

• Lasso (0.6.3 or later) ;

• Quixote (2.0 or later) ;

• mod_python or SCGI (SCGI 1.7 or later recommended).

Package Installation

Authentic is not yet an official package of these distributions, depending on the version you use, you will need to add one of the following lines to your /etc/apt/sources.list file:

As root type:

apt-get update
apt-get install authentic

All the required packages are installed.

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:

• Authentic and Quixote 2 on http://authentic.labs.libre-entreprise.org/ ;

• Lasso on http://lasso.entrouvert.org.

Apache Configuration

You need then to configure Apache to have a Authentic virtual host. The following example file is called authentic and is installed. It works (replacing www.example.com by the domain Name you've chosen for Authentic, we'll use authentic.example.com) for Apache and SCGI. You can find it in /etc/apache2/sites-available:

<VirtualHost *>
  ServerName authentic.example.com
  include /usr/share/authentic/apache2.conf
  CustomLog /var/log/apache2/authentic-access.log combined
  ErrorLog /var/log/apache2/authentic-error.log
</VirtualHost>

To activate Authentic site you need to make a link toward this file from the /etc/apache2/sites-available/ directory:

a2ensite authentic

You have to make sure Apache is configured to support SSL as well: check you have the following line in /etc/apache2/ports.conf:

Listen 443

Add it if you don't find it. Add then SSL support in Apache:

a2enmod ssl

Next it is necessary for SCGI to be enabled:

a2enmod scgi

You can then reload Apache (still as root):

/etc/init.d/apache2 reload

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

Authentic works, the administration interface is reachable: http://authentic.example.com/admin.

Installation with another Linux distribution

We suppose Apache, SCGI (which gather a Python module and an Apache module which communicate together) or mod_python are already installed. You need then to download and install the following sources:

• Lasso;

• Quixote;

• Authentic.

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

tar xzf authentic-VERSION.tar.gz
cd authentic-VERSION
python setup.py install

You then need to configure Apache correctly.

To launch Authentic you can type as root (or any non-privileged user with read/write access to /var/lib/authentic/) in a terminal:

authenticctl.py start

Note that for security reasons, it is better to have Authentic launched by a dedicated user, this user must have writing right on /var/lib/authentic.

Once Authentic is working, the administration interface is: http://authentic.example.com/admin.

Installation under Windows

We did not proceed any installation of Authentic under Windows so far. But as all the required components works with this OS, the installation is possible and we may describe it soon. Don't hesitate to tell us about your attempts.

Basic Authentic configuration

Administrator creation

We consider you are the Authentic administrator and we are going to help you create your account.

At first, you have to go on the administration interface: http://authentic.example.com/admin/.

Click on "Identity Management", then on the "add identity" link.

Fill the following fields:

• Name (type your first and last name);
• Email (type your email);
• Roles (choose the only available role "administrator");
• Username (the user name chosen for the administrator);
• Password (the password chosen for the administrator).

the account is created you can now connect as administrator on the identification page.

Basic configuration of the Identity Provider

Public and private keys creation

If you don't hold pem format keys, you need to create them. To create a couple public key/private key with OpenSSL, use the following commands:

Create the private key in a file named name-of-the-private-key.pem:

openssl genrsa -out name-of-the-private-key.pem 2048

Extract the public key from the private key in a file named name-of-the-public-key.pem:

openssl rsa -in name-of-the-private-key.pem -pubout \
    -out name-of-the-public-key.pem

Identity Provider configuration

The first two fields are automatically filled, don't play with them unless you know what you are doing.

Fields:

• Provider ID (a username which necessarily is a URL);
• Base URL (All the Liberty Alliance required URL are located under this root);
• Organisation name (Name of the organisation who manage the Identity Provider);
• Private Key (PEM format private key);
• Public Key (PEM format public key);
• Identity Provider Introduction, Common Domain (the Identity Provider introduction is a Liberty Alliance mechanism allowing an Identity Provider, for a particular domain, to create a cookie on the client machine. This is useful when several Identity Providers are associated to a Service Provider: this cookie can associate the Service Providers within a domain with the Identity Provider which delivered the cookie.);
• ID-FF Proxy Support (the proxy ID-FF option allows an identity provider to act as an active proxy between a Service Provider and the final Identity Provider. It is usefull only when several Identity Providers are used).

Saving the metadata file

In this Authentic administration interface you can save the metadata file. this is usefull when it comes to configure a Service Provider. Act as follows:

• click on "Settings";
• you see an "Identity Provider Metadata" link. Do a right click and "save the link target as" ;
• choose the file name (for example metadata-authentic.xml) and the place you want to save it.

Service Provider installation

Service Provider Example: Candle

Candle is a Liberty Alliance Service Provider specifically designed to work with Authentic. You may prefer to install your own Service Provider, it may work without any problem if it is compliant with Liberty Alliance. Candle has the advantage of being developped by the Authentic team (the user interface is very similar, beware of confusion) and to be fully operationnal.

Authentic-like installation

To install Candle under Debian Sarge, just type as root:

echo 'deb http://deb.entrouvert.org/ sarge-experimental' \
  >> /etc/apt/sources.list

This command add the repository which contains all the required packages in your sources.list file.

Still as root type:

apt-get update
apt-get install candle

All the required packages are installed.

Concerning other distributions, download the sources on this site http://lasso.entrouvert.org/links and follow exactly the same steps as for the Authentic installation (Installation with another Linux distribution).

Once the software is installed, the Candle administration interface is available http://candle.example.com/admin.

Public and private keys creation

If you don't have pem format keys, you need to create them. To create a couple public key/private key with OpenSSL, use the following commands:

Create the private key in a file named name-of-the-private-key.pem:

openssl genrsa -out name-of-the-private-key.pem 2048

Extract the public key from the private key in a file named name-of-the-public-key.pem:

openssl rsa -in name-of-the-private-key.pem -pubout \
    -out name-of-the-public-key.pem

Service Provider creation

Go on the Candle administration interface http://candle.example.com/admin. Click on the "Settings" tab then on the "Service Provider" link.

the first two fields are automatically filled don't play with them unless you know what you are doing.

Fields:

• Provider ID (an username which necessarily a URL);
• Base URL (All the Liberty Alliance required URLs are under this base URL);
• Organisation Name (name of the organisation which manages the identity provider);
• Private Key (pem format private key);
• Public Key (pem format public key);
• Identity Provider Introduction, Common Domain (the Identity Provider Introduction is a Liberty Alliance mechanism allowing an Identity Provider, for a particular domain, to create a cookie on the client machine. This is useful when several Identity Providers are associated to a Service Provider: this cookie can associate the Service Providers within a domain with the Identity Provider which delivered the cookie.);

Saving the metadata file

In the Candle administration interface you can save the metadata file. This is usefull when it comes to declare Candle as Service Provider on Authentic. Proceed as follow:

• click on the "Settings" tab;
• you see a link " Service Provider Metadata". Do a right click and "save the link target as";
• choose the file name (for example metadata-candle.xml) and the place you want to save it.

Declaring Authentic as Identity Provider on Candle

On Candle administration interface, click on the "Settings" tab, then on the "Identity Providers" link . Click again on "New".

Fill the following fields:

• Metadata (Authentic metadata file);
• Public Key (Authentic public key);
• CA Certificate Chain (certificate gathering all the authentication chain to the root CA.

Declaring Candle as Service Provider on Authentic

You need to declare Candle as Service Provider linked to the Identity Provider Authentic. In order to do so, go on the Authentic administration interface:

• click on "Settings";
• click on the "Liberty Providers" link;
• click on the "New" link.

You need to fill the following fields:

• Metadata (Candle metadata file);
• Public Key (Candle Public Key);
• CA Certification Chain (Certificate gathering all the authentication chain to the root CA).
• Allow IdP initiated Single Sign On: (Allow Single Sign-On from the Identity Provider and not only from the Service Provider).

Service Provider example: w.c.s.

w.c.s. is a web application which allows to design and set up online forms. It gives a user the ability to create web forms easily without requiring any other skill than familiarity with web surfing. You can install it exactly the same way you installed Candle, the w.c.s. documentation can be helpful http://wcs.labs.libre-entreprise.org/doc/fr/

Authentic use and settings

Creating and modifying users

You have four different ways of adding new users:

• Create them one by one;
• Create a lot of them automatically using a CSV file;
• Collect the informations of an LDAP directory;
• Allowing the users to create their identity themselves.

Clicking on "Identity Management" you see the users list.

In front of each user name, take place four icons allowing the following actions on the user account: see, modify, remove, see the logs.

Adding a user manually

To create users one by one, click on "Identity Management" then on the "Add identity" link.

Fill the following fields:

• Name (type the Name of the user);
• Email (type the Email of the user);
• Roles (choose the role "administrator" if you intend to create another administrator or leave it blank to create a normal user);
• Username (the username chosen for the user);
• Password (the Password chosen for the user).

Import identites from a CSV file

Instead of creating many users one by one, you can generate them automatically thanks to a CSV file formatted as follows:

Username;Password;Name;Email

Click on "Identity Management" then on the "Import identities from CSV file" link. Click on the "Choose File" button and select the CSV file you have prepared.

Using a LDAP directory

You can use the user base of your LDAP (or LDAPs) directory as a data source: All you LDAP users will have their identity on Authentic. The user must have a direct acces to the LDAP directory. Once the LDAP directory declaration is done, one of the users has to be set as the administrator (using Authentic interface), or all the users will be able to access the administration interface.

Click on "Settings", then on the "Identity Storage" link, select LDAP directory in the list, clik on the submit button.

Fill the diferent LDAP parameters:

• LDAP URL (LDAP or LDAPs server URL);
• LDAP Base (root of the LDAP tree);
• LDAP Administrative Bind DN (Distinguished Name, the name of the LDAP administrator account, not mandatory);
• LDAP Administrative Bind password (the LDAP administrator account password, not mandatory);
• LDAP Object Classe (Class to which belong the objects "user", Active Directory default is "user");
• LDAP Object Username Attribute (Field which contains the username in the LDAP directory, Active Directory default is "sAMAccountName");

• LDAP Object User Name Attribute (Field which contains the name of the user in the LDAP directory, Active Directory default is "UserName");

• LDAP Object Email Attribute (Field which contains the email in the LDAP directory, Active Directory default is "mail");
• Massive LDAP Directory (Check this to improve performances of a big LDAP directory, Active Directory default is "").

Please be aware the user connecting through LDAP must be allowed to "bind" on the directory with his/her username and password. Also, the user selected to become administrator must be allowed to list LDAP objects.

Allow the users to create their identities

Instead of having the administror being the only one in charge of identity creation, you can select an option allowing anybody to create its own account from the login page. When this option is selected, a new link stands on the login page. This link allows anybody to reach an identity creation form similar to the one used by the administrator.

To activate this option, click on "Settings", then on the "Identity Options" link. In the list "Identity Creation", choose "Self-registration" then submit.

Modifying a user datas

To modify a user datas, click on "Settings", then on the second icon in front of his name. You can then change what has to be.

Identity parameters

Some parameters exist about the way identities are created. You can set them on "Settings", under the "Identities" section.

Identity Options

Clicking the "Identity Options" link you can set four elements:

• Identity Creation: defines if the user can create identities themselves or if only the administrator is allowed to. When "Self-registration" is selected a new link stand on the login page allowing anybody to create an account and to receive his password by email.
• Notify Administrators on Registration: defines if the administrator must receive an email when an account is created by a user.
• Use email as username: defines if the email address must be used as the username. When this checkbox is selected the user email address will automatically be used as username, the user can't choose it anymore.
• Welcome email: allow to write a welcome email which will be automatically sent to the new users. The text is up to you but is definetly more usefull if it includes the user password. At the place you want to display it in the text simply type "[password]" (without the quotes). You can insert the username as well using "[username]" and the server name using "[hostname]".

Identity Storage

Following the "Identity Storage" link you can choose two different stockage types:

• Default storage (files) (stores the identities in separate files in /var/lib/authentic/);

• LDAP directory (allows the use of a LDAP directory, cf. Using a LDAP directory).

Passwords

Following the "Passwords" link, you can set the following elements:

• Allow the user to change his password;
• Choose to generate automatically the initial password;
• Determine the way a lost password can be retrieved (sending an email to the administrator, receiving it by email automatically, answer a question before receiving it by email);
• Define the biggest and the smallest size allowed for passords (0 means no limitation).

Login Screen

Following the "Login Screen" link, you can add to this screen a cancel button. This button allows a redirection towards the Service Provider from which the user came. It happens to be usefull when a user reach the Login screen by mistake.

Logs

The "Logs" link gives access to some informations about the users actions on the server:

the following events are collected

• authentication: an authentication succeeded;
• authentication failure: an authentication failed;
• changed password: a password has been changed;
• changing password page: the page allowing to change password has been hit;
• changing password page (had_errors): on the page allowing to change password the user provoked errors (not typing twice the same new password, or typing a new password similar to the old one);
• created new identity (username): an identity has been created by the administrator;
• deleted identity (username): an identity has been deleted;
• fedterm to (provider ID): the Service Provider ended a federation;
• internal server error: Authentic had an internal server error;
• login page: the Login Screen has been hit;
• login page, cancel: the cancel button on the Login Screen has been hit;
• login page, proxying to (provider ID): on the Login Screen, the user asked for being redirected toward another Identity Provider. Authentic becomes a proxy for this provider.
• lost password page: the page allowing to retrieve a lost password has been hit;

• lost password -> email password (username): a password has been sent to the user by email;

• logout: a simple deconnexion succeeded;
• SLO from (Provider ID): a global deconnexion initiated by the Service Provider using http (redirect) protocol succeeded;
• SLO/SOAP from (provider ID): a global deconnexion initiated by the Service Provider using SOAP protocol succeeded;
• SSO from (username): a Single Sign-On connexion succeeded;
• SSO to (provider ID): a Single Sign-On connexion initiated by the Service Provider succeededi;
• updated identity: the user modified his/her identity;
• updating personal information: the user modified his/her personnal information;
• user created new identity (username): a user created an identity;

 <?xml version="1.0"?>
   <theme name="Fake" version="1.0">
     <label>Fake</label>
     <desc>Fake Theme used to explain</desc>
     <author>Frederic Peters</author>
    </theme>

Licenses

Authentic, Candle and Lasso are released under the terms of the GNU General Public License.