path: root/docs/reference/tmpl/login.sgml

<!-- ##### SECTION Title ##### -->
LassoLogin

<!-- ##### SECTION Short_Description ##### -->
Single Sign-On and Federation Profile

<!-- ##### SECTION Long_Description ##### -->
<para>
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.
</para>

<para>
The service provider must implement the following process:
<itemizedlist>
 <listitem><para>creating an authentication request (#LassoLibAuthnRequest) with
 lasso_login_init_authn_request();</para></listitem>
 <listitem><para>sending it to the identity provider with
 lasso_login_build_authn_request_msg();</para></listitem>
 <listitem><para>receiving and processing the answer:
   <itemizedlist>
     <listitem>either an authentication response with
     lasso_login_process_authn_response_msg()</listitem>
     <listitem>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().</listitem>
   </itemizedlist>
   </para></listitem>
</itemizedlist>
</para>

<example>
<title>Service Provider Login URL</title>
<programlisting>
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);
</programlisting>
</example>

<example>
<title>Service Provider Assertion Consumer Service URL</title>
<programlisting>
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");
</programlisting>
</example>

<!-- ##### SECTION See_Also ##### -->
<para>

</para>

<!-- ##### STRUCT LassoLogin ##### -->
<para>
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.
</para>

@protocolProfile: 
@assertionArtifact: 
@assertion: 

<!-- ##### ENUM LassoLoginProtocolProfile ##### -->
<para>
Identifies the two possible profiles for Single Sign-On and Federation.
</para>

@LASSO_LOGIN_PROTOCOL_PROFILE_BRWS_ART: 
@LASSO_LOGIN_PROTOCOL_PROFILE_BRWS_POST: 

<!-- ##### FUNCTION lasso_login_new ##### -->
<para>

</para>

@server: 
@Returns: 


<!-- ##### FUNCTION lasso_login_destroy ##### -->
<para>

</para>

@login: 


<!-- ##### FUNCTION lasso_login_dump ##### -->
<para>

</para>

@login: 
@Returns: 


<!-- ##### FUNCTION lasso_login_new_from_dump ##### -->
<para>

</para>

@server: 
@dump: 
@Returns: 


<!-- ##### FUNCTION lasso_login_accept_sso ##### -->
<para>

</para>

@login: 
@Returns: 


<!-- ##### FUNCTION lasso_login_build_artifact_msg ##### -->
<para>

</para>

@login: 
@http_method: 
@Returns: 


<!-- ##### FUNCTION lasso_login_build_assertion ##### -->
<para>

</para>

@login: 
@authenticationMethod: 
@authenticationInstant: 
@reauthenticateOnOrAfter: 
@notBefore: 
@notOnOrAfter: 
@Returns: 


<!-- ##### FUNCTION lasso_login_build_authn_request_msg ##### -->
<para>

</para>

@login: 
@Returns: 


<!-- ##### FUNCTION lasso_login_build_authn_response_msg ##### -->
<para>

</para>

@login: 
@Returns: 


<!-- ##### FUNCTION lasso_login_build_request_msg ##### -->
<para>

</para>

@login: 
@Returns: 


<!-- ##### FUNCTION lasso_login_build_response_msg ##### -->
<para>

</para>

@login: 
@remote_providerID: 
@Returns: 


<!-- ##### FUNCTION lasso_login_init_authn_request ##### -->
<para>

</para>

@login: 
@remote_providerID: 
@http_method: 
@Returns: 


<!-- ##### FUNCTION lasso_login_init_idp_initiated_authn_request ##### -->
<para>

</para>

@login: 
@remote_providerID: 
@Returns: 


<!-- ##### FUNCTION lasso_login_init_request ##### -->
<para>

</para>

@login: 
@response_msg: 
@response_http_method: 
@Returns: 


<!-- ##### FUNCTION lasso_login_must_ask_for_consent ##### -->
<para>

</para>

@login: 
@Returns: 


<!-- ##### FUNCTION lasso_login_must_authenticate ##### -->
<para>

</para>

@login: 
@Returns: 


<!-- ##### FUNCTION lasso_login_process_authn_request_msg ##### -->
<para>

</para>

@login: 
@authn_request_msg: 
@Returns: 


<!-- ##### FUNCTION lasso_login_process_authn_response_msg ##### -->
<para>

</para>

@login: 
@authn_response_msg: 
@Returns: 


<!-- ##### FUNCTION lasso_login_process_request_msg ##### -->
<para>

</para>

@login: 
@request_msg: 
@Returns: 


<!-- ##### FUNCTION lasso_login_process_response_msg ##### -->
<para>

</para>

@login: 
@response_msg: 
@Returns: 


<!-- ##### FUNCTION lasso_login_validate_request_msg ##### -->
<para>

</para>

@login: 
@authentication_result: 
@is_consent_obtained: 
@Returns: 


<!-- ##### FUNCTION lasso_login_set_encryptedResourceId ##### -->
<para>

</para>

@login: 
@encryptedResourceId: 
@Returns: 


<!-- ##### FUNCTION lasso_login_set_resourceId ##### -->
<para>

</para>

@login: 
@content: 
@Returns: 
<!-- # Unused Parameters # -->
@resourceId: