spkitlasso/README

Lasso SPKit PHP v0.3

This library contains code to ease the usage of the PHP bindings of the lasso
library inside a service provider, usually an existing web application where
you wish to handle some of the profile of the Liberty Alliance or SAML 2.0
protocols.

The API is procedural, minimal and easy to understand.

Depending upong the configuration there is two functionning mode:
 - liberty state is reported through the function lassospkit_nameid() and
   lassospkit_federation(), your application MUST persist them by its own way.
 - liberty state is stored using one of the automatic storage mode, you just
   have to associate a user id with the liberty state. After any liberty event
   you can retrieve this user id.

= Description of the API =

General idea: Initiation of SAML request is done via redirection to a local
page and transmission of parameters to this pages are done via PHP sessions.
The $relay parameters are the url where user should be redirected at the end of
the SAML request whatever the result is.

function lassospkit_nameid()

 * return the nameid found during the last SSO request in the current session.
   If it is non-null, it usually means that we are logged to an SAML IdP.

function lassospkit_set_nameid($nameid)
 * Set the nameid that the next SAML profile should use. Use it before
   presenting link for defederation or single logout. It has no effect if
   redirecting toward SSO.

function lassospkit_userid()
 * When automated storage of the federation is activated this parameter will
   contain the last userID associated with the current nameID. The association
   is done by calling setUserID then making a successul SSO request (via a
   redirection to lassospki_websso_redirect).  When automated storage is
   inactivated, it always returns null and set_userid is ignored by the backend
   code.

function lassospkit_error()
 * When non-null gives a human readable explaination of the last unsucessful
   SAML request. Can be an error or a normal event like the user refusing to
   federate is identity in the context of an SSO request.

function lassospkit_federation()
 * Return an opaque blob containing informations on the federation created with
  an IdP afer a succesful request. If you intend to handle yourself storage of
  the federation, you must save this together with local user account/sessions
  informations and restores it before any future redirection to a
  logout/defederation request. If you user automated persistence you can ignore
  it.

function lassospkit_set_federation($federation)
 * Restore the opaque blob needed to initalize SAML requests. See previous
   function.

function lassospkit_websso_redirect($relay)
 * URL to the local page intiating SSO exchanges with the IdP. Use the baseUrl
   configuration option to construct this URL.

function lassospkit_set_userid($userID)
 * Set the userID (can be any string) to persist together
   with the nameId when using automatized persistence of federations.

function lassospkit_defederation_redirect($relay)
 * Return the URL to the local page initiating defederation exchanges with the
   IdP. It appends the endpoint suffix to the baseUrl configuration option to
   build this URL.

function lassospkit_logout_redirect($relay)
 * Return the URL to the local page initiating logout exchanges with the
   IdP. It appends the endpoint suffix to the baseUrl configuration option to
   build this URL.