Introduction

The LassoEcp object is used to implement a SAMLv2 ECP client. If you want to support ECP in a SP see [ecp-sp]. If you want to support ECP in a IdP see [ecp-idp].

ECP Operational Steps

SAML2 Profile for ECP (Section 4.2) defines these steps for an ECP transaction

lasso_ecp_is_provider_in_sp_idplist ()

gboolean
lasso_ecp_is_provider_in_sp_idplist (LassoEcp *ecp,
                                     const gchar *entity_id);

Check to see if the provider with entity_id is in the ecp IDPList returned by the SP.

lasso_ecp_is_idp_entry_known_idp_supporting_ecp ()

gboolean
lasso_ecp_is_idp_entry_known_idp_supporting_ecp
                               (LassoEcp *ecp,
                                const LassoSamlp2IDPEntry *idp_entry);

Check to see if the idp_entry is in the entity_id_list

lasso_ecp_set_known_sp_provided_idp_entries_supporting_ecp ()

void
lasso_ecp_set_known_sp_provided_idp_entries_supporting_ecp
                               (LassoEcp *ecp);

The SP may provide a list of LassoSamlp2IDPEntry (LassoEcp.sp_idp_list) which it trusts. The ECP client has a list of IDP EntityID's it knows supports ECP (LassoEcp.known_idp_entity_ids_supporting_ecp). The set of possible IDP's which can service the SP's authn request are the interesection of these two lists (the IDP's the SP approves and IDP's the ECP knows about). This find the common members between the two lists and assign them to LassoEcp.known_sp_provided_idp_entries_supporting_ecp.

lasso_ecp_has_sp_idplist ()

gboolean
lasso_ecp_has_sp_idplist (LassoEcp *ecp);

Returns TRUE if the SP provided an IDP List, FALSE otherwise.

lasso_ecp_get_endpoint_url_by_entity_id ()

gchar *
lasso_ecp_get_endpoint_url_by_entity_id
                               (LassoEcp *ecp,
                                const gchar *entity_id);

Returns the SingleSignOnService SOAP endpoint URL for the specified entity_id . If the provider cannot be found or if the provider does not have a matching endpoint NULL will be returned.

lasso_ecp_process_sp_idp_list ()

int
lasso_ecp_process_sp_idp_list (LassoEcp *ecp,
                               const LassoSamlp2IDPList *sp_idp_list);

The SP may optionally send a list of IdP's it trusts in ecp:IDPList. The ecp:IDPList may not be complete if the IDPList.GetComplete is non-NULL. If so the IDPList.GetComplete is a URL where a complete IDPList may be fetched.

Whenever the IDPList is updated this function needs to be called because it sets the LassoEcp.known_sp_provided_idp_entries_supporting_ecp and the default IdP URL (LassoProfile.msg_url).

The LassoEcp client has a list of IdP's it knows supports ECP (LassoEcp.known_idp_entity_ids_supporting_ecp). The set of IdP's available to select from should be those in common between SP provided IdP list and those known by this ECP client to support ECP.

This routine sets the LassoEcp.known_sp_provided_idp_entries_supporting_ecp list to the common members (e.g. intersection) of the SP provided IdP list and the list of known IdP's supporting ECP.

A default IdP will be selected and it's endpoint URL will be assigned to LassoProfile.msg_url.

If the SP provided an IDP list then the default URL will be taken from first IDPEntry in LassoEcp.known_sp_provided_idp_entries_supporting_ecp otherwise it will be taken from LassoEcp.known_idp_entity_ids_supporting_ecp.

lasso_ecp_new ()

LassoEcp *
lasso_ecp_new (LassoServer *server);

Creates a new LassoEcp.

lasso_ecp_process_authn_request_msg ()

lasso_error_t
lasso_ecp_process_authn_request_msg (LassoEcp *ecp,
                                     const char *authn_request_msg);

This function implements the following ECP step: ECP Step 3, ECP determines IdP ECP Step 4, parse SP PAOS Authn request, build SOAP for IdP

This is to be used in an ECP client. The authn_request_msg is the SOAP PAOS message received from the SP in response to a resource request with an HTTP Accept header indicating PAOS support.

The following actions are implemented:

lasso_ecp_process_response_msg ()

lasso_error_t
lasso_ecp_process_response_msg (LassoEcp *ecp,
                                const char *response_msg);

The function implements ECP Step 7; parse IdP SOAP response and build PAOS response for SP.

See SAML Profile Section 4.2.4.5 PAOS Response Header Block: ECP to SP

This is to be used in an ECP client. The response_msg parameter contains the SOAP response from the IdP. We extract the ECP Header Block and body from it. We will generate a new PAOS message to send to the SP, the SOAP header will contain a paos:Response. If we received a paos:Request.MessageID in Step. 4 from the SP then we will copy it back to the paos:Response.refToMessageID. If we received a RelayState we will add that to the SOAP header as well.

To prevent a man-in-the-middle attack we verify the responseConsumerURL we received in Step 4 matches the ecp:Response.AssertionConsumerServiceURL we just received back from the IdP. If they do not match we return a LASSO_ECP_ERROR_ASSERTION_CONSUMER_URL_MISMATCH error and set the LassoProvider.msg_body to the appropriate SOAP fault.

The new PAOS message for the SP we are buiding contains the IdP response in the new SOAP body and the new SOAP headers will contain a paso:Response and optionally an ecp:RelayState.

After a successful return from this call you are ready to complete Step 7. and forward the response to the SP.

The PASO message is assigned to the LassoProvider.msg_body and the desination URL is assigned to the LassoProvider.msg_url.

lasso_ecp_destroy ()

void
lasso_ecp_destroy (LassoEcp *ecp);

Destroys a LassoEcp object

struct LassoEcp

struct LassoEcp {
	LassoProfile parent;

	gchar *assertion_consumer_url;
	gchar *message_id;
	gchar *response_consumer_url;
	gchar *relaystate;
	LassoSaml2NameID *issuer;
	gchar *provider_name;
	gboolean is_passive;
	LassoSamlp2IDPList *sp_idp_list;
	GList *known_sp_provided_idp_entries_supporting_ecp; /* of LassoSamlp2IDPEntry */
	GList *known_idp_entity_ids_supporting_ecp;	         /* of strings */
};