LassoLogin: lasso Reference Manual

## LassoLogin LassoLogin — Single Sign-On and Federation Profile |

## Functions

LassoLogin * | lasso_login_new ()
LassoLogin * | lasso_login_new_from_dump ()
lasso_error_t | lasso_login_accept_sso ()
lasso_error_t | lasso_login_build_artifact_msg ()
lasso_error_t | lasso_login_build_assertion ()
lasso_error_t | lasso_login_build_authn_request_msg ()
lasso_error_t | lasso_login_build_authn_response_msg ()
lasso_error_t | lasso_login_build_request_msg ()
lasso_error_t | lasso_login_build_response_msg ()
void | lasso_login_destroy ()
gchar * | lasso_login_dump ()
LassoNode * | lasso_login_get_assertion ()
lasso_error_t | lasso_login_init_authn_request ()
lasso_error_t | lasso_login_init_idp_initiated_authn_request ()
lasso_error_t | lasso_login_init_request ()
gboolean | lasso_login_must_ask_for_consent ()
gboolean | lasso_login_must_authenticate ()
lasso_error_t | lasso_login_process_authn_request_msg ()
lasso_error_t | lasso_login_process_authn_response_msg ()
lasso_error_t | lasso_login_process_paos_response_msg ()
lasso_error_t | lasso_login_process_request_msg ()
lasso_error_t | lasso_login_process_response_msg ()
lasso_error_t | lasso_login_validate_request_msg ()

## Types and Values

struct | LassoLogin

## 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:

- creating an authentication request with `lasso_login_init_authn_request()`;

- sending it to the identity provider with `lasso_login_build_authn_request_msg()`;

- receiving and processing the answer:

  - either an authentication response with `lasso_login_process_authn_response_msg()`
  - or an artifact with `lasso_login_init_request()` then sending the request to the IdP with `lasso_login_build_request_msg()` and processing the new answer with `lasso_login_process_response_msg()`.

Our first example shows how to initiate a request toward an ID-FF 1.2 or SAML 2.0 identity provider. It supposes that we already initialized a LassoServer object with the metadatas or our provider (and its private key if we want to sign the request), and that we added the metadatas of the targetted IdP with the method `lasso_server_add_provider()`.

Example 2. Service Provider Login 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
    LassoLogin *login;
    int rc; // hold return codes

    login = lasso_login_new(server);
    rc = lasso_login_init_authn_request(login, "http://identity-provider-id/",
                    LASSO_HTTP_METHOD_REDIRECT);
    if (rc != 0) {
      ... // handle errors, most of them are related to bad initialization
    }

    // customize AuthnRequest
    // protocolProfile is the protocolProfile of the provider http://identity-provider-id/
    if (protocolProfile == LASSO_LIBERTY_1_2) {
            LassoLibAuthnRequest *request = LASSO_LIB_AUTHN_REQUEST(LASSO_PROFILE(login)->request);
            request->NameIDPolicy = strdup(LASSO_LIB_NAMEID_POLICY_TYPE_FEDERATED);
            request->ForceAuthn = TRUE;
            request->IsPassive = FALSE;
            // tell the IdP how to return the response
            request->ProtocolProfile = strdup(LASSO_LIB_PROTOCOL_PROFILE_BRWS_ART);
    } else if (protocolProfile == LASSO_SAML_2_0) {
            LassoSamlp2AuthnRequest *request = LASSO_SAMLP2_AUTHN_REQUEST(LASSO_PROFILE(login)->request);
            if (request->NameIDPolicy->Format) {
                    g_free(request->NameIDPolicy->Format);
            }
            request->NameIDPolicy->Format = g_strdup(LASSO_NAME_IDENTIFIER_FORMAT_PERSISTENT);
            // Allow creation of new federation
            //
            request->NameIDPolicy->AllowCreate = 1;
            request->ForceAuthn = TRUE;
            request->IsPassive = FALSE;
            // tell the IdP how to return the response
            if (request->ProtocolBinding) {
                     g_free(request->ProtocolBinding);
            }
            // here we expect an artifact response, it could be post, redirect or PAOS.
            request->ProtocolBinding = g_strdup(LASSO_SAML2_METADATA_BINDING_ARTIFACT);
       }
    // Lasso will choose whether to sign the request by looking at the IdP
    // metadatas and at our metadatas, but you can always force him to sign or to
    // not sign using the method lasso_profile_set_signature_hint() on the
    // LassoLogin object.

    rc = lasso_login_build_authn_request_msg(login);
    if (rc != 0) {
          .... // handle errors
          // could be that the requested binding (POST, Redirect, etc..) is not supported (LASSO_PROFILE_ERROR_UNSUPPORTED_PROFILE)
          // or that we could not sign the request (LASSO_PROFILE_ERROR_BUILDING_QUERY_FAILED).
    }

    // redirect user to identity provider
       // we chose the Redirect binding, so we have to generate a redirect HTTP response to the URL returned by Lasso
    printf("Location: %s\n\nRedirected to IdP\n", LASSO_PROFILE(login)->msg_url);

