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

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': 'application/soap+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'})

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.