LassoLogin

LassoLogin — Single Sign-On and Federation Profile

Synopsis


#include <lasso/lasso.h>

                    LassoLogin;
enum                LassoLoginProtocolProfile;
LassoLogin*         lasso_login_new                     (LassoServer *server);
void                lasso_login_destroy                 (LassoLogin *login);
gchar*              lasso_login_dump                    (LassoLogin *login);
LassoLogin*         lasso_login_new_from_dump           (LassoServer *server,
                                                         const gchar *dump);
gint                lasso_login_accept_sso              (LassoLogin *login);
gint                lasso_login_build_artifact_msg      (LassoLogin *login,
                                                         LassoHttpMethod http_method);
int                 lasso_login_build_assertion         (LassoLogin *login,
                                                         const char *authenticationMethod,
                                                         const char *authenticationInstant,
                                                         const char *reauthenticateOnOrAfter,
                                                         const char *notBefore,
                                                         const char *notOnOrAfter);
gint                lasso_login_build_authn_request_msg (LassoLogin *login);
gint                lasso_login_build_authn_response_msg
                                                        (LassoLogin *login);
gint                lasso_login_build_request_msg       (LassoLogin *login);
gint                lasso_login_build_response_msg      (LassoLogin *login,
                                                         gchar *remote_providerID);
gint                lasso_login_init_authn_request      (LassoLogin *login,
                                                         const gchar *remote_providerID,
                                                         LassoHttpMethod http_method);
gint                lasso_login_init_idp_initiated_authn_request
                                                        (LassoLogin *login,
                                                         const gchar *remote_providerID);
gint                lasso_login_init_request            (LassoLogin *login,
                                                         gchar *response_msg,
                                                         LassoHttpMethod response_http_method);
gboolean            lasso_login_must_ask_for_consent    (LassoLogin *login);
gboolean            lasso_login_must_authenticate       (LassoLogin *login);
int                 lasso_login_process_authn_request_msg
                                                        (LassoLogin *login,
                                                         const char *authn_request_msg);
gint                lasso_login_process_authn_response_msg
                                                        (LassoLogin *login,
                                                         gchar *authn_response_msg);
gint                lasso_login_process_request_msg     (LassoLogin *login,
                                                         gchar *request_msg);
gint                lasso_login_process_response_msg    (LassoLogin *login,
                                                         gchar *response_msg);
int                 lasso_login_validate_request_msg    (LassoLogin *login,
                                                         gboolean authentication_result,
                                                         gboolean is_consent_obtained);
int                 lasso_login_set_encryptedResourceId (LassoLogin *login,
                                                         LassoDiscoEncryptedResourceID *encryptedResourceId);
int                 lasso_login_set_resourceId          (LassoLogin *login,
                                                         const char *content);

Object Hierarchy

  GObject
   +----LassoNode
         +----LassoProfile
               +----LassoLogin
                     +----LassoLecp

Description

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 service provider must implement the following process:

Example 1. Service Provider Login URL

LassoLogin *login;

login = lasso_login_new(server);
lasso_login_init_authn_request(login, "http://identity-provider-id/",
                LASSO_HTTP_METHOD_REDIRECT);

// customize AuthnRequest
request = LASSO_LIB_AUTHN_REQUEST(LASSO_PROFILE(login)->request);
request->NameIDPolicy = strdup(LASSO_LIB_NAMEID_POLICY_TYPE_FEDERATED);
request->ForceAuthn = TRUE;
request->IsPassive = FALSE;
request->ProtocolProfile = strdup(LASSO_LIB_PROTOCOL_PROFILE_BRWS_ART);

lasso_login_build_authn_request_msg(login);

// redirect user to identity provider
printf("Location: %s\n\nRedirected to IdP\n", LASSO_PROFILE(login)->msg_url);


Example 2. Service Provider Assertion Consumer Service URL

LassoLogin *login;
char *request_method = getenv("REQUEST_METHOD");
char *artifact_msg = NULL, *lares = NULL, *lareq = NULL;
char *name_identifier;
lassoHttpMethod method;

login = lasso_login_new(server);
if (strcmp(request_method, "GET") == 0) {
        artifact_msg = getenv("QUERY_STRING");
        method = LASSO_HTTP_METHOD_REDIRECT;
} else {
        // read submitted form; if it has a LAREQ field, put it in lareq,
        // if it has a LARES field, put it in lares
        if (lareq) {
                artifact_msg = lareq;
        } else if (lares) {
                response_msg = lares;
        } else {
                // bail out
        }
        method = LASSO_HTTP_METHOD_POST;
}

if (artifact_msg) {
        lasso_login_init_request(login, artifact_msg, method);
        lasso_login_build_request_msg(login);
        // makes a SOAP call, soap_call is NOT a Lasso function
        soap_answer_msg = soap_call(LASSO_PROFILE(login)->msg_url,
                        LASSO_PROFILE(login)->msg_body);
        lasso_login_process_response_msg(login, soap_answer_msg);
} else if (response_msg) {
        lasso_login_process_authn_response_msg(login, response_msg);
}

