<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>LassoEcp: Lasso Reference Manual</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="index.html" title="Lasso Reference Manual">
<link rel="up" href="saml2.html" title="SAML 2.0 Single Sign On profiles">
<link rel="prev" href="lasso-LassoNameIdManagement.html" title="LassoNameIdManagement">
<link rel="next" href="lasso-Utility-functions-for-SAML-2.0.html" title="Utility functions for SAML 2.0">
<meta name="generator" content="GTK-Doc V1.28 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle">
<td width="100%" align="left" class="shortcuts">
<a href="#" class="shortcut">Top</a><span id="nav_description"> <span class="dim">|</span>
<a href="#lasso-LassoEcp.description" class="shortcut">Description</a></span>
</td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
<td><a accesskey="u" href="saml2.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
<td><a accesskey="p" href="lasso-LassoNameIdManagement.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
<td><a accesskey="n" href="lasso-Utility-functions-for-SAML-2.0.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
</tr></table>
<div class="refentry">
<a name="lasso-LassoEcp"></a><div class="titlepage"></div>
<div class="refnamediv"><table width="100%"><tr>
<td valign="top">
<h2><span class="refentrytitle"><a name="lasso-LassoEcp.top_of_page"></a>LassoEcp</span></h2>
<p>LassoEcp — Enhanced Client or Proxy Profile (SAMLv2)</p>
</td>
<td class="gallery_image" valign="top" align="right"></td>
</tr></table></div>
<div class="refsect1">
<a name="lasso-LassoEcp.functions"></a><h2>Functions</h2>
<div class="informaltable"><table class="informaltable" width="100%" border="0">
<colgroup>
<col width="150px" class="functions_return">
<col class="functions_name">
</colgroup>
<tbody>
<tr>
<td class="function_type">
<span class="returnvalue">gboolean</span>
</td>
<td class="function_name">
<a class="link" href="lasso-LassoEcp.html#lasso-ecp-is-provider-in-sp-idplist" title="lasso_ecp_is_provider_in_sp_idplist ()">lasso_ecp_is_provider_in_sp_idplist</a> <span class="c_punctuation">()</span>
</td>
</tr>
<tr>
<td class="function_type">
<span class="returnvalue">gboolean</span>
</td>
<td class="function_name">
<a class="link" href="lasso-LassoEcp.html#lasso-ecp-is-idp-entry-known-idp-supporting-ecp" title="lasso_ecp_is_idp_entry_known_idp_supporting_ecp ()">lasso_ecp_is_idp_entry_known_idp_supporting_ecp</a> <span class="c_punctuation">()</span>
</td>
</tr>
<tr>
<td class="function_type">
<span class="returnvalue">void</span>
</td>
<td class="function_name">
<a class="link" href="lasso-LassoEcp.html#lasso-ecp-set-known-sp-provided-idp-entries-supporting-ecp" title="lasso_ecp_set_known_sp_provided_idp_entries_supporting_ecp ()">lasso_ecp_set_known_sp_provided_idp_entries_supporting_ecp</a> <span class="c_punctuation">()</span>
</td>
</tr>
<tr>
<td class="function_type">
<span class="returnvalue">gboolean</span>
</td>
<td class="function_name">
<a class="link" href="lasso-LassoEcp.html#lasso-ecp-has-sp-idplist" title="lasso_ecp_has_sp_idplist ()">lasso_ecp_has_sp_idplist</a> <span class="c_punctuation">()</span>
</td>
</tr>
<tr>
<td class="function_type">
<span class="returnvalue">gchar</span> *
</td>
<td class="function_name">
<a class="link" href="lasso-LassoEcp.html#lasso-ecp-get-endpoint-url-by-entity-id" title="lasso_ecp_get_endpoint_url_by_entity_id ()">lasso_ecp_get_endpoint_url_by_entity_id</a> <span class="c_punctuation">()</span>
</td>
</tr>
<tr>
<td class="function_type">
<span class="returnvalue">int</span>
</td>
<td class="function_name">
<a class="link" href="lasso-LassoEcp.html#lasso-ecp-process-sp-idp-list" title="lasso_ecp_process_sp_idp_list ()">lasso_ecp_process_sp_idp_list</a> <span class="c_punctuation">()</span>
</td>
</tr>
<tr>
<td class="function_type">
<a class="link" href="lasso-LassoEcp.html#LassoEcp" title="struct LassoEcp"><span class="returnvalue">LassoEcp</span></a> *
</td>
<td class="function_name">
<a class="link" href="lasso-LassoEcp.html#lasso-ecp-new" title="lasso_ecp_new ()">lasso_ecp_new</a> <span class="c_punctuation">()</span>
</td>
</tr>
<tr>
<td class="function_type">
<span class="returnvalue">lasso_error_t</span>
</td>
<td class="function_name">
<a class="link" href="lasso-LassoEcp.html#lasso-ecp-process-authn-request-msg" title="lasso_ecp_process_authn_request_msg ()">lasso_ecp_process_authn_request_msg</a> <span class="c_punctuation">()</span>
</td>
</tr>
<tr>
<td class="function_type">
<span class="returnvalue">lasso_error_t</span>
</td>
<td class="function_name">
<a class="link" href="lasso-LassoEcp.html#lasso-ecp-process-response-msg" title="lasso_ecp_process_response_msg ()">lasso_ecp_process_response_msg</a> <span class="c_punctuation">()</span>
</td>
</tr>
<tr>
<td class="function_type">
<span class="returnvalue">void</span>
</td>
<td class="function_name">
<a class="link" href="lasso-LassoEcp.html#lasso-ecp-destroy" title="lasso_ecp_destroy ()">lasso_ecp_destroy</a> <span class="c_punctuation">()</span>
</td>
</tr>
</tbody>
</table></div>
</div>
<div class="refsect1">
<a name="lasso-LassoEcp.other"></a><h2>Types and Values</h2>
<div class="informaltable"><table class="informaltable" width="100%" border="0">
<colgroup>
<col width="150px" class="name">
<col class="description">
</colgroup>
<tbody><tr>
<td class="datatype_keyword">struct</td>
<td class="function_name"><a class="link" href="lasso-LassoEcp.html#LassoEcp" title="struct LassoEcp">LassoEcp</a></td>
</tr></tbody>
</table></div>
</div>
<div class="refsect1">
<a name="lasso-LassoEcp.description"></a><h2>Description</h2>
<div class="refsect2">
<a name="id-1.3.5.5.5.2"></a><h3>Introduction</h3>
<p>The <a class="link" href="lasso-LassoEcp.html#LassoEcp" title="struct LassoEcp"><span class="type">LassoEcp</span></a> 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].</p>
</div>
<hr>
<div class="refsect2">
<a name="id-1.3.5.5.5.3"></a><h3>ECP Operational Steps</h3>
<p>SAML2 Profile for ECP (Section 4.2) defines these steps for an ECP
transaction</p>
<div class="orderedlist"><ol class="orderedlist" type="1">
<li class="listitem"><p>ECP issues HTTP Request to SP</p></li>
<li class="listitem"><p>SP issues <samlp:AuthnRequest> to ECP using PAOS</p></li>
<li class="listitem"><p>ECP determines IdP</p></li>
<li class="listitem"><p>ECP conveys <samlp:AuthnRequest> to IdP using SOAP</p></li>
<li class="listitem"><p>IdP identifies principal</p></li>
<li class="listitem"><p>IdP issues <samlp:Response> to ECP, targeted at SP using SOAP</p></li>
<li class="listitem"><p>ECP conveys <samlp:Response> to SP using PAOS</p></li>
<li class="listitem"><p>SP grants or denies access to principal</p></li>
</ol></div>
</div>
</div>
<div class="refsect1">
<a name="lasso-LassoEcp.functions_details"></a><h2>Functions</h2>
<div class="refsect2">
<a name="lasso-ecp-is-provider-in-sp-idplist"></a><h3>lasso_ecp_is_provider_in_sp_idplist ()</h3>
<pre class="programlisting"><span class="returnvalue">gboolean</span>
lasso_ecp_is_provider_in_sp_idplist (<em class="parameter"><code><a class="link" href="lasso-LassoEcp.html#LassoEcp" title="struct LassoEcp"><span class="type">LassoEcp</span></a> *ecp</code></em>,
<em class="parameter"><code>const <span class="type">gchar</span> *entity_id</code></em>);</pre>
<p>Check to see if the provider with <em class="parameter"><code>entity_id</code></em>
is in the
ecp IDPList returned by the SP.</p>
<div class="refsect3">
<a name="lasso-ecp-is-provider-in-sp-idplist.parameters"></a><h4>Parameters</h4>
<div class="informaltable"><table class="informaltable" width="100%" border="0">
<colgroup>
<col width="150px" class="parameters_name">
<col class="parameters_description">
<col width="200px" class="parameters_annotations">
</colgroup>
<tbody>
<tr>
<td class="parameter_name"><p>ecp</p></td>
<td class="parameter_description"><p>a <a class="link" href="lasso-LassoEcp.html#LassoEcp" title="struct LassoEcp"><span class="type">LassoEcp</span></a></p></td>
<td class="parameter_annotations"> </td>
</tr>
<tr>
<td class="parameter_name"><p>entity_id</p></td>
<td class="parameter_description"><p>EntityID to check if member of <span class="type">LassoEcp.IDPList</span></p></td>
<td class="parameter_annotations"> </td>
</tr>
</tbody>
</table></div>
</div>
<div class="refsect3">
<a name="lasso-ecp-is-provider-in-sp-idplist.returns"></a><h4>Returns</h4>
<p> TRUE if <em class="parameter"><code>entity_id</code></em>
is in <span class="type">LassoEcp.IDPList</span>, FALSE otherwise</p>
</div>
</div>
<hr>
<div class="refsect2">
<a name="lasso-ecp-is-idp-entry-known-idp-supporting-ecp"></a><h3>lasso_ecp_is_idp_entry_known_idp_supporting_ecp ()</h3>
<pre class="programlisting"><span class="returnvalue">gboolean</span>
lasso_ecp_is_idp_entry_known_idp_supporting_ecp
(<em class="parameter"><code><a class="link" href="lasso-LassoEcp.html#LassoEcp" title="struct LassoEcp"><span class="type">LassoEcp</span></a> *ecp</code></em>,
<em class="parameter"><code>const <a class="link" href="lasso-LassoSamlp2IDPEntry.html#LassoSamlp2IDPEntry" title="struct LassoSamlp2IDPEntry"><span class="type">LassoSamlp2IDPEntry</span></a> *idp_entry</code></em>);</pre>
<p>Check to see if the <em class="parameter"><code>idp_entry</code></em>
is in the <em class="parameter"><code>entity_id_list</code></em>
</p>
<div class="refsect3">
<a name="lasso-ecp-is-idp-entry-known-idp-supporting-ecp.parameters"></a><h4>Parameters</h4>
<div class="informaltable"><table class="informaltable" width="100%" border="0">
<colgroup>
<col width="150px" class="parameters_name">
<col class="parameters_description">
<col width="200px" class="parameters_annotations">
</colgroup>
<tbody>
<tr>
<td class="parameter_name"><p>ecp</p></td>
<td class="parameter_description"><p>a <a class="link" href="lasso-LassoEcp.html#LassoEcp" title="struct LassoEcp"><span class="type">LassoEcp</span></a></p></td>
<td class="parameter_annotations"> </td>
</tr>
<tr>
<td class="parameter_name"><p>idp_entry</p></td>
<td class="parameter_description"><p><a class="link" href="lasso-LassoSamlp2IDPEntry.html#LassoSamlp2IDPEntry" title="struct LassoSamlp2IDPEntry"><span class="type">LassoSamlp2IDPEntry</span></a> to check if member of <em class="parameter"><code>entity_id_list</code></em>
</p></td>
<td class="parameter_annotations"> </td>
</tr>
</tbody>
</table></div>
</div>
<div class="refsect3">
<a name="lasso-ecp-is-idp-entry-known-idp-supporting-ecp.returns"></a><h4>Returns</h4>
<p> TRUE if <em class="parameter"><code>entity_id</code></em>
is in <em class="parameter"><code>idp_list</code></em>
, FALSE otherwise</p>
</div>
</div>
<hr>
<div class="refsect2">
<a name="lasso-ecp-set-known-sp-provided-idp-entries-supporting-ecp"></a><h3>lasso_ecp_set_known_sp_provided_idp_entries_supporting_ecp ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>
lasso_ecp_set_known_sp_provided_idp_entries_supporting_ecp
(<em class="parameter"><code><a class="link" href="lasso-LassoEcp.html#LassoEcp" title="struct LassoEcp"><span class="type">LassoEcp</span></a> *ecp</code></em>);</pre>
<p>The SP may provide a list of <a class="link" href="lasso-LassoSamlp2IDPEntry.html#LassoSamlp2IDPEntry" title="struct LassoSamlp2IDPEntry"><span class="type">LassoSamlp2IDPEntry</span></a>
(<span class="type">LassoEcp.sp_idp_list</span>) which it trusts. The ECP client
has a list of IDP EntityID's it knows supports ECP
(<span class="type">LassoEcp.known_idp_entity_ids_supporting_ecp</span>). 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
<span class="type">LassoEcp.known_sp_provided_idp_entries_supporting_ecp</span>.</p>
<div class="refsect3">
<a name="lasso-ecp-set-known-sp-provided-idp-entries-supporting-ecp.parameters"></a><h4>Parameters</h4>
<div class="informaltable"><table class="informaltable" width="100%" border="0">
<colgroup>
<col width="150px" class="parameters_name">
<col class="parameters_description">
<col width="200px" class="parameters_annotations">
</colgroup>
<tbody><tr>
<td class="parameter_name"><p>ecp</p></td>
<td class="parameter_description"><p>a <a class="link" href="lasso-LassoEcp.html#LassoEcp" title="struct LassoEcp"><span class="type">LassoEcp</span></a></p></td>
<td class="parameter_annotations"> </td>
</tr></tbody>
</table></div>
</div>
</div>
<hr>
<div class="refsect2">
<a name="lasso-ecp-has-sp-idplist"></a><h3>lasso_ecp_has_sp_idplist ()</h3>
<pre class="programlisting"><span class="returnvalue">gboolean</span>
lasso_ecp_has_sp_idplist (<em class="parameter"><code><a class="link" href="lasso-LassoEcp.html#LassoEcp" title="struct LassoEcp"><span class="type">LassoEcp</span></a> *ecp</code></em>);</pre>
<p>Returns TRUE if the SP provided an IDP List, FALSE otherwise.</p>
<div class="refsect3">
<a name="lasso-ecp-has-sp-idplist.parameters"></a><h4>Parameters</h4>
<div class="informaltable"><table class="informaltable" width="100%" border="0">
<colgroup>
<col width="150px" class="parameters_name">
<col class="parameters_description">
<col width="200px" class="parameters_annotations">
</colgroup>
<tbody><tr>
<td class="parameter_name"><p>ecp</p></td>
<td class="parameter_description"><p>a <a class="link" href="lasso-LassoEcp.html#LassoEcp" title="struct LassoEcp"><span class="type">LassoEcp</span></a></p></td>
<td class="parameter_annotations"> </td>
</tr></tbody>
</table></div>
</div>
</div>
<hr>
<div class="refsect2">
<a name="lasso-ecp-get-endpoint-url-by-entity-id"></a><h3>lasso_ecp_get_endpoint_url_by_entity_id ()</h3>
<pre class="programlisting"><span class="returnvalue">gchar</span> *
lasso_ecp_get_endpoint_url_by_entity_id
(<em class="parameter"><code><a class="link" href="lasso-LassoEcp.html#LassoEcp" title="struct LassoEcp"><span class="type">LassoEcp</span></a> *ecp</code></em>,
<em class="parameter"><code>const <span class="type">gchar</span> *entity_id</code></em>);</pre>
<p>Returns the SingleSignOnService SOAP endpoint URL for the specified
<em class="parameter"><code>entity_id</code></em>
. If the provider cannot be found or if the provider does
not have a matching endpoint NULL will be returned.</p>
<div class="refsect3">
<a name="lasso-ecp-get-endpoint-url-by-entity-id.parameters"></a><h4>Parameters</h4>
<div class="informaltable"><table class="informaltable" width="100%" border="0">
<colgroup>
<col width="150px" class="parameters_name">
<col class="parameters_description">
<col width="200px" class="parameters_annotations">
</colgroup>
<tbody>
<tr>
<td class="parameter_name"><p>ecp</p></td>
<td class="parameter_description"><p>a <a class="link" href="lasso-LassoEcp.html#LassoEcp" title="struct LassoEcp"><span class="type">LassoEcp</span></a></p></td>
<td class="parameter_annotations"> </td>
</tr>
<tr>
<td class="parameter_name"><p>entity_id</p></td>
<td class="parameter_description"><p>the EntityID of the IdP</p></td>
<td class="parameter_annotations"> </td>
</tr>
</tbody>
</table></div>
</div>
<div class="refsect3">
<a name="lasso-ecp-get-endpoint-url-by-entity-id.returns"></a><h4>Returns</h4>
<p> url (must be freed by caller)</p>
</div>
</div>
<hr>
<div class="refsect2">
<a name="lasso-ecp-process-sp-idp-list"></a><h3>lasso_ecp_process_sp_idp_list ()</h3>
<pre class="programlisting"><span class="returnvalue">int</span>
lasso_ecp_process_sp_idp_list (<em class="parameter"><code><a class="link" href="lasso-LassoEcp.html#LassoEcp" title="struct LassoEcp"><span class="type">LassoEcp</span></a> *ecp</code></em>,
<em class="parameter"><code>const <a class="link" href="lasso-LassoSamlp2IDPList.html#LassoSamlp2IDPList" title="struct LassoSamlp2IDPList"><span class="type">LassoSamlp2IDPList</span></a> *sp_idp_list</code></em>);</pre>
<p>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.</p>
<p>Whenever the IDPList is updated this function needs to be called
because it sets the
<span class="type">LassoEcp.known_sp_provided_idp_entries_supporting_ecp</span> and the
default IdP URL (<a class="link" href="lasso-LassoProfile.html#LassoProfile.msg-url"><span class="type">LassoProfile.msg_url</span></a>).</p>
<p>The <a class="link" href="lasso-LassoEcp.html#LassoEcp" title="struct LassoEcp"><span class="type">LassoEcp</span></a> client has a list of IdP's it knows supports ECP
(<span class="type">LassoEcp.known_idp_entity_ids_supporting_ecp</span>). 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.</p>
<p>This routine sets the
<span class="type">LassoEcp.known_sp_provided_idp_entries_supporting_ecp</span> list to the
common members (e.g. intersection) of the SP provided IdP list and
the list of known IdP's supporting ECP.</p>
<p>A default IdP will be selected and it's endpoint URL will be
assigned to <a class="link" href="lasso-LassoProfile.html#LassoProfile.msg-url"><span class="type">LassoProfile.msg_url</span></a>.</p>
<p>If the SP provided an IDP list then the default URL will be taken
from first IDPEntry in
<span class="type">LassoEcp.known_sp_provided_idp_entries_supporting_ecp</span> otherwise
it will be taken from <span class="type">LassoEcp.known_idp_entity_ids_supporting_ecp</span>.</p>
<div class="refsect3">
<a name="lasso-ecp-process-sp-idp-list.parameters"></a><h4>Parameters</h4>
<div class="informaltable"><table class="informaltable" width="100%" border="0">
<colgroup>
<col width="150px" class="parameters_name">
<col class="parameters_description">
<col width="200px" class="parameters_annotations">
</colgroup>
<tbody><tr>
<td class="parameter_name"><p>ecp</p></td>
<td class="parameter_description"><p>a <a class="link" href="lasso-LassoEcp.html#LassoEcp" title="struct LassoEcp"><span class="type">LassoEcp</span></a></p></td>
<td class="parameter_annotations"> </td>
</tr></tbody>
</table></div>
</div>
</div>
<hr>
<div class="refsect2">
<a name="lasso-ecp-new"></a><h3>lasso_ecp_new ()</h3>
<pre class="programlisting"><a class="link" href="lasso-LassoEcp.html#LassoEcp" title="struct LassoEcp"><span class="returnvalue">LassoEcp</span></a> *
lasso_ecp_new (<em class="parameter"><code><a class="link" href="lasso-LassoServer.html#LassoServer" title="struct LassoServer"><span class="type">LassoServer</span></a> *server</code></em>);</pre>
<p>Creates a new <a class="link" href="lasso-LassoEcp.html#LassoEcp" title="struct LassoEcp"><span class="type">LassoEcp</span></a>.</p>
<div class="refsect3">
<a name="lasso-ecp-new.returns"></a><h4>Returns</h4>
<p> a newly created <a class="link" href="lasso-LassoEcp.html#LassoEcp" title="struct LassoEcp"><span class="type">LassoEcp</span></a> object; or NULL if an error
occured</p>
</div>
</div>
<hr>
<div class="refsect2">
<a name="lasso-ecp-process-authn-request-msg"></a><h3>lasso_ecp_process_authn_request_msg ()</h3>
<pre class="programlisting"><span class="returnvalue">lasso_error_t</span>
lasso_ecp_process_authn_request_msg (<em class="parameter"><code><a class="link" href="lasso-LassoEcp.html#LassoEcp" title="struct LassoEcp"><span class="type">LassoEcp</span></a> *ecp</code></em>,
<em class="parameter"><code>const <span class="type">char</span> *authn_request_msg</code></em>);</pre>
<p>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</p>
<p>This is to be used in an ECP client. The <em class="parameter"><code>authn_request_msg</code></em>
is the
SOAP PAOS message received from the SP in response to a resource
request with an HTTP Accept header indicating PAOS support.</p>
<p>The following actions are implemented:</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem"><p>Extract the samlp:AuthnRequest from the SOAP body and build a
new SOAP message containing the samlp:AuthnRequest which will
be forwarded to the IdP. This new SOAP message is stored in the
<a class="link" href="lasso-LassoProfile.html#LassoProfile.msg-body"><span class="type">LassoProfile.msg_body</span></a>.</p></li>
<li class="listitem">
<p>Parse the SOAP header which will contain a paos:Request, a
ecp:Request and optionally a ecp:RelayState. Some of the data
in these headers need to be preserved for later processing steps.</p>
<div class="orderedlist"><ol class="orderedlist" type="1">
<li class="listitem"><p>The paos:Request.responseConsumerURL is copied to the
<span class="type">LassoEcp.response_consumer_url</span>. This is necessary because the
ECP client MUST assure it matches the
ecp:Response.AssertionConsumerServiceURL returned by the IdP to
prevent man-in-the-middle attacks. It must also match the
samlp:AuthnRequest.AssertionConsumerServiceURL.</p></li>
<li class="listitem"><p>If the paos:Request contained a messageID it is copied to
<span class="type">LassoEcp.message_id</span> so it can be returned in the subsequent
paos:Response.refToMessageID. This allows a provider to
correlate messages.</p></li>
<li class="listitem"><p>If an ecp:RelayState is present it is copied to
<span class="type">LassoEcp.relaystate</span>. This is necessary because in step 7 when
the ECP responds to the SP it must include RelayState provided in
the request.</p></li>
</ol></div>
</li>
<li class="listitem">
<p>In addition the following items are copied to the <a class="link" href="lasso-LassoEcp.html#LassoEcp" title="struct LassoEcp"><span class="type">LassoEcp</span></a> for
informational purposes:</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; ">
<li class="listitem"><p><span class="type">LassoEcp.issuer</span> = ecp:Request.Issuer</p></li>
<li class="listitem"><p><span class="type">LassoEcp.provider_name</span> = ecp:Request.ProviderName</p></li>
<li class="listitem"><p><span class="type">LassoEcp.is_passive</span> = ecp:Request.IsPassive</p></li>
<li class="listitem"><p><span class="type">LassoEcp.sp_idp_list</span> = ecp:Request.IDPList</p></li>
</ul></div>
</li>
</ul></div>
<div class="refsect2">
<a name="id-1.3.5.5.6.9.8"></a><h3>IdP Selection</h3>
<p>In Step 3. The ECP must determine the IdP to forward the
AuthnRequest to. There are two sets of IdP's which come into
play. The ECP client has a set of IdP's it knows about because
their metadata has been loaded into the <a class="link" href="lasso-LassoServer.html#LassoServer" title="struct LassoServer"><span class="type">LassoServer</span></a> object. The SP
may optionally send a list of IdP's in the ecp:Request that it
trusts.</p>
<p>The selected IdP *must* be one of the IdP's loaded into the
<a class="link" href="lasso-LassoServer.html#LassoServer" title="struct LassoServer"><span class="type">LassoServer</span></a> object from metadata because the IdP endpoints must be
known. Furthermore the IdP *must* support the SingleSignOnService
using the SOAP binding. Therefore the known IdP's are filtered for
those that match this criteria and a list of their EntityID's are
assigned to <span class="type">LassoEcp.known_idp_entity_ids_supporting_ecp</span>. The
selected IdP *must* be a member of this list.</p>
<p>The SP may optionally send a list of IdP's it trusts. If the SP
sends an IDPList the selected IdP should be a member of this list
and from above we know it must also be a member of the
<span class="type">LassoEcp.known_idp_entity_ids_supporting_ecp</span>. Therefore the
<span class="type">LassoEcp.known_sp_provided_idp_entries_supporting_ecp</span> list is set
to the common members (e.g. intersection) of the SP provided IdP
list and the list of known IdP's supporting ECP.</p>
<p>When making an IdP selection if the SP provided an IdP List (use
<code class="function">LassoEcp.lasso_ecp_has_sp_idplist()</code>) then it should be selected
from the <span class="type">LassoEcp.known_sp_provided_idp_entries_supporting_ecp</span>
list. Otherwise the IdP should be selected from
<span class="type">LassoEcp.known_idp_entity_ids_supporting_ecp</span>.</p>
<p>A default IdP will be selected using the above logic by picking the
first IdP in the appropriate list, it's endpoint URL will be
assigned to <a class="link" href="lasso-LassoProfile.html#LassoProfile.msg-url"><span class="type">LassoProfile.msg_url</span></a>. The above processing is
implemented by <code class="function">LassoEcp.lasso_ecp_process_sp_idp_list()</code> and if the
SP IDPList is updated this routine should be called.</p>
<p>A note about the 3 IdP lists. The <span class="type">LassoEcp.sp_idp_list.IDPList</span>
and <span class="type">LassoEcp.known_sp_provided_idp_entries_supporting_ecp</span> are
<span class="type">GList</span>'s of <a class="link" href="lasso-LassoSamlp2IDPEntry.html#LassoSamlp2IDPEntry" title="struct LassoSamlp2IDPEntry"><span class="type">LassoSamlp2IDPEntry</span></a> object which have a ProviderID,
Name, and Loc attribute. You may wish to use this SP provided
information when making a decision or presenting in a user
interface that allows a user to make a choice. The
<span class="type">LassoEcp.known_idp_entity_ids_supporting_ecp</span> is a <span class="type">GList</span> of
EntityID strings.</p>
<p>Given the EntityID of an IdP you can get the ECP endpoint by
calling <code class="function">LassoEcp.lasso_ecp_get_endpoint_url_by_entity_id()</code></p>
</div>
<hr>
<div class="refsect2">
<a name="id-1.3.5.5.6.9.9"></a><h3>Results</h3>
<p>After a successful return from this call you are ready to complete
Step 4. and forward the request the IdP.</p>
<p>The URL to send to the request to will be <a class="link" href="lasso-LassoProfile.html#LassoProfile.msg-url"><span class="type">LassoProfile.msg_url</span></a> (if
you accept the default IdP) and the body of the message to post
will be <a class="link" href="lasso-LassoProfile.html#LassoProfile.msg-body"><span class="type">LassoProfile.msg_body</span></a>.</p>
</div>
<hr>
<div class="refsect2">
<a name="id-1.3.5.5.6.9.10"></a><h3>Side Effects</h3>
<p>After a successful return the <a class="link" href="lasso-LassoEcp.html#LassoEcp" title="struct LassoEcp"><span class="type">LassoEcp</span></a> object will be updated with:</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem"><p>ecp->response_consumer_url = paos_request->responseConsumerURL</p></li>
<li class="listitem"><p>ecp->message_id = paos_request->messageID</p></li>
<li class="listitem"><p>ecp->relaystate = ecp_relaystate->RelayState</p></li>
<li class="listitem"><p>ecp->issuer = ecp_request->Issue</p></li>
<li class="listitem"><p>ecp->provider_name = ecp_request->ProviderName</p></li>
<li class="listitem"><p>ecp->is_passive = ecp_request->IsPassive</p></li>
<li class="listitem"><p>ecp->known_idp_entity_ids_supporting_ecp</p></li>
<li class="listitem"><p>ecp->sp_idp_list = ecp_request->IDPList</p></li>
<li class="listitem"><p>ecp->known_sp_provided_idp_entries_supporting_ecp</p></li>
</ul></div>
</div>
<div class="refsect3">
<a name="lasso-ecp-process-authn-request-msg.parameters"></a><h4>Parameters</h4>
<div class="informaltable"><table class="informaltable" width="100%" border="0">
<colgroup>
<col width="150px" class="parameters_name">
<col class="parameters_description">
<col width="200px" class="parameters_annotations">
</colgroup>
<tbody>
<tr>
<td class="parameter_name"><p>ecp</p></td>
<td class="parameter_description"><p>this <a class="link" href="lasso-LassoEcp.html#LassoEcp" title="struct LassoEcp"><span class="type">LassoEcp</span></a> object</p></td>
<td class="parameter_annotations"> </td>
</tr>
<tr>
<td class="parameter_name"><p>authn_request_msg</p></td>
<td class="parameter_description"><p>the PAOS authn request received from the SP</p></td>
<td class="parameter_annotations"> </td>
</tr>
</tbody>
</table></div>
</div>
</div>
<hr>
<div class="refsect2">
<a name="lasso-ecp-process-response-msg"></a><h3>lasso_ecp_process_response_msg ()</h3>
<pre class="programlisting"><span class="returnvalue">lasso_error_t</span>
lasso_ecp_process_response_msg (<em class="parameter"><code><a class="link" href="lasso-LassoEcp.html#LassoEcp" title="struct LassoEcp"><span class="type">LassoEcp</span></a> *ecp</code></em>,
<em class="parameter"><code>const <span class="type">char</span> *response_msg</code></em>);</pre>
<p>The function implements ECP Step 7; parse IdP SOAP response and
build PAOS response for SP.</p>
<p>See SAML Profile Section 4.2.4.5 PAOS Response Header Block: ECP to SP</p>
<p>This is to be used in an ECP client. The <em class="parameter"><code>response_msg</code></em>
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.</p>
<p>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
<span class="type">LASSO_ECP_ERROR_ASSERTION_CONSUMER_URL_MISMATCH</span> error and set the
<span class="type">LassoProvider.msg_body</span> to the appropriate SOAP fault.</p>
<p>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.</p>
<p>After a successful return from this call you are ready to complete
Step 7. and forward the response to the SP.</p>
<p>The PASO message is assigned to the <span class="type">LassoProvider.msg_body</span> and
the desination URL is assigned to the <span class="type">LassoProvider.msg_url</span>.</p>
<div class="refsect2">
<a name="id-1.3.5.5.6.10.11"></a><h3>Side Effects</h3>
<p>After a successful return the <a class="link" href="lasso-LassoEcp.html#LassoEcp" title="struct LassoEcp"><span class="type">LassoEcp</span></a> object will be updated with:</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem"><p>ecp->assertion_consumer_url = ecp_response->AssertionConsumerServiceURL</p></li>
<li class="listitem"><p>ecp.profile.msg_url = ecp->assertion_consumer_url</p></li>
<li class="listitem"><p>ecp.profile.msg_body_url = PAOS response to SP</p></li>
</ul></div>
</div>
<div class="refsect3">
<a name="lasso-ecp-process-response-msg.parameters"></a><h4>Parameters</h4>
<div class="informaltable"><table class="informaltable" width="100%" border="0">
<colgroup>
<col width="150px" class="parameters_name">
<col class="parameters_description">
<col width="200px" class="parameters_annotations">
</colgroup>
<tbody>
<tr>
<td class="parameter_name"><p>ecp</p></td>
<td class="parameter_description"><p>this <a class="link" href="lasso-LassoEcp.html#LassoEcp" title="struct LassoEcp"><span class="type">LassoEcp</span></a> object</p></td>
<td class="parameter_annotations"> </td>
</tr>
<tr>
<td class="parameter_name"><p>response_msg</p></td>
<td class="parameter_description"><p>the SOAP response from the IdP</p></td>
<td class="parameter_annotations"> </td>
</tr>
</tbody>
</table></div>
</div>
</div>
<hr>
<div class="refsect2">
<a name="lasso-ecp-destroy"></a><h3>lasso_ecp_destroy ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>
lasso_ecp_destroy (<em class="parameter"><code><a class="link" href="lasso-LassoEcp.html#LassoEcp" title="struct LassoEcp"><span class="type">LassoEcp</span></a> *ecp</code></em>);</pre>
<p>Destroys a <a class="link" href="lasso-LassoEcp.html#LassoEcp" title="struct LassoEcp"><span class="type">LassoEcp</span></a> object</p>
<div class="refsect3">
<a name="lasso-ecp-destroy.parameters"></a><h4>Parameters</h4>
<div class="informaltable"><table class="informaltable" width="100%" border="0">
<colgroup>
<col width="150px" class="parameters_name">
<col class="parameters_description">
<col width="200px" class="parameters_annotations">
</colgroup>
<tbody><tr>
<td class="parameter_name"><p>ecp</p></td>
<td class="parameter_description"><p>a <a class="link" href="lasso-LassoEcp.html#LassoEcp" title="struct LassoEcp"><span class="type">LassoEcp</span></a></p></td>
<td class="parameter_annotations"> </td>
</tr></tbody>
</table></div>
</div>
</div>
</div>
<div class="refsect1">
<a name="lasso-LassoEcp.other_details"></a><h2>Types and Values</h2>
<div class="refsect2">
<a name="LassoEcp"></a><h3>struct LassoEcp</h3>
<pre class="programlisting">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 */
};
</pre>
</div>
</div>
</div>
<div class="footer">
<hr>Generated by GTK-Doc V1.28</div>
</body>
</html>