Next example shows how to receive the response from the identity provider for ID-FF 1.2.

Example 3. Service Provider Assertion Consumer Service URL for ID-FF 1.2

    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
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    LassoLogin *login;
    char *request_method = getenv("REQUEST_METHOD");
    char *artifact_msg = NULL, *lares = NULL, *lareq = NULL;
    char *name_identifier;
    lassoHttpMethod method;
    int rc = 0;

    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) {
            // we received an artifact response,
            // it means we did not really receive the response,
            // only a token to redeem the real response from the identity
            // provider through a SOAP resolution call
            rc = lasso_login_init_request(login, artifact_msg, method);
            if (rc != 0) {
                      ... // handle errors
                      // there is usually no error at this step, only
                      // if the IdP response is malformed
            }
            rc = lasso_login_build_request_msg(login);
            if (rc != 0) {
                      ... // handle errors
                      // as for AuthnRequest generation, it generally is caused
                      // by a bad initialization like an impossibility to load
                      // the private key.
            }
            // 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);
            rc = lasso_login_process_response_msg(login, soap_answer_msg);
            if (rc != 0) {
                      ... // handle errors
                      // here you can know if the IdP refused the request,
            }
    } 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);

The implement an IdP you must create a single sign-on service endpoint, the needed APIs for this are `lasso_login_process_authn_request_msg()`, `lasso_login_validate_request_msg()`, `lasso_login_build_assertion()`, `lasso_login_build_authn_response_msg()` and `lasso_login_build_artifact_msg()`. You will have to chose between `lasso_login_build_authn_response_msg()` and `lasso_login_build_artifact_msg()` depending on the requested protocol for the response by the service provider