// looks up name_identifier in local file, database, whatever and gets back
// two things: identity_dump and session_dump
name_identifier = LASSO_PROFILE(login)->nameIdentifier
lasso_profile_set_identity_from_dump(LASSO_PROFILE(login), identity_dump);
lasso_profile_set_session_from_dump(LASSO_PROFILE(login), session_dump);

lasso_login_accept_sso(login);

if (lasso_profile_is_identity_dirty(LASSO_PROFILE(login))) {
        LassoIdentity *identity;
        char *identity_dump;
        identity = lasso_profile_get_identity(LASSO_PROFILE(login));
        identity_dump = lasso_identity_dump(identity);
        // record identity_dump in file, database...
}

if (lasso_profile_is_session_dirty(LASSO_PROFILE(login))) {
        LassoSession *session;
        char *session_dump;
        session = lasso_profile_get_session(LASSO_PROFILE(login));
        session_dump = lasso_session_dump(session);
        // record session_dump in file, database...
}

// redirect user anywhere
printf("Location: %s\n\nRedirected to site root\n", login->msg_url);


Details

LassoLogin

typedef struct {
	LassoLoginProtocolProfile protocolProfile;
	gchar *assertionArtifact;
	LassoSamlAssertion *assertion;
} LassoLogin;

Single sign-on profile for the current transaction; possibly an assertionArtifact to be used by the service provider in its "assertionConsumerServiceURL" and the assertion created or received for the principal.


enum LassoLoginProtocolProfile

typedef enum {
	LASSO_LOGIN_PROTOCOL_PROFILE_BRWS_ART = 1,
	LASSO_LOGIN_PROTOCOL_PROFILE_BRWS_POST,
	LASSO_LOGIN_PROTOCOL_PROFILE_BRWS_LECP,
	LASSO_LOGIN_PROTOCOL_PROFILE_REDIRECT,
} LassoLoginProtocolProfile;

Identifies the two possible profiles for Single Sign-On and Federation.


lasso_login_new ()

LassoLogin*         lasso_login_new                     (LassoServer *server);

Creates a new LassoLogin.

server : the LassoServer
Returns : a newly created LassoLogin object; or NULL if an error occured

lasso_login_destroy ()

void                lasso_login_destroy                 (LassoLogin *login);

Destroys a LassoLogin object.

login : a LassoLogin

lasso_login_dump ()

gchar*              lasso_login_dump                    (LassoLogin *login);

Dumps login content to an XML string.

login : a LassoLogin
Returns : the dump string. It must be freed by the caller.

lasso_login_new_from_dump ()

LassoLogin*         lasso_login_new_from_dump           (LassoServer *server,
                                                         const gchar *dump);

Restores the dump to a new LassoLogin.

server : the LassoServer
dump : XML login dump
Returns : a newly created LassoLogin; or NULL if an error occured.

lasso_login_accept_sso ()

gint                lasso_login_accept_sso              (LassoLogin *login);

Gets the assertion of the response and adds it into the session. Builds a federation with the 2 name identifiers of the assertion and adds it into the identity. If the session or the identity are NULL, they are created.

login : a LassoLogin
Returns : 0 on success; or a negative value otherwise.

lasso_login_build_artifact_msg ()

gint                lasso_login_build_artifact_msg      (LassoLogin *login,
                                                         LassoHttpMethod http_method);

Builds a SAML artifact. Depending of the HTTP method, the data for the sending of the artifact are stored in msg_url (REDIRECT) or msg_url, msg_body and msg_relayState (POST).

login : a LassoLogin
http_method : the HTTP method to send the artifact (REDIRECT or POST)
Returns : 0 on success; or a negative value otherwise.

lasso_login_build_assertion ()

int                 lasso_login_build_assertion         (LassoLogin *login,
                                                         const char *authenticationMethod,
                                                         const char *authenticationInstant,
                                                         const char *reauthenticateOnOrAfter,
                                                         const char *notBefore,
                                                         const char *notOnOrAfter);

Builds an assertion and stores it in profile session. authenticationInstant, reauthenticateOnOrAfter, notBefore and notOnOrAfter may be NULL. If authenticationInstant is NULL, the current time will be used. Time values must be encoded in UTC.

login : a LassoLogin
authenticationMethod : the authentication method
authenticationInstant : the time at which the authentication took place
reauthenticateOnOrAfter : the time at, or after which the service provider must reauthenticates the principal with the identity provider
notBefore : the earliest time instant at which the assertion is valid
notOnOrAfter : the time instant at which the assertion has expired
Returns : 0 on success; or a negative value otherwise.

lasso_login_build_authn_request_msg ()

gint                lasso_login_build_authn_request_msg (LassoLogin *login);

Converts profile authentication request (request member) into a Liberty message, either an URL in HTTP-Redirect profile or an URL and a field value in Browser-POST (form) profile.

The URL is set into the msg_url member and the eventual field value (LAREQ) is set into the msg_body member.

login : a LassoLogin
Returns : 0 on success; or a negative value otherwise.

lasso_login_build_authn_response_msg ()

