Service Provider‎ > ‎

ECP for non web applications

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.

The easiest way to check this is by using the AAF ECP Validator service. Undertake the following steps on a Linux/OSX machine:

  1. Ensure you have Python available on your system path. We've tested with version 2.7.5, other versions should work as well but YMMV;
  2. Download the latest version of from Github;
  3. Ensure that you can successfully login to the Attribute Validator using your browser of choice. If there are any problems these must be fixed before continuing;
  4. Navigate to the list of Identity Providers within Federation Registry and find your Identity Providers listing (this might also be linked from your Federation Registry dashboard);
  5. Click on: 
    SAML > Endpoints > Single Sign On Services
  6. Take a copy of the location for the ECP endpoint associated with your Identity Provider, this will be used next as <ssourl>. 

    To help you identify the correct endpoint it should have the form: 

  7. Run the following command: 

    $> python <ssourl> https://ecpvalidator[.test] <your username> 

    You should receive output similar to the following if all is well or a specific error message for your attention. 

    $> python bradleybeddoes
    Enter password for login 'bradleybeddoes':
    The AAF ECP Validator was provided the following about your account via ECP session establishment:
    displayName:                  Bradley Beddoes
    Notice: This is example data only. Real ECP clients will work with data received by the service provider installed as part of their service. All AAF defined attributes are available.
    Raw JSON response: {"service":{"name":"AAF ECP Validator","version":"0.2.0"},"subject":{"principal":"!!mHCYKXzzZGZMtSOJ090wfSpE0hA=","display_name":"Bradley Beddoes"},"notice":"This is example data only. Real ECP clients will work with data received by the service provider installed as part of their service. All AAF defined attributes are available."} ECP session completed. $>
  8. Should you have errors and need extra output add the -d flag for debug output immediently after the client name as follows: 

    $> python -d <ssourl> https://ecpvalidator[.test] <your username>

Ensure your SP supports ECP

Enabling ECP support within your Shibboleth SP requires two changes.

1. 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.

2. 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

The Python script shown above is a reasonably complete ECP client implementation based on above. 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). You can check each IdP using the AAF ECP Validator service documented previously.