Guide to using ECP

==================

Introduction

------------

The **Enhanced Client or Proxy** (ECP) profile of SAML2

The Enhanced Client or Proxy (ECP) Profile supports several SSO use

cases, in particular:

  * Clients with capabilities beyond those of a browser, allowing them

    to more actively participate in IdP discovery and message flow.

  * Using a proxy server, for example a WAP gateway in front of a mobile

    device which has limited functionality.

  * When other bindings are precluded (e.g. where the client does not

    support redirects, or when auto form post is not possible without

    Javascript, or when the artifact binding is ruled out because the

    identity provider and service provider cannot directly communicate.

An enhanced client or proxy (ECP) is a system entity that knows how to

contact an appropriate identity provider, possibly in a

context-dependent fashion, and also supports the Reverse SOAP (PAOS)

binding.

An example scenario enabled by ECP profile is as follows: A principal,

wielding an ECP, uses it to either access a resource at a service

provider, or access an identity provider such that the service

provider and desired resource are understood or implicit. The

principal authenticates (or has already authenticated) with the

identity provider [1]_, which then produces an authentication assertion

(possibly with input from the service provider). The service provider

then consumes the assertion and subsequently establishes a security

context for the principal. During this process, a name identifier

might also be established between the providers for the principal,

subject to the parameters of the interaction and the consent of the

principal.

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

transaction:

  1. ECP issues HTTP Request to SP

  2. SP issues <AuthnRequest> to ECP using PAOS

  3. ECP determines IdP

  4. ECP conveys <AuthnRequest> to IdP using SOAP

  5. IdP identifies principal

  6. IdP issues <Response> to ECP, targeted at SP using SOAP

  7. ECP conveys <Response> to SP using PAOS

  8. SP grants or denies access to principal

mod_auth_mellon and ECP

-----------------------

mod_auth_mellon plays the role of the SP in an ECP transaction.

mod_auth_mellon utilizes the Lasso library to provide it's SAML2

functionality. Fully functioning SAML2 ECP support in Lasso is

relatively new. When mod_auth_mellon is built it detects the presence

of SAML2 ECP in Lasso and only compiles in the ECP code in

mod_auth_mellon if it's present in Lasso.

How does mod_auth_mellon recognize a request is from an ECP client?

```````````````````````````````````````````````````````````````````

In Step 1. when the ECP client issues the HTTP Request to the SP it

**MUST** include `application/vnd.paos+xml` as a mime type in the HTTP

`Accept` header field and include an HTTP `PAOS` header specifying a

PAOS version of `urn:liberty:paos:2003-08` and an ECP service

declaration of `urn:oasis:names:tc:SAML:2.0:profiles:SSO:ecp` [2]_,

for example::

  Accept: text/html, application/vnd.paos+xml

  PAOS: ver="urn:liberty:paos:2003-08";"urn:oasis:names:tc:SAML:2.0:profiles:SSO:ecp"

If mod_auth_mellon sees this in the incoming request it knows the

client is ECP aware and capable. If authentication is required

mod_auth_mellon will initiate an ECP flow.

The role of IdP's in ECP

````````````````````````

The SAML2 ECP profile states it is the ECP client which determines the

IdP that will be used for authentication. This is in contrast to the

Web SSO flow where the SP determines the IdP. However, the ECP

protocol permits an SP to send the ECP client a list of IdP's it

trusts. It is optional if the SP sends an IDPList, if it does the ECP

client should select the IdP from the SP provided IDPList otherwise

the ECP client is free to select any IdP it wishes.

If the mellon configuration option `MellonECPSendIDPList` is true then

mod_auth_mellon will include an IDPList when it returns a PAOS

<AuthnRequest> to the ECP client.

To build the IDPList mod_auth_mellon scans it's list of loaded IdP's

selecting those which are ECP capable. To support ECP an IdP must

advertise the SingleSignOn service utilizing the SOAP binding.

ECP specific mod_auth_mellon configuration directives

`````````````````````````````````````````````````````

These configuration directives are specific to ECP:

MellonECPSendIDPList

  If `On` mod_auth_mellon will send an IdP list to the ECP client

  containing only those IdP's capable of ECP flow. The ECP client

  should select an IdP only from this list. If this option is `Off`

  no IdP list will be sent and the ECP client is free to select any

  IdP.

Example ECP client

``````````````````

To illustrate a simple ECP client based on Lasso we'll use the Lasso

Python binding (as opposed to pseudo code, Python is quite

readable). All error checking and another necessary ancillary code has

been eliminated in order to clearly illustrate only the ECP

operations.

.. code-block:: python

  import lasso

  import requests

  ecp = lasso.Ecp(server)

  session = requests.Session()

  MEDIA_TYPE_PAOS = 'application/vnd.paos+xml'

  PAOS_HEADER = 'ver="%s";"%s"' % (lasso.PAOS_HREF,lasso.ECP_HREF)

  # Step 1: Request protected resource, indicate ECP capable

  response = session.get(protected, headers={'Accept': MEDIA_TYPE_PAOS,

                                             'PAOS': PAOS_HEADER})

  # Process returned PAOS wrapped <AuthnRequest>

  ecp.processAuthnRequestMsg(response.text)

  # Post SOAP wrapped <AuthnRequest> to IdP, use Digest Auth to authenticate

  response = session.post(ecp.msgUrl,

                          data=ecp.msgBody,

                          auth=requests.auth.HTTPDigestAuth(user, password)

                          headers={'Content-Type': 'text/xml'})

  # Process returned SOAP wrapped <Assertion> from IdP

  ecp.processResponseMsg(response.text)

  # Post PASO wrapped <Assertion> to SP, response is protected resource

  response = session.post(ecp.msgUrl,

                          data=ecp.msgBody,

                          headers={'Content-Type': 'application/vnd.paos+xml'})

mod_auth_mellon internal ECP implementation notes

-------------------------------------------------

Notes on ECP vs. Web SSO flow

`````````````````````````````

Web SSO (Single Sign-On) flow is by far the most common and what

most people are familiar with when they think of SAML. The Web SSO

profile is designed so that browsers ignorant of SAML can perform

SAML authentication without modification. This is accomplished with

existing HTTP paradigms such as redirects, form posts, etc. which a

browser will process normally yielding the desired result.

ECP (Enhanced Client or Proxy) is a different SAML profile that

also accomplishes SSO (Single Sign-On). The distinction is an ECP

client is fully SAML aware and actively participates in the SAML

conversation.

Web SSO and ECP have very different flows, mod_auth_mellon must

support both flows. mod_auth_mellon is a SP (Service Provider).

IdP Selection Differences

`````````````````````````

With Web SSO the SP determines the IdP and redirects there.

With ECP the ECP client determines the IdP, the SP has no a prori

knowledge of the target IdP, although the SP may provide a

suggested list of IdP's when responding to the ECP client.

Since with ECP it is the ECP client which selects the IdP the set of

IdP's loaded into mod_auth_mellon are not relevant **except** if

`MellonECPSendIDPList` is enabled. In this case mod_auth_mellon will

filter the set of loaded IdP's and forward those IdP's supporting

SingleSignOn with the SOAP binding.

Apache request processing pipeline

``````````````````````````````````

Apache implements a request processing pipeline composed of

stages. An Apache extension module can participate in the pipeline

by asking to be called at specific stages (steps) by registering a

hook function for that stage. Final content returned to the HTTP

client in the HTTP response is generated in the "handler", one of

the final stages in the request processing pipeline.

One of the stages in the request pipeline is determining

authentication and authorization for protected resources. If a

resource is protected and the authentication and authorization

pipeline stages deny access or fail the request processing pipeline

is aborted early, a non-success HTTP response is returned, the

content handler is never reached.

With Web SSO if authentication needs to be performed a redirect will

be returned that redirects to a SAML endpoint (login) on our SP. This

in turn generates the SAML <AuthnRequest> with a redirect to the

IdP. All of this is very vanilla standard HTTP easily accommodated by

Apache's request processing pipeline which is designed to handle these

types of flows.

ECP requires special handling

`````````````````````````````

However ECP has a very different flow. When an ECP client sends a

request to the SP it includes a special HTTP headers indicating it is

ECP capable. If the SP determines the resource is protected and

authentication is needed and the client has signaled it is ECP capable

then the SP responds successfully (200) with a SAML <AuthnRequest>

wrapped in PAOS. *This is very different than conventional HTTP

request processing.* Here we have a case where there is a protected

resource that has **not** been authenticated yet the web server will

responds with an HTTP 200 success and content! One might normally

expect a HTTP 401 or redirect response for a protected resource when

there is no authenticated user. *This is clearly contrary to the

expectations of Apache's request processing pipeline.*

Reaching the Apache content handler

```````````````````````````````````

In order to be able to return a successful (HTTP 200) PAOS response

when doing the ECP we have to reach the part of Apache's request

processing pipeline that generates the response. In Apache terminology

this is called a (content) handler.

At an early stage we detect if authentication is required. For the

normal Web SSO profile we would redirect the client back to our login

endpoint which will be handled by our handler in a different

request. But for ECP the current request must proceed. We set a flag

on the request indicating ECP authentication is required. The pipeline

continues. When the pipeline reaches the authentication and

authorization stages we check the ECP flag on the request, if ECP

authentication is indicated we lie and tell the pipeline the user is

authenticated and authorized. We do this only so we can reach the

handler stage (otherwise because the request is for a protected

resource the pipeline would terminate with an error). Despite our

having forced authentication and authorization to be valid for the

protected resource the request processing pipeline *will not return the

protected resource* because we will subsequently intercept the request

in our handler before the pipeline reaches the point of returning the

protected resource.

At the handler stage

````````````````````

Once our handler is invoked it has 3 possible actions to perform:

  1. The request is for one of our SAML endpoints (e.g. login,

  logout, metadata, etc.) We dispatch to the handler for the specific

  action. We detect this case by matching the request URI to our SAML

  endpoints. We signal to the pipeline that our hook handled the request.

  2. The request is for a protected resource and needs ECP

  authentication performed. We detect this case by examining the ECP flag

  set on the request by an earlier hook function. The request URI is

  for the protected resource and has nothing to do with our SAML

  endpoints. We generate the PAOS <AuthnRequest> and respond with

  success (200) and signal to the pipeline that our hook handled the

  request. Note, we have not returned the protected resource, instead

  we've returned the PAOS request.

  3. The request has nothing to do with us, we decline to handle

  it. The pipeline proceeds to the next handler.

.. [1] The means by which a principal authenticates with an identity

       provider is outside of the scope of SAML. Typically an ECP

       client will utilize an HTTP authentication method when posting

       the <AuthnRequest> SOAP message to the IdP.

.. [2] Contrary to most HTTP headers the values in the PAOS header must

       be enclosed in double quotes. A semicolon is used to separate

       the values.