gint                lasso_login_build_authn_response_msg
                                                        (LassoLogin *login);

Converts profile authentication response (response member) into a Liberty message.

The URL is set into the msg_url member and the field value (LARES) is set into the msg_body member.

login : a LassoLogin
Returns : 0 on success; or a negative value otherwise.

lasso_login_build_request_msg ()

gint                lasso_login_build_request_msg       (LassoLogin *login);

Converts profile artifact request into a Liberty SOAP message.

The URL is set into the msg_url member and the SOAP message is set into the msg_body member.

login : a LassoLogin
Returns : 0 on success; or a negative value otherwise.

lasso_login_build_response_msg ()

gint                lasso_login_build_response_msg      (LassoLogin *login,
                                                         gchar *remote_providerID);

Converts profile assertion response (response member) into a Liberty SOAP messageresponse message.

The URL is set into the msg_url member and the SOAP message is set into the msg_body member.

login : a LassoLogin
remote_providerID : service provider ID
Returns : 0 on success; or a negative value otherwise.

lasso_login_init_authn_request ()

gint                lasso_login_init_authn_request      (LassoLogin *login,
                                                         const gchar *remote_providerID,
                                                         LassoHttpMethod http_method);

Initializes a new AuthnRequest from current service provider to remote identity provider specified in remote_providerID (if NULL the first known identity provider is used).

login : a LassoLogin
remote_providerID : the providerID of the identity provider (may be NULL)
http_method : HTTP method to use for request transmission
Returns : 0 on success; or a negative value otherwise.

lasso_login_init_idp_initiated_authn_request ()

gint                lasso_login_init_idp_initiated_authn_request
                                                        (LassoLogin *login,
                                                         const gchar *remote_providerID);

Generates an authentication response without matching authentication request.

If remote_providerID is NULL, the first known provider is used.

login : a LassoLogin.
remote_providerID : the providerID of the remote service provider (may be NULL)
Returns : 0 on success; or a negative value otherwise.

lasso_login_init_request ()

gint                lasso_login_init_request            (LassoLogin *login,
                                                         gchar *response_msg,
                                                         LassoHttpMethod response_http_method);

Initializes an artifact request. response_msg is either the query string (in redirect mode) or the form LAREQ field (in browser-post mode).

login : a LassoLogin
response_msg : the authentication response received
response_http_method : the method used to receive the authentication response
Returns : 0 on success; or a negative value otherwise.

lasso_login_must_ask_for_consent ()

gboolean            lasso_login_must_ask_for_consent    (LassoLogin *login);

Evaluates if consent must be asked to the Principal to federate him.

login : a LassoLogin
Returns : TRUE if consent must be asked

lasso_login_must_authenticate ()

gboolean            lasso_login_must_authenticate       (LassoLogin *login);

Evaluates if user must be authenticated.

login : a LassoLogin
Returns : TRUE if user must be authenticated

lasso_login_process_authn_request_msg ()

int                 lasso_login_process_authn_request_msg
                                                        (LassoLogin *login,
                                                         const char *authn_request_msg);

Processes received authentication request, checks it is signed correctly, checks if requested protocol profile is supported, etc.

login : a LassoLogin
authn_request_msg : the authentication request received
Returns : 0 on success; or a negative value otherwise.

lasso_login_process_authn_response_msg ()

gint                lasso_login_process_authn_response_msg
                                                        (LassoLogin *login,
                                                         gchar *authn_response_msg);

Processes received authentication response.

login : a LassoLogin
authn_response_msg : the authentication response received
Returns : 0 on success; or a negative value otherwise.

lasso_login_process_request_msg ()

gint                lasso_login_process_request_msg     (LassoLogin *login,
                                                         gchar *request_msg);

Processes received artifact request.

login : a LassoLogin
request_msg : the artifact request received
Returns : 0 on success; or a negative value otherwise.

lasso_login_process_response_msg ()

gint                lasso_login_process_response_msg    (LassoLogin *login,
                                                         gchar *response_msg);

Processes received assertion response.

login : a LassoLogin
response_msg : the assertion response received
Returns : 0 on success; or a negative value otherwise.

lasso_login_validate_request_msg ()

int                 lasso_login_validate_request_msg    (LassoLogin *login,
                                                         gboolean authentication_result,
                                                         gboolean is_consent_obtained);

Initializes a response to the authentication request received.

login : a LassoLogin
authentication_result : whether user has authenticated succesfully
is_consent_obtained : whether user consent has been obtained
Returns : 0 on success; or a negative value otherwise.

lasso_login_set_encryptedResourceId ()

int                 lasso_login_set_encryptedResourceId (LassoLogin *login,
                                                         LassoDiscoEncryptedResourceID *encryptedResourceId);

...

login : a LassoLogin
encryptedResourceId :
Returns : 0 on success; or a negative value otherwise.

lasso_login_set_resourceId ()

int                 lasso_login_set_resourceId          (LassoLogin *login,
                                                         const char *content);

...

login : a LassoLogin
content :
Returns : 0 on success; or a negative value otherwise.