ECP Plugin Overview

From OpenLiberty.org Wiki

Simplified version

The ECP plugin for Firefox (technically it's an extension), forms the basis for compliance with the SAML v2.0 ECP profile.

Basically, it acts as an intermediary between a Service Provider and a Identity Provider, to facilitate WebSSO without direct interaction between the two. This is done (initially) by declaring a content handler for the 'application/vnd.paos+xml' mime type and subsequently, by advertising the ability to handle the mime type by augmenting all outgoing requests with the proper 'Accept' & 'PAOS' headers.

When the Service Provider receives the request, (if it is ECP-compliant), it will return an AuthnRequest, meant for the Identity Provider. The Identity Provider then returns a AuthnResponse (if successful) containing a SAML assertion(s) to return back to the Service Provider, granting access to the User.

The ECP profile also provides for the possibility that the IdP MAY respond to the AuthnRequest with an HTML response. The ECP will in this case cache the AuthnRequest, render the HTML response to the browser window and give up on the UI blocking scheme. It is up to the IdP to redirect the browser (via any means at its disposal POST, 302, etc.), so that the ECP will have a chance to intercept the AuthnResponse at some later time.

Obviously this is the simple version. There are many variants to this process, including some that are completely outside the scope of the ECP profile, but which the ECP profile needs to deal with.

As much as possible, I have tried to block the UI, using synchronous XMLHttpRequests in the background, so that no redirects are visible. Also, the intention is to fail over to the 'normal' Browser Profile, if anything doesn't work as expected.

Detailed walkthrough

To be fair, we should start with the diagram from the docs [SAML PROFILES]:

I like to think of the steps slightly differently than the published diagram ... explicitly including the User/UserAgent in the steps, not just the ECP onward ...

1. User clicks on a link to a Service Provider
2. Mozilla ObserverService notifies the ECP plugin that a request is being sent out
3. ECP plugin appends special ECP-specific headers

 Accept:'application/vnd.paos+xml'
 PAOS: ver='urn:liberty:paos:2003-08'; 'urn:oasis:names:tc:SAML:2.0:profiles:SSO:ecp'

4. ECP-compliant Service Provider responds with a SOAP document, which includes an AuthnRequest element

 Content-Type: application/vnd.paos+xml
 SOAPAction: ""
 ...
 <?xml version="1.0" encoding="UTF-8"?>                // NOTE: I think this is optional because issues arise in some SOAP implementations??
 <SOAP-ENV:Envelope 
   xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
   xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" 
   xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
   xmlns:ecp="urn:oasis:names:tc:SAML:2.0:profiles:SSO:ecp">"
   <SOAP-ENV:Header>" 
   	<paos:Request xmlns:paos="urn:liberty:paos:2003-08" responseConsumerURL="http://service.provider.com/link" 
     	   messageID="OPTIONAL_SP_GENERATED_UNIQUE_MESSAGE_ID" 
     	   SOAP-ENV:actor="http://schemas.xmlsoap.org/soap/actor/next" 
     	   SOAP-ENV:mustUnderstand="1" 
   	   service="urn:oasis:names:tc:SAML:2.0:profiles:SSO:ecp">
       </paos:Request>
   	<ecp:Request xmlns:ecp="urn:oasis:names:tc:SAML:2.0:profiles:SSO:ecp" 
   	   SOAP-ENV:mustUnderstand="1" 
   	   SOAP-ENV:actor="http://schemas.xmlsoap.org/soap/actor/next" 
   	   ProviderName="WebObjects Reference Liberty-Enabled Service Provider" IsPassive="0">     // NOTE: can IsPassive be "true" or "false" too?
   	   <saml:Issuer>http://service.provider.com/unique_sp_id</saml:Issuer> 
   	   <samlp:IDPList>"
   	      <samlp:IDPEntry ProviderID="http://identity.provider.com/unique_idp_id"              // NOTE: I have seen <IDPEntryLoc> ... valid??
   		  Name="Identity Provider Human Readable Name" 
   		  Loc="http://http://identity.provider.com/ecp_sso_url">
   	      </samlp:IDPEntry>
   	      <samlp:GetComplete>                                                                  // NOTE: Anyone know what the format of returned content is?
   	         http://service.provider.com/all_supported_idps
   	      </samlp:GetComplete>
   	   </samlp:IDPList>
   	</ecp:Request>
   	<ecp:RelayState SOAP-ENV:mustUnderstand="1" SOAP-ENV:actor="http://schemas.xmlsoap.org/soap/actor/next">
   		CONTEXT_DEPENDENT_STATE_INFO_GOES_HERE 
   	</ecp:RelayState>
    </SOAP-ENV:Header>
    <SOAP-ENV:Body> 
       <samlp:AuthnRequest ID="REQUIRED">SAML_ASSERTION_STUFF</samlp:AuthnRequest>       // NOTE: Is the ID here the same as the messageID above??
    </SOAP-ENV:Body> 
 </SOAP-ENV:Envelope>