Example 4. Identity provider single sign-on service

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    LassoLogin *login;
    char *request_method = getenv("REQUEST_METHOD");
    char *artifact_msg = NULL, *lares = NULL, *lareq = NULL;
    char *name_identifier;
    lassoHttpMethod method;
    int rc = 0;

    login = lasso_login_new(server);
    if (strcmp(request_method, 'GET')) { // AuthnRequest send with the HTTP-Redirect binding
        //
        lasso_profile_set_signature_verify_hint(LASSO_PROFILE(login),
                LASSO_PROFILE_SIGNATURE_VERIFY_HINT_FORCE);
        rc = lasso_process_authn_request_msg(login, getenv("QUERY_STRING"));
        if (rc != 0) {
            // handle errors
        }

    } else {

## Functions

### lasso_login_new ()

    LassoLogin *
    lasso_login_new (LassoServer *server);

Creates a new LassoLogin.

#### Parameters

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.

#### Parameters

server | the LassoServer |
dump | XML login dump |

#### Returns

a newly created LassoLogin; or NULL if an error occured.

### lasso_login_accept_sso ()

    lasso_error_t
    lasso_login_accept_sso (LassoLogin *login);

Gets the assertion of the response and adds it to the LassoSession object. 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.

#### Parameters

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 done;

- 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 same as LASSO_PROFILE_ERROR_NAME_IDENTIFIER_NOT_FOUND,

- LASSO_LOGIN_ERROR_ASSERTION_REPLAY if the assertion has already been used.

### lasso_login_build_artifact_msg ()

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

#### Parameters

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 which impeach us to find a service endpoint,

- LASSO_PROFILE_ERROR_MISSING_RESPONSE if the response object is missing,

- LASSO_PROFILE_ERROR_MISSING_STATUS_CODE if the response object is missing a status code,

### lasso_login_build_assertion ()

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

Construct the authentication assertion for the response. It must be called after validating the request using `lasso_login_validate_request_msg()`. The created assertion is accessed using `lasso_login_get_assertion()`.

#### Parameters

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_PROFILE_ERROR_MISSING_RESPONSE if no response object is present ( it is normally initialized by `lasso_login_process_authn_request_msg()` )

- LASSO_PROFILE_ERROR_FEDERATION_NOT_FOUND if a LASSO_SAML2_NAME_IDENTIFIER_FORMAT_PERSISTENT or LASSO_SAML2_NAME_IDENTIFIER_FORMAT_ENCRYPTED NameID format is asked and no corresponding federation was found in the LassoIdentity object,

- LASSO_SERVER_ERROR_PROVIDER_NOT_FOUND if encryption is needed and the request issuing provider is unknown (it as not been registered in the LassoServer object),

- LASSO_DS_ERROR_ENCRYPTION_FAILED if encryption is needed but it failed,

### lasso_login_build_authn_request_msg ()

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

#### Parameters

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&160;- 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&160;- it only happens with the LASSO_HTTP_METHOD_REDIRECT, LASSO_HTTP_METHOD_POST, LASSO_HTTP_METHOD_ARTIFACT_GET and LASSO_HTTP_METHOD_ARTIFACT_POST bindings&160;-,

- LASSO_PROFILE_ERROR_UNKNOWN_PROFILE_URL if the metadata of the remote provider does not contain an url for the SSO profile,

- LASSO_PROFILE_ERROR_INVALID_REQUEST if the request object is not of the needed type, is usually means that `lasso_login_init_request()` was not called before,

- LASSO_PROFILE_MISSING_REQUEST if the request object is missing,

- LASSO_PROFILE_ERROR_INVALID_HTTP_METHOD if the current setted `http_method` on the LassoLogin object is invalid.

### lasso_login_build_authn_response_msg ()

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

#### Parameters

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_PROFILE_ERROR_MISSING_SERVER the server object is needed to sign a message and it is missing,

- LASSO_DS_ERROR_PRIVATE_KEY_LOAD_FAILED the private key for signing could not be found,

- LASSO_PROFILE_ERROR_MISSING_RESPONSE if the response object is missing,

- LASSO_PROFILE_ERROR_UNSUPPORTED_PROFILE if the SSO profile is not supported by the targeted provider,

- LASSO_PROFILE_BUILDING_QUERY_FAILED if using LASSO_HTTP_METHOD_REDIRECT building of the redirect URL failed,

- LASSO_PROFILE_BUILDING_MSG_FAILED if using LASSO_HTTP_METHOD_POST, LASSO_HTTP_METHOD_SOAP or LASSO_HTTP_METHOD_PAOS and building the `msg_body` failed.

### lasso_login_build_request_msg ()

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

#### Parameters

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

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

#### Parameters

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.

#### Parameters

login | a LassoLogin |

### lasso_login_dump ()

    gchar *
    lasso_login_dump (LassoLogin *login);

Dumps `login` content to an XML string.

#### Parameters

login | a LassoLogin |

#### Returns

the dump string. It must be freed by the caller.

[transfer full]

### lasso_login_get_assertion ()

    LassoNode *
    lasso_login_get_assertion (LassoLogin *login);

Return the last build assertion.

#### Parameters

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

    lasso_error_t
    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

#### Parameters

login | a LassoLogin |
remote_providerID | the providerID of the identity provider (may be NULL). | [allow-none]
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 ()

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

#### Parameters

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

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

#### Parameters

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

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

#### Parameters

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.

#### Parameters

login | a LassoLogin |

#### Returns

`TRUE` if user must be authenticated

### lasso_login_process_authn_request_msg ()

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

#### Parameters

login | a LassoLogin |
authn_request_msg | the authentication request received |

#### Returns

0 on success; or

- LASSO_PARAM_ERROR_BAD_TYPE_OR_NULL_OBJ if login is no a LassoLogin object,

- LASSO_PROFILE_ERROR_MISSING_REQUEST if `authn_request_msg` is NULL and no request as actually been processed or initialized &151; see `lasso_login_init_idp_initiated_authn_request()`,

- LASSO_PROFILE_ERROR_INVALID_MSG if the content of `authn_request_msg` cannot be parsed to as a valid lib:AuthnRequest messages for any support binding (mainly HTTP-Redirect, HTTP-Post and SOAP),

- LASSO_PROFILE_ERROR_MISSING_ISSUER if the parsed samlp2:AuthnRequest does not have a proper Issuer element,

- LASSO_PROFILE_ERROR_INVALID_REQUEST if the parsed message does not validate as a valid samlp2:AuthnRequest (SAMLv2) i.e. if there is no Issuer, or mutually exclusive attributes are used (ProtocolBinding and AssertionConsumerServiceIndex),

- LASSO_PROFILE_ERROR_INVALID_PROTOCOLPROFILE if the protocolProfile (ID-FFv1.2) or the protocolBinding (SAMLv2) is unsupported by Lasso,

- LASSO_PROFILE_ERROR_UNSUPPORTED_PROFILE if the protocolProfile (ID-FFv1.2) or the protocolBinding (SAMLv2) for the AssertionConsumer is unsupported by this provider implementation as indicated by its metadata file,

- LASSO_PROFILE_ERROR_UNKNOWN_PROVIDER, or LASSO_SERVER_ERROR_PROVIDER_NOT_FOUND if the metadata for the issuer of the request are absent from the LassoServer object of this profile,

- LASSO_DS_ERROR_SIGNATURE_NOT_FOUND if no signature could be found and signature validation is forced &151; by the service provider metadata with the AuthnRequestsSigned attribute (ID-FFv1.2&SAMLv2), the attribute WantAuthnRequestsSigned in the identity provider metadata file (SAMLv2) or as advised by the `lasso_profile_set_signature_verify_hint()` method),

- LASSO_DS_ERROR_SIGNATURE_VERIFICATION_FAILED if the signature validation failed on a present signature,

- LASSO_DS_ERROR_INVALID_SIGNATURE if the signature was malformed and a signature was present,

### lasso_login_process_authn_response_msg ()

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

Processes received authentication response.

#### Parameters

login | a LassoLogin |
authn_response_msg | the authentication response received |

#### Returns

0 on success; or

- LASSO_PARAM_ERROR_BAD_TYPE_OR_NULL_OBJ if login is not a LassoLogin object,

- LASSO_PARAM_ERROR_INVALID_VALUE if authn_response_msg is NULL,

- LASSO_SERVER_ERROR_PROVIDER_NOT_FOUND, if the issuing provider of the assertion is not registered in the LassoServer object,

- LASSO_PROFILE_ERROR_MISSING_ISSUER if the parsed samlp2:AuthnRequest does not have a proper Issuer element,

- LASSO_PROFILE_ERROR_MISSING_STATUS_CODE if the reponse is missing a `StatusCode` element,

- LASSO_PROFILE_STATUS_NOT_SUCCESS_ERROR if the identity provider returned a failure response,

- LASSO_PROFILE_ERROR_REQUEST_DENIED

  if the identity provider returned the specific status code `RequestDenied`,

- LASSO_PROFILE_ERROR_INVALID_MSG if the message is not a LassoSamlpResponse (ID-FF 1.2) or a LassoSamlp2ResponseMsg (SAML 2.0),

- LASSO_PROFILE_ERROR_UNSUPPORTED_PROFILE, if the received message format does not correspond to a binding supported by this function, the only supported binding by this function is HTTP POST,

- LASSO_PROFILE_ERROR_MISSING_SERVER the server object is needed to sign a message and it is missing,

- LASSO_PROFILE_ERROR_CANNOT_VERIFY_SIGNATURE if the validation of the signature of the message failed, a specific error code is available in `login->parent.signature_status`

- LASSO_LOGIN_ERROR_ASSERTION_DOES_NOT_MATCH_REQUEST_ID if the received response does not match the saved AuthenticationRequest ID,

- LASSO_PROFILE_ERROR_INVALID_ISSUER if the assertion issuer does not match the AuthenticationResponse issuer,

