Enabling ECP support

ECP Overview

The ECP 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.

Version 2.0 of the ECP profile is now standardised, and is the best choice to base a new implementation or project around. Version 2.0 is:

  • Backwardly-compatible with the original;
  • Adds support for "Holder of Key" subject confirmation;
  • Adds support for channel bindings; and
  • Is defined more succinctly.

Direct vs. Delegated Authentication

The basic definition of the ECP profile is designed around the same set of "actors" as the Browser SSO profile:

  1. A subject controlling a client;
  2. An IdP that can authenticate the subject; and
  3. An SP that can accept an assertion from the IdP to establish a session with the subject.

Generally speaking ECP is a "single tier" profile for a user accessing a service.

A more advanced variant of the ECP work can be combined with some other profiles to solve a more complicated problem, that of multi-tier delegation. In the delegated case, the "client" accessing the web service is acting on behalf of an earlier client that authenticated to it with SAML.

With delegation, the web service can recognize both the original client/subject and the "delegate" that is accessing it on behalf of that subject, and control or limit access based on both identities.

Current AAF support

At this time the AAF is only supporting the basic, direct modes of working with ECP and is not supporting the more advanced uses of holder of key or channel bindings.

This may change in the future if there is sufficient need and would require further investigation.

Enabling ECP support in your Identity Provider

Technical Prerequisites

This section assumes you already have a tested, fully functioning Identity Provider with a minimum version number of 2.3.0 or greater as described in the Identity Provider install guide that has at a minimum been used successfully with the AAF Attribute Validator. The documentation here was developed on Shibboleth IdP version 2.4.2 and AAF support strongly recommends subscribers on older releases upgrade to the latest release of Shibboleth IdP in order to ensure they have all security patches and bug fixes.

If this is not the case please ensure you successfully complete an install or upgrade before continuing.

Internal IdP configuration

The basics of enabling the Shibboleth IdP to support ECP are reasonably straight forward. Ensure the following exists in the your IdP's configuration files (generally under /opt/shibboleth-idp/conf) and add them if not:

  • relying-party.xml: A definition of SAML2ECPProfile

        <rp:ProfileConfiguration xsi:type="saml:SAML2ECPProfile"
            signAssertions="always"
            includeAttributeStatement="true"/>
    
  • handler.xml: An ECP endpoint definition:

        <ph:ProfileHandler xsi:type="ph:SAML2ECP"
            inboundBinding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP"
            outboundBindingEnumeration="urn:oasis:names:tc:SAML:2.0:bindings:SOAP">
          <ph:RequestPath>/SAML2/SOAP/ECP</ph:RequestPath>
        </ph:ProfileHandler>
    

Authenticating ECP requests

This is where ECP gets somewhat complex. The authentication method that you're already using for web browser clients will not work for ECP.

There are many ways your IdP may choose to authenticate an ECP request but the most common is via basic authentication using the HTTP Authorize header. If you choose to not use basic authentication then applications wishing to use your IdP for ECP purposes may find it difficult to establish a session.

In order to not break your existing web browser clients be sure that your ECP basic auth configuration applies only to requests sent to /idp/profile/SAML2/SOAP/ECP. A successful authentication MUST set the REMOTE_USER value so that the Shibboleth IdP can establish a session.

How you undertake basic authentication is a decision that needs to be made by each Identity Provider and largely depends on what sort of backend you have available.

Using an Apache webserver

If you're using Apache HTTPD as your webserver the following example will probably suit your deployment in order to undertake the basic authentication process for ECP.

Protect the /idp/profile/SAML2/SOAP/ECP location on your IdP with authentication against your LDAP - add the following (customized for your LDAP server) into /etc/httpd/conf.d/idp.conf:
        <Location /idp/profile/SAML2/SOAP/ECP>
                AuthType Basic
                AuthName "Example Institution Shibboleth Identity Provider - ECP profile"
                AuthzLDAPAuthoritative Off
                AuthBasicProvider ldap
                AuthLDAPURL ldap://ldap.example.org/ou=People,dc=example,dc=org?uid
                AuthLDAPBindDN "cn=read,dc=example,dc=org"
                AuthLDAPBindPassword "password"
                Require valid-user
                # enable this only over SSL -  not needed when defined in the context of a https VirtualHost
                SSLRequireSSL
        </Location>
Notes:
  • The Apache LDAP module cannot handle LDAP referrals. When connecting to an Active Directory server (which typically includes referrals to other domains in the AD forest in the results), you will need to connect to the Global Catalog at port 3268.
  • In order for the ECP handler (running as part of the Identity Provider web application inside Tomcat) to receive the REMOTE_USER variable set by Apache, the AJP connector in Tomcat must have the tomcatAuthentication="false"

Alternative options

Verify configuration

Restart your Identity Provider. Ensure in logs that everything starts back up as expected and test to ensure that login to the AAF Attribute Validator still functions.

You should also be able to check that the authentication part of your basic authentication process is working by opening https://<idp-url>/idp/profile/SAML2/SOAP/ECP in your web browser. You should be presented with the standard basic authentication login prompt by your browser and on successful login be given a 404 response. Check your logs for details on how the entire process went on your server.

Registering the change in Federation Registry

Once you've completed the technical changes on your server you need to advertise ECP support from Federation Registry.

Navigate to Federation Registry (production | test) and open your Identity Provider management page, this should be linked from your dashboard view, then:

  • Select the SAML tab;
  • Select the second level Endpoints tab and the "Single Sign On Services" category;
  • Click on Add Endpoint;
  • Select Binding urn:oasis:names:tc:SAML:2.0:bindings:SOAP;
  • Enter Location https://<idp-url>/idp/profile/SAML2/SOAP/ECP (substituting your Identity Provider hostname); and
  • Click save

Give this change between 1 and 24 hours to distribute out through the AAF.

Comments