1.1. The Liberty Alliance Project

The Liberty Alliance Project was formed in September 2001 to develop open standards for federated network identity management and identity-based services. Its goals are to ensure interoperability, support privacy, and promote adoption of its specifications, guidelines and best practices. The Alliance is made up of more than 150 members, representing a worldwide cross-section of organizations ranging from educational institutions and government organizations, to service providers and financial institutions, to technology vendors and wireless providers.

1.2. The Lasso Project

In July 2003 Entr'ouvert started to develop the "Carte de Vie Quotidienne" project for the commune of Vandoeuvre-les-Nancy. This project quickly drove us to take interest in cross-site authentication problems. We identified Liberty Alliance specifications as the only ones potentially able to satisfy our need for a strong authentication, coupled with private life respect. Lasso is a library written in C which means it can be easily integrated within any kind of web service whenever a strong authentication is required. Lasso has been the first implementation of Liberty Alliance released under the GNU GPL license.

1.3. Acknowledgments

Figures use drawings from GNOME Gorilla theme by Jakub 'jimmac' Steiner.

2.1. Single Sign-On and Federation

The Single Sign On process allows a user to log in once to an identity provider (IdP), and to be then transparently loged in to the required service providers (SP) belonging to the IP "circle of trust". Subordinating different identities of the same user within a circle of trust to a unique IP is called "Identity Federation". The liberty Alliance specifications allows, thanks to this federation, strong and unique authentication coupled with control by the user of his personal informations. The explicit user agreement is necessary before proceeding to Identity Federation.

The different SPs can't communicate directly together about users informations. They're only able to exchange informations about a user with the IP. This assure :