- LASSO_PROFILE_ERROR_NAME_IDENTIFIER_NOT_FOUND if not NameID could be found or decoded,

### lasso_login_process_paos_response_msg ()

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

### lasso_login_process_request_msg ()

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

Processes received artifact request.

#### Parameters

login | a LassoLogin |
request_msg | the artifact request received |

#### Returns

0 on success; or a negative value otherwise.

### lasso_login_process_response_msg ()

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

Processes received assertion response.

#### Parameters

login | a LassoLogin |
response_msg | the assertion response received |

#### Returns

0 on success; or

- 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_MSG if the message is not a LassoSamlpResponse (ID-FF 1.2) or a LassoSamlp2ResponseMsg (SAML 2.0),

- LASSO_PROFILE_ERROR_RESPONSE_DOES_NOT_MATCH_REQUEST if the response does not refer to the request or if the response refer to an unknown request and `strict-checking` is activated ,

- LASSO_LOGIN_ERROR_REQUEST_DENIED the identity provided returned a failure status of "RequestDenied"

- LASSO_LOGIN_ERROR_FEDERATION_NOT_FOUND if creation of a new federation was not allowed and none existed,

- LASSO_LOGIN_ERROR_UNKNOWN_PRINCIPAL if authentication failed or/and if the user cancelled the authentication,

- LASSO_LOGIN_ERROR_STATUS_NOT_SUCCESS, if the response status is a failure but we have no more precise error code to report it, you must look at the second level status in the response,

- LASSO_SERVER_ERROR_PROVIDER_NOT_FOUND, if the issuing provider of the assertion is unknown,

- LASSO_PROFILE_ERROR_INVALID_ISSUER the issuer of the assertion received, is not the expected one

- LASSO_PROFILE_ERROR_NAME_IDENTIFIER_NOT_FOUND no statement was fournd, or none statement contains a subject with a name identifier,

- LASSO_PROFILE_ERROR_MISSING_STATUS_CODE if the reponse is missing a `StatusCode` element,

- LASSO_PROFILE_ERROR_MISSING_ASSERTION if the message does not contain any assertion.

### lasso_login_validate_request_msg ()

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

Initializes a response to the authentication request received.

#### Parameters

login | a LassoLogin |
authentication_result | whether user has authenticated succesfully |
is_consent_obtained | whether user consent has been obtained |

#### Returns

0 on success; or

- LASSO_PARAM_ERROR_BAD_TYPE_OR_NULL_OBJ if login is not a LassoLogin object,

- LASSO_LOGIN_ERROR_REQUEST_DENIED

  if `authentication_result` if FALSE,

- LASSO_LOGIN_ERROR_INVALID_SIGNATURE if signature validation of the request failed,

- LASSO_LOGIN_ERROR_UNSIGNED_AUTHN_REQUEST if no signature was present on the request,

- LASSO_LOGIN_ERROR_FEDERATION_NOT_FOUND if federation policy is LASSO_LIB_NAMEID_POLICY_TYPE_NONE and no federation was found in the LassoIdentity object (ID-FF 1.2 case)

- LASSO_LOGIN_ERROR_INVALID_NAMEIDPOLICY if request policy is not one of LASSO_LIB_NAMEID_POLICY_TYPE_FEDERATED or LASSO_LIB_NAMEID_POLICY_TYPE_ANY (ID-FF 1.2 case) or if no NameID policy was defined or the AllowCreate request flag is FALSE (SAML 2.0 case),

- LASSO_LOGIN_ERROR_CONSENT_NOT_OBTAINED if `is_consent_obtained` is FALSE and conssent was necessary (for example if the request does not communicate that consent was already obtained from the user),

- LASSO_SERVER_ERROR_PROVIDER_NOT_FOUND if the requesting provider is unknown,

## Types and Values

### struct LassoLogin

    struct LassoLogin {
    	LassoLoginProtocolProfile protocolProfile;
    	gchar *assertionArtifact;
    };

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.

#### Members

LassoLoginProtocolProfile `protocolProfile`; | the kind of binding used for this authentication request. |
gchar *`assertionArtifact`; | a string representing the artifact received through an artifact resolution. request |