ECP Overview

The Enhanced Client or Proxy profile is an adaptation of the SAML profile used for Browser SSO with the parts that were designed around the limitations of a browser removed.

It is designed for clients such as:

  • Desktop applications;
  • Server-side code running in a web application; and
  • Anything else that isn't a browser.

On the backend ECP communications occur over (secured) HTTP requests.

ECP isn't easy

Enabling an application (client) to use ECP is a complex process. You will need to understand the details of the specific SAML interactions between the IdP, DS, SP and your application at a low level. While there are some examples of libraries provided for different languages you'll likely need to start from scratch.

As each client will be reasonably unique AAF support will be limited in how much assistance we can provide you.

Developers who have successfully completed building a client with ECP support indicate a time frame of at least 4 weeks work to understand the ECP space, write the code and debug all the interactions.

It is recommended that you read the ECP SAML 2 specification before going any further to ensure you have a full understanding of what you're about to undertake.

General Flow

The following is adapted from

A basic summary of what your ECP client code is responsible for:

  1.  Send special HTTP headers on every request to advertise ECP support to the SP.
  2.  Detect the special PAOS content type in a response to trigger the profile.
  3. Save off the response location provided by the SP in a SOAP header, as well as optional RelayState.
  4.  Check for an optional set of "supported IdPs" from the SP in a SOAP header, filtered against IdP(s) the client supports.
  5.  Route the SOAP body from the SP to the IdP along with the user's credentials, generally using HTTP basic auth, making sure to strongly verify the IdP's identity while doing so.
  6. Compare the response location provided by the IdP in a SOAP header to the one from the SP and scream bloody murder if they don't match.
  7. Route the SOAP body from the IdP back to the SP, along with any RelayState information saved from earlier.
  8. Check for a 200 or 302 response from the SP, indicating success or a redirect to the original resource. You can follow a redirect, or simply preserve the original request from the beginning of the process internally and replay it.

At each step, cookies might be involved (particularly with the SP) and need to be handled properly.

Before you start development

Ensure your IdP supports ECP

Before you can build an application with ECP support you must ensure that your IdP has been configured to support ECP.

Ensure your SP supports ECP

Enabling ECP support within your Shibboleth SP requires two changes. 

  • Edit the file /etc/shibboleth/shibboleth2.xml adding ECP="true" to you <SSO> element.

 For example:<SSO discoveryProtocol="SAMLDS" ECP="true" discoveryURL="">SAML2 SAML1</SSO>

Once complete restart the shibd process to pickup the change.

  • Edit your SP record within AAF Federation Registry to include a new assertion endpoint with the following details:

Profile: urn:oasis:names:tc:SAML:2.0:bindings:PAOS

Location: https://<your server>/Shibboleth.sso/SAML2/ECP

For example:
Profile: urn:oasis:names:tc:SAML:2.0:bindings:PAOS

Known Implementations

The following is adapted from

 Enabling its debug mode and following the flows between IdP and SP may further assist developers in understand the finer details of the conversion which happens between IdP and SP.

Useful log files

Once your IdP has been shown to correctly work with ECP as above your best source of error logging in the Shibboleth SP log file.

This is located at /var/log/shibboleth/shibd.log

As a general rule it is best to have this set to full debug mode when doing initial development. Full details on configuring appropriate logging levels for your Shibboleth SP can be found on the Shibboleth website.

Session Management

The initial session establishment process between SP and IdP requires a number of soap packets and headers as defined above and in the specification. For most Identity Providers the act of actually authenticating will be carried out using HTTP Basic Auth and involves sending the username and password supplied to your application to the remote Identity Provider. It is critical that clients using Basic Authentication never log or otherwise store user credentials.


Once the full authentication process has been completed (which is quite slow and lengthy) a long lived session will be established directly with the service.

Your client MUST avoid continually undertaking the authentication process on every request it makes to the service. Not only will this be incredibly slow but it will put unwanted load on the users Identity Provider and associated infrastructure.

Instead once authentication is complete you will receive a cookie named as follows:


Where the XXX.... component of the name will be unique for every session which is established.

Your client MUST store this cookie value for the time you expect your user to interact with the remote service and supply it with all subsequent HTTP requests to the service.

Supporting Multiple Identity Providers

In order to support multiple Identity Providers your client application must provide users a way to select their home organisation much like the AAF hosted discovery service does for web base applications.

Additionally each IdP which your client offers must support ECP using basic authentication (or an alternative authentication mechanism which your client code understands how to interact with).