![]() | ![]() | ![]() | Lasso Reference Manual | ![]() |
---|
LassoLoginLassoLogin — Single Sign-On and Federation Profile |
#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, constgchar *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, constchar *authenticationMethod, constchar *authenticationInstant, constchar *reauthenticateOnOrAfter, constchar *notBefore, constchar *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, constgchar *remote_providerID, LassoHttpMethod http_method);gint lasso_login_init_idp_initiated_authn_request (LassoLogin *login, constgchar *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, constchar *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, constchar *content);
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 personnal informations. The explicit user agreement is necessary before proceeding to Identity Federation.
The service provider must implement the following process:
creating an authentication request (LassoLibAuthnRequest) with
lasso_login_init_authn_request()
;
sending it to the identity provider with
lasso_login_build_authn_request_msg()
;
receiving and processing the answer:
lasso_login_process_authn_response_msg()
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()
.
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: /\n\nRedirected to site root\n");
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.
typedef enum { LASSO_LOGIN_PROTOCOL_PROFILE_BRWS_ART = 1, LASSO_LOGIN_PROTOCOL_PROFILE_BRWS_POST, LASSO_LOGIN_PROTOCOL_PROFILE_BRWS_LECP, } LassoLoginProtocolProfile;
Identifies the two possible profiles for Single Sign-On and Federation.
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 |
void lasso_login_destroy (LassoLogin *login);
Destroys a LassoLogin object.
login : | a LassoLogin |
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. |
LassoLogin* lasso_login_new_from_dump (LassoServer *server, constgchar *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. |
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. |
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. |
int lasso_login_build_assertion (LassoLogin *login, constchar *authenticationMethod, constchar *authenticationInstant, constchar *reauthenticateOnOrAfter, constchar *notBefore, constchar *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. |
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. |
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. |
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. |
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. |
gint lasso_login_init_authn_request (LassoLogin *login, constgchar *remote_providerID, LassoHttpMethod http_method);
Initializes a new lib: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. |
gint lasso_login_init_idp_initiated_authn_request (LassoLogin *login, constgchar *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. |
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. |
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
|
gboolean lasso_login_must_authenticate (LassoLogin *login);
Evaluates if user must be authenticated.
login : | a LassoLogin |
Returns : | TRUE if user must be authenticated
|
int lasso_login_process_authn_request_msg (LassoLogin *login, constchar *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. |
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. |
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. |
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. |
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. |
int lasso_login_set_encryptedResourceId (LassoLogin *login,LassoDiscoEncryptedResourceID *encryptedResourceId);
...
login : | a LassoLogin |
encryptedResourceId : | |
Returns : | 0 on success; or a negative value otherwise. |
int lasso_login_set_resourceId (LassoLogin *login, constchar *content);
...
login : | a LassoLogin |
content : | |
Returns : | 0 on success; or a negative value otherwise. |
<< LassoProfile | LassoLecp >> |