• private life respect;
• increased security (an unveiled identity for one of the SPs won't endanger the others).

To insure the integrity and the non-revocability of the exchange, a trusted third part releases a security token which identify only the session and not the user.

2.1.1. Artifact Profile

Single Sign-On and Federation interactions, Artifact profile

1. the user clicks on a "login" button
2. the service provider answers with a redirect to the identity provider
3. the browser goes to the identity provider where the user logs in
4. the identity provider answers with a redirect, back to the service provider
5. the browser goes to the service provider telling it has been authenticated
6. the service provider makes a SOAP request to the identity provider asking if it is true that the user has been authenticated
7. the identity provider answers that yeah, everything is under control
8. the service provider answers to the browser and send a welcome page

2.2. Single Log-out

A few words about the five different profiles.

2.2.1. Initiated by the Service Provider, using SOAP requests

Single Log-out interactions; initiated at service provider, using SOAP

Should arrange the figure with the SP on the right; I think it would help read the figure.

2.3. Liberty URLs

How does the identity provider knows the "SOAP endpoint" of the service provider ? That is metadata for you.

4.1. Binary packages

deb http://www.entrouvert.org ./debian/lasso/

apt-get install liblasso-dev

4.2. Sources

The source code of the latest release is available at the following URL: http://labs.libre-entreprise.org/project/showfiles.php?group_id=31

Lasso uses the GNU automake and autoconf to handle system dependency checking. It is developed and built locally on GNU/Linux (Debian) both on x86 and PowerPC processors.

./configure

make

make install

export CVSROOT=:pserver:anonymous@cvs.labs.libre-entreprise.org:/cvsroot/lasso
cvs login     # press enter
cvs -z3 checkout lasso

5.1. Lasso Projects Basics

Lasso functions are defined in several header files typically located in /usr/include/lasso/ or /usr/local/include/lasso/. It is possible to include individual files even if the main lasso.h is sufficient most often.

The first thing to do is then to call lasso_init(). Similarly the last thing will be to call lasso_shutdown(). The smallest and useless Lasso project will therefore be:

#include <lasso/lasso.h>

int main(int argc, char *argv[])
{
    lasso_init();
    printf("Hello world.\n");
    lasso_shutdown();
    return 0;
}

Lasso uses a tool called pkg-config to know the necessary flags for compilation and linking.

 $ pkg-config lasso --cflags
-DXMLSEC_CRYPTO=\"openssl\" -DXMLSEC_LIBXML_260=1 -D__XMLSEC_FUNCTION__=__FUNCTION__
-DXMLSEC_NO_XKMS=1 -DXMLSEC_NO_CRYPTO_DYNAMIC_LOADING=1 -DXMLSEC_CRYPTO_OPENSSL=1
-I/usr/include/lasso -I/usr/include/libxml2 -I/usr/include/xmlsec1 -I/usr/include/glib-2.0
-I/usr/lib/glib-2.0/include
 $ pkg-config lasso --libs
-llasso -lxmlsec1-openssl -lxmlsec1 -lssl -lcrypto -ldl -lgobject-2.0 -lxslt -lxml2
-lpthread -lz -lm -lglib-2.0

Creating an executable from the previous sample will then be a simple matter of calling gcc with the right flags

Creating an executable from the previous sample would then a simple matter of calling gcc with the right flags. But there is currently in bug in XMLSec, the library used by Lasso to provide XML Signature and XML Encryption support. It is possible to workaround the bug:

 $ gcc hello.c -o hello $(pkg-config lasso --cflags --libs)
<command line>:4:16: missing terminating " character
 $ gcc hello.c -o hello $(pkg-config xmlsec1 --cflags --libs | tr -d '\\')
 $ ./hello
Hello world.

5.2. Lasso Objects

The Lasso Architecture chapter described the different objects provided by Lasso. The profile objects will be detailed in the following chapters; common objects such as server, identity and session are explained here.

LassoServer *server;
server = lasso_server_new("sp-metadata.xml",
              NULL, "sp-private-key.pem", "sp-crt.pem", lassoSignatureMethodRsaSha1);
lasso_server_add_provider(server, "idp-metadata.xml",
              "idp-public-key.pem", "ca-crt.pem");

/* profile is a pointer to a LassoProfile object */

LassoIdentity *identity;

if (lasso_profile_is_identity_dirty(profile)) {
    identity = lasso_profile_get_identity(profile);
    if (identity) {
        dump = lasso_identity_dump(identity);
    }
}

/* profile is a pointer to a LassoProfile object */

LassoSession *session;

if (lasso_profile_is_session_dirty(profile)) {
    session = lasso_profile_get_session(profile);
    if (session) {
        dump = lasso_session_dump(session);
    }
}

gchar *dump;
FILE *fd;

dump = lasso_server_dump(server);
/* write dump into a file, a database, whatever */
g_free(dump);

LassoServer *server;
gchar *dump;

/* restore dump from file, database, whatever */
server = lasso_server_new_from_dump(dump);

6.1. Profile Overview

The service provider has four things to do:

• creating an authentication request
• sending it to the identity provider
• receiving an authentication response or an artifact
• (eventually) checking it against the identity provider

The first two steps are handled with an HTTP redirection or an HTML form; typically the user would click on a button, the service provider would then create the authentication request and send an HTTP Redirect to the browser. No URL is defined in the specifications for this first step.

The last two steps are handled in the AssertionConsumerServiceURL; the user will arrive there through an HTTP Redirect or an HTTP POST carrying a piece of information from the identity provider. In case of a redirect, this information, called artifact, won't be large and will be exchanged with the identity provider for a AuthnResponse. An HTTP POST will be able to carry much more information and will therefore be able to provide either the artifact or directly the AuthnResponse.

An appropriate metadata snippet would be:

<?xml version="1.0"?>
<EntityDescriptor providerID="service-provider" xmlns="urn:liberty:metadata:2003-08">
 <SPDescriptor>
  <AssertionConsumerServiceURL id="AssertionConsumerServiceURL1" isDefault="true">
   https://service-provider.example.com/liberty-alliance/assertionConsumer
  </AssertionConsumerServiceURL>
 </SPDescriptor>
</EntityDescriptor>

The identity provider has more things to do:

• receiving an authentication request
• authenticating the user if necessary
• sending a response to the service provider
• (eventually) answering a SOAP request with an other response

All but the last one is handled in the SingleSignOnServiceURL; the user has been redirected there from the service provider with an authentication request as URL parameter. This authentication request is used to decide several things (allowed authentication methods for example) and the authentication is done. This step is not part of the Liberty protocols, this can be as simple as straight HTTP authentication with a username and a password or as complex as a Java applet checking a certificate on the client.

Anyway, once the user has been authenticated, an answer must be sent to the service provider. It is actually not a direct communication, the answer bounces on the user agent with an HTTP Redirect or by an HTML form pointing to the service provider.

The answer may be an artifact (available in the query string in case of a redirect or in a LAREQ form field in case of a POST); the user is then simply redirected to this URL. The service provider will then make a SOAP request to the SoapEndpoint asking for the authentication response matching the artifact.

The answer may also be an authentication response; since it will be a large piece of data it must be passed in an HTML page; an HTML form embedding the authentication response. The user will then submit this form to the service provider AssertionConsumerURL.

Metadata would be:

<?xml version="1.0"?>
<EntityDescriptor providerID="identity-provider" xmlns="urn:liberty:metadata:2003-08">
 <IDPDescriptor>
  <SoapEndpoint>
   https://identity-provider.example.com/soapEndpoint
  </SoapEndpoint>
  <SingleSignOnServiceURL>
   https://identity-provider.example.com/singleSignOn
  </SingleSignOnServiceURL>
 </IDPDescriptor>
</EntityDescriptor> 

6.2. Implementing the service provider parts

LassoLogin *login;

/* create login object */
login = lasso_login_new(server);

lasso_login_init_authn_request(login, idpProviderId, LASSO_HTTP_METHOD_REDIRECT);

lasso_login_init_authn_request(login, idpProviderId, LASSO_HTTP_METHOD_POST);

/* will force authentication on the identity provider */
LASSO_LIB_AUTHN_REQUEST(LASSO_PROFILE(login)->request)->ForceAuthn = TRUE;

/* ask for identity federation */
LASSO_LIB_AUTHN_REQUEST(LASSO_PROFILE(login)->request)->NameIDPolicy =
    strdup(LASSO_LIB_NAME_ID_POLICY_TYPE_FEDERATED);

/* the user consents with the idea of identity federation */
LASSO_LIB_AUTHN_REQUEST(LASSO_PROFILE(login)->request)->consent =
    strdup(LASSO_LIB_CONSENT_OBTAINED);

lasso_login_build_authn_request_msg(login);

printf("Location: %s\n", LASSO_PROFILE(login)->msg_url);

LassoLogin *login;

login = lasso_login_new(server);
lasso_login_init_request(login, query_string, LASSO_HTTP_METHOD_REDIRECT);
lasso_login_build_request_msg(login);

LassoLogin *login;

login = lasso_login_new(server);
lasso_login_init_request(login, lareq_field, LASSO_HTTP_METHOD_POST);
lasso_login_build_request_msg(login);

lasso_login_process_response_msg(login, answer);

LassoLogin *login;

login = lasso_login_new(server);
lasso_login_process_authn_response_msg(lares_field);

if (session_dump != NULL) {
    lasso_profile_set_session_from_dump(LASSO_PROFILE(login), session_dump);
}
if (identity_dump != NULL) {
    lasso_profile_set_identity_from_dump(LASSO_PROFILE(login), identity_dump);
}

lasso_login_destroy(login);

6.3. Implementing the identity provider parts

XXX