LassoLogin

LassoLogin — Single Sign-On and Federation Profile

Synopsis

enum                LassoLoginProtocolProfile;
                    LassoLogin;
LassoLogin*         lasso_login_new                     (LassoServer *server);
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);
void                lasso_login_destroy                 (LassoLogin *login);
gchar*              lasso_login_dump                    (LassoLogin *login);
LassoNode *         lasso_login_get_assertion           (LassoLogin *login);
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);
int                 lasso_login_process_paos_response_msg
                                                        (LassoLogin *login,
                                                         gchar *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);

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
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

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 four possible profiles for Single Sign-On and Federation. It defined how the response to authentication request will transmitted to the service provider.

LASSO_LOGIN_PROTOCOL_PROFILE_BRWS_ART

response is transmitted through a redirect request with an artifact, followed by an artifact resolution request by the service provider.

LASSO_LOGIN_PROTOCOL_PROFILE_BRWS_POST

response is transmitted through a POST.

LASSO_LOGIN_PROTOCOL_PROFILE_BRWS_LECP

response is transmitted in a PAOS response (see LassoLecp).

LASSO_LOGIN_PROTOCOL_PROFILE_REDIRECT

response is transmitted through a redirect.

LassoLogin

typedef struct {
	LassoProfile parent;

	LassoLoginProtocolProfile protocolProfile;
	gchar *assertionArtifact;
} 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.

LassoProfile parent;

LassoLoginProtocolProfile protocolProfile;

the kind of binding used for this authentication request.

gchar *assertionArtifact;

a string representing the artifact received through an artifact resolution. request

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_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 LASSO_PARAM_ERROR_BAD_TYPE_OR_NULL_OBJ if login is not a LassoLogin object, LASSO_PROFILE_ERROR_MISSING_RESPONSE if no response is present in the login profile object -- usually because no call to lasso_login_process_authn_response_msg was donne --, LASSO_PROFILE_ERROR_MISSING_ASSERTION if the response does not contain an assertion, LASSO_PROFILE_ERROR_NAME_IDENTIFIER_NOT_FOUND if the assertion does not contain a NameID element, LASSO_PROFILE_ERROR_MISSING_NAME_IDENTIFIER idem, LASSO_LOGIN_ERROR_ASSERTION_REPLAY if the assertion has already been used.

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 LASSO_PARAM_ERROR_BAD_TYPE_OR_NULL_OBJ if login is not a LassoLogin object, LASSO_PROFILE_ERROR_MISSING_REMOTE_PROVIDERID if no remote provider ID was setup in the login profile object, it's usually done by lasso_login_process_authn_request_msg, LASSO_PROFILE_ERROR_INVALID_HTTP_METHOD if the HTTP method is neither LASSO_HTTP_METHOD_REDIRECT or LASSO_HTTP_METHOD_POST (ID-FF 1.2 case) or neither LASSO_HTTP_METHOD_ARTIFACT_GET or LASSO_HTTP_METHOD_ARTIFACT_POST (SAML 2.0 case) for SAML 2.0), LASSO_PROFILE_ERROR_INVALID_PROTOCOLPROFILE if the current protocolProfile is not LASSO_LOGIN_PROTOCOL_PROFILE_BRWS_ART (only for ID-FF 1.2), LASSO_SERVER_ERROR_PROVIDER_NOT_FOUND if the remote provider is not known to our server object.

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

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 LASSO_PARAM_ERROR_BAD_TYPE_OR_NULL_OBJ if login is not a LassoLogin object, LASSO_PROFILE_ERROR_IDENTITY_NOT_FOUND if no identity object was found in the login profile object.

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 LASSO_PARAM_ERROR_BAD_TYPE_OR_NULL_OBJ if login is not a LassoLogin object, LASSO_PROFILE_ERROR_MISSING_REMOTE_PROVIDERID if not remote provider ID was setup -- it usually means that lasso_login_init_request was not called before, LASSO_SERVER_ERROR_PROVIDER_NOT_FOUND if the remote provider ID is not registered in the server object, LASSO_PROFILE_ERROR_UNSUPPORTED_PROFILE if the SSO profile is not supported by the targeted provider, LASSO_PROFILE_ERROR_BUILDING_QUERY_FAILED if the building of the query part of the redirect URL or of the body of the POST content failed -- it only happens with LASSO_HTTP_METHOD_REDIRECT of LASSO_HTTP_METHOD_POST --, LASSO_PROFILE_ERROR_UNKNOWN_PROFILE_URL if the metadata of the remote provider does not contain an url for the SSO profile.

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 LASSO_PARAM_ERROR_BAD_TYPE_OR_NULL_OBJ if login is not a LassoLogin object, LASSO_PROFILE_ERROR_INVALID_PROTOCOLPROFILE if the current protocol profile is not LASSO_LOGIN_PROTOCOL_PROFILE_BRWS_POST or LASSO_LOGIN_PROTOCOL_PROFILE_BRWS_LECP, LASSO_SERVER_ERROR_PROVIDER_NOT_FOUND if the remote provider ID is not registered in the server object, LASSO_PROFILE_ERROR_UNKNOWN_PROFILE_URL if the metadata of the remote provider does not contain an URL for the assertion consuming service.

lasso_login_build_request_msg ()

gint                lasso_login_build_request_msg       (LassoLogin *login);

Produce a SOAP Artifact Resolve message. It must follows a call to lasso_login_init_request() on the artifact message. Converts 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. You should POST the msg_body to the msg_url afterward.

login :

a LassoLogin

Returns :

0 on success; or LASSO_PARAM_ERROR_BAD_TYPE_OR_NULL_OBJ if login is not a LassoLogin object, LASSO_PROFILE_ERROR_MISSING_REMOTE_PROVIDERID if not remote provider ID was setup -- it usually means that lasso_login_init_request was not called before, LASSO_SERVER_ERROR_PROVIDER_NOT_FOUND if the remote provider ID is not registered in the server object.

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_PARAM_ERROR_BAD_TYPE_OR_NULL_OBJ if login is not a LassoLogin object, LASSO_PROFILE_ERROR_SESSION_NOT_FOUND if no session object was found in the login profile object -- it should be created by lasso_login_build_assertion() if you did not set it manually before calling lasso_login_build_assertion().

lasso_login_destroy ()

void                lasso_login_destroy                 (LassoLogin *login);

Destroys a LassoLogin object.

Deprecated: Since 2.2.1, use g_object_unref() instead.

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_get_assertion ()

LassoNode *         lasso_login_get_assertion           (LassoLogin *login);

Return the last build assertion.

login :

a LassoLogin object

Returns :

a LassoNode representing the build assertion (generally a LassoSamlAssertion when using ID-FF 1.2 or a LassoSaml2Assertion when using SAML 2.0)

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).

For ID-FF 1.2 the default NameIDPolicy in an AuthnRequest is None, which imply that a federation must already exist on the IdP side.

For SAML 2.0 the default NameIDPolicy is the first listed in the metadatas of the current provider, or if none is specified, Transient, which ask the IdP to give a one-time federation

login :

a LassoLogin

remote_providerID:(allow-none) :

the providerID of the identity provider (may be NULL)

http_method :

HTTP method to use for request transmission. default LASSO_HTTP_METHOD_REDIRECT.

Returns :

0 on success; or
  • LASSO_PARAM_ERROR_BAD_TYPE_OR_NULL_OBJ if login is not a LassoLogin object,

  • LASSO_PROFILE_ERROR_MISSING_REMOTE_PROVIDERID if remote_providerID is NULL and no default remote provider could be found from the server object -- usually the first one in the order of adding to the server object --,

  • LASSO_SERVER_ERROR_PROVIDER_NOT_FOUND if the remote_providerID is not known to our server object.

  • LASSO_PROFILE_ERROR_INVALID_HTTP_METHOD if the HTTP method is neither LASSO_HTTP_METHOD_REDIRECT or LASSO_HTTP_METHOD_POST,

  • LASSO_PROFILE_ERROR_BUILDING_REQUEST_FAILED if creation of the request object failed.


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.

The choice of NameIDFormat is the same as for lasso_login_init_authn_request() but with the target remote_providerID as the current provider

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. Error codes are the same as lasso_login_init_authn_request().

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). It should only be used if you received an artifact message, response_msg must be content of the artifact field for the POST artifact binding of the query string for the REDIRECT artifact binding. You must set the response_http_method argument according to the way you received the artifact message.

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 LASSO_PARAM_ERROR_BAD_TYPE_OR_NULL_OBJ if login is not a LassoLogin object, LASSO_PARAM_ERROR_INVALID_VALUE if response_msg is NULL, LASSO_PROFILE_ERROR_INVALID_HTTP_METHOD if the HTTP method is neither LASSO_HTTP_METHOD_REDIRECT or LASSO_HTTP_METHOD_POST (in the ID-FF 1.2 case) or neither LASSO_HTTP_METHOD_ARTIFACT_GET or LASSO_HTTP_METHOD_ARTIFACT_POST (in the SAML 2.0 case), LASSO_PROFILE_ERROR_MISSING_ARTIFACT if no artifact field was found in the query string (only possible for the LASSO_HTTP_METHOD_REDIRECT case), LASSO_PROFILE_ERROR_INVALID_ARTIFACT if decoding of the artifact failed -- whether because the base64 encoding is invalid or because the type code is wrong --, LASSO_PROFILE_ERROR_MISSING_REMOTE_PROVIDERID if no provider ID could be found corresponding to the hash contained in the artifact.

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_paos_response_msg ()

int                 lasso_login_process_paos_response_msg
                                                        (LassoLogin *login,
                                                         gchar *msg);

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.