SAML2 Overview and authentication workflow

For GateIn Portal and SAML2 integration, we are using JBoss project Picketlink Federation, which provides solution for most important parts of SAML2 specification. Especially it supports SSO authentication with SAML2 HTTP Redirect Binding and SAML2 HTTP Post Binding and it supports SAML2 Single Logout feature.

SSO authentication is based on circle of trust between SP and IDP.

The authentication works as follows (flow with GateIn Portal as SAML2 SP):

1. User sends request to secured resource like http://localhost:8080/portal/dologin

2. GateIn Portal will check if user is already authenticated and if yes, grant access to resource. Otherwise continue with flow below.

3. There is special Tomcat valve, which needs to be configured for portal context. This Valve will create SAML Request, which is basically XML message. Example of message:

   <samlp:AuthnRequest AssertionConsumerServiceURL="http://localhost:8080/portal/dologin" ID="ID_101dcb5e-f432-4f45-87cb-47daff92edef" IssueInstant="2012-04-12T17:53:27.294+01:00" ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Version="2.0">
      <saml:Issuer>http://localhost:8080/portal/dologin</saml:Issuer>
      <samlp:NameIDPolicy AllowCreate="true" Format="urn:oasis:names:tc:SAML:2.0:nameid-format:transient"/>
   </samlp:AuthnRequest>
   

   Valve will encapsulate SAML request into HttpResponse and it redirects it to IDP. Picketlink Federation supports SAML Redirect Binding, which basically means that SAML XML Request message is Base64 encoded and URL encoded and it is appended as URL parameter to GET request, which will be send to IDP. PL Fed also supports SAML POST Binding where is message encoded into Base64 and sent in the body of POST request.

4. IDP parses XML with SAML request and it sends login screen back to client. Now client (user) needs to authenticate himself. SAML specification does not mandate how exactly should be authentication of client on IDP side performed.

5. User fills his credentials into IDP FORM and submits request for JAAS authentication. GateIn Portal SSO component provides login module SAML2IdpLoginModule, which will authenticate user by sending callback request via REST API back to GateIn Portal. This is similar approach like authentication with other SSO providers like CAS, which are also leveraging this REST service.

   Portal administrators are free to use their own login module stack instead of our REST callback based login module. However they need to make sure that authenticated users also need to exist in GateIn Portal database. Otherwise their users may have authorization errors with 403 response when they try to access portal.

6. So after successful authentication, IDP will create SAML assertion ticket and it creates SAML Response message with this ticket. Message can looks like this:

   <samlp:Response ID="ID_5291c49e-5450-4b3b-9f99-f76606db9929" Version="2.0" IssueInstant="2012-04-12T17:53:59.237+01:00" Destination="http://localhost:8080/portal/dologin" InResponseTo="ID_101dcb5e-f432-4f45-87cb-47daff92edef">
      <saml:Issuer>http://localhost:8080/idp/</saml:Issuer>
      <samlp:Status>
         <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/>
      </samlp:Status>
   
      <saml:Assertion ID="ID_ebe89398-1e27-4257-9413-c3c17c40c9df" Version="2.0" IssueInstant="2012-04-12T17:53:59.236+01:00">
         <saml:Issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent">root</saml:Issuer>
         <saml:Subject>
            <saml:NameID Format="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent">root</saml:NameID>
            <saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
               <saml:SubjectConfirmationData InResponseTo="ID_101dcb5e-f432-4f45-87cb-47daff92edef" NotBefore="2012-04-12T17:53:59.236+01:00" NotOnOrAfter="2012-04-12T17:54:06.236+01:00" Recipient="http://localhost:8080/portal/dologin"/>
            </saml:SubjectConfirmation>
         </saml:Subject>
         <saml:Conditions NotBefore="2012-04-12T17:53:57.236+01:00" NotOnOrAfter="2012-04-12T17:54:06.236+01:00"/>
         <saml:AuthnStatement AuthnInstant="2012-04-12T17:53:59.237+01:00">
            <saml:AuthnContext>
               <saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:Password</saml:AuthnContextClassRef>
            </saml:AuthnContext>
         </saml:AuthnStatement>
         <saml:AttributeStatement>
            <saml:Attribute Name="Role">
               <saml:AttributeValue xsi:type="xs:string">users</saml:AttributeValue>
            </saml:Attribute>
            <saml:Attribute Name="Role">
               <saml:AttributeValue xsi:type="xs:string">administrators</saml:AttributeValue>
            </saml:Attribute>
         </saml:AttributeStatement>
      </saml:Assertion>
   </samlp:Response>
   

7. Message is then encapsulated into HttpResponse and redirected back to SP (GateIn Portal).

8. On GateIn Portal side is SAML response message decoded again by the Tomcat Valve and if assertion from response is valid, then username and his roles are added into ThreadLocal context variable. Valve then triggers JAAS authentication. GateIn Portal component will provide login module SAML2IntegrationLoginModule, which will parse authenticated username and it will perform GateIn Portal specific operations, like creating Identity object and registering it into IdentityRegistry. Now user is successfully authenticated.

9. User is redirected back to the secure resource http://localhost:8080/portal/dologin, which in next turn will redirect him to GateIn Portal as authenticated user. If the user wants to authenticate against different SP application within same browser session (GateIn Portal on different host or completely different web application), then he does not need to provide credentials again on IDP side because he has been already authenticated against IDP. So he has automatic authentication thanks to SSO.

In next sections, we will go through various scenarios, which describes how you can leverage SAML2 in GateIn Portal and there is description of all needed configuration changes.

Portal as SAML2 SP and SAML2 IDP

In this scenario we will use GateIn Portal as SAML2 SP and another instance of GateIn Portal as SAML2 IDP. SP will be executed on virtual host www.sp.com and IDP will be on virtual host www.idp.com . Both GateIn Portal instances will be on JBoss AS7. The idea is that users, who want to authenticate against GateIn Portal on www.sp.com will be redirected to www.idp.com where they need to authenticate and after successful authentication on IDP the SAMLResponse will be send back to www.sp.com and user will be redirected back.

gatein.sso.filter.logout.enabled=false

Setup with external IDP using REST callback

In previous section, you saw how to configure GateIn Portal to act as SAML2 SP or as SAML2 IDP. Note that you can use GateIn Portal IDP with any other SP web applications. And on the opposite site, you can configure your GateIn Portal SP to authenticate against some external IDP application. You can consult documentation of Picketlink Federation for more details about setup.

But in addition we provide modified version of idp-sig quickstart application from Picketlink Federation. Our modified version is again using REST callback to authenticate against existing GateIn Portal instance. So it's similar like for other SSO scenarios and details are in Central Authentication Service (CAS)#Login workflow . In this case, we need to configure special login module SAML2IdpLoginModule, which is able to connect to GateIn Portal via REST and verify against portal database if provided credentials are valid.

So we assume that you have instance of JBoss AS7 where we deploy our idp-sig.war application. This server will run again on www.idp.com. GateIn Portal will be configured as SP on www.sp.com and it will use this IDP from www.idp.com to authenticate.

1. GateIn Portal SP setup - You need to configure properties in SSO section of file GATEIN_SP_HOME/standalone/configuration/gatein/configuration.properties like this:

   gatein.sso.enabled=true
   gatein.sso.callback.enabled=${gatein.sso.enabled}
   gatein.sso.login.module.enabled=${gatein.sso.enabled}
   gatein.sso.login.module.class=org.gatein.sso.agent.login.SAML2IntegrationLoginModule
   gatein.sso.filter.login.sso.url=/@@portal.container.name@@/dologin
   gatein.sso.filter.logout.enabled=true
   gatein.sso.filter.logout.class=org.gatein.sso.agent.filter.SAML2LogoutFilter
   gatein.sso.filter.initiatelogin.enabled=false
   gatein.sso.valve.enabled=true
   gatein.sso.valve.class=org.picketlink.identity.federation.bindings.tomcat.sp.ServiceProviderAuthenticator
   gatein.sso.saml.config.file=/WEB-INF/conf/sso/saml/picketlink-sp.xml
   gatein.sso.idp.host=www.idp.com
   gatein.sso.idp.url=http://${gatein.sso.idp.host}:8080/idp-sig/
   gatein.sso.sp.url=http://www.sp.com:8080/portal/dologin
   # WARNING: This bundled keystore is only for testing purposes. You should generate and use your own keystore!
   gatein.sso.picketlink.keystore=/sso/saml/jbid_test_keystore.jks

   There are some differences from previous setup. Now gatein.sso.callback.enabled is true because idp-sig.war application need to handle REST callback requests from idp-sig application. Also gatein.sso.idp.url is changed as idp will run on URI /idp-sig/ .

2. Start SP with:

   cd GATEIN_SP_HOME/bin
   ./standalone.sh -b www.sp.com

3. IDP setup:

   1. Take another instance of GateIn Portal , which will be used for IDP setup. The directory with this instance will be referred as AS7_IDP_HOME.

      We won't use GateIn Portal itself for IDP setup, but we will use independent web application idp-sig . So theoretically you can use plain AS7 without GateIn Portal deployed. But note that AS7 instance with GateIn Portal contains some additional modules, which are needed for our idp-sig.war application. So it's still recommended to use GateIn Portal instead of plain AS7.

   2. Copy GATEIN_SSO_HOME/saml/idp-sig.war into AS7_IDP_HOME/standalone/deployments . GATEIN_SSO_HOME points to directory with SSO packaging. See Single-Sign-On (SSO) for more details.

   3. Create empty file AS7_IDP_HOME/standalone/deployments/idp-sig.war.dodeploy (It's needed because idp-sig.war is exploded archive right now)

   4. New IDP security domain needs to be added to AS7_IDP_HOME/standalone/configuration/standalone.xml

      <security-domain name="idp" cache-type="default">
         <authentication>
            <login-module code="org.gatein.sso.saml.plugin.SAML2IdpLoginModule" flag="required">
               <module-option name="rolesProcessing" value="STATIC"/>
               <module-option name="staticRolesList" value="manager,employee,sales"/>
               <module-option name="gateInURL" value="http://www.sp.com:8080/portal"/>
               <module-option name="httpMethod" value="POST"/>
            </login-module>
         </authentication>
      </security-domain>

      Note especially option gateInURL, which contains base URL for sending authentication callback to GateIn Portal, so this needs to point to URL where your portal is running.

   5. Run IDP with:

      cd AS7_IDP_HOME/bin
      ./standalone.sh -b www.idp.com -Dsp.host=www.sp.com -Dsp.domains=sp.com -Dpicketlink.keystore=/jbid_test_keystore.jks

      All these properties are used in picketlink configuration file of idp-sig.war application in AS7_IDP_HOME/standalone/deployments/idp-sig.war/WEB-INF/picketlink.xml

4. Test - you can go to http://www.sp.com:8080/portal and click Sign in. You will be redirected to idp-sig application on http://www.idp.com:8080/idp-sig/. Now you can login with GateIn Portal credentials like "john"/"gtn" because REST callback will be sent to portal on www.sp.com and it will take care of user authentication. After authentication you will be redirected to portal on www.sp.com and logged as john.

Integration with Salesforce and Google Apps

GateIn Portal SSO component contains the support for Salesforce and Google Apps integration for SAML2 based SSO. Supported scenarios are:

• GateIn Portal as SAML Identity Provider, Salesforce as SAML Service Provider

• GateIn Portal as Identity Provider, Google Apps as SAML Service Provider

• GateIn Portal as SAML Service Provider, Salesforce as SAML Identity Provider

In next sections, you can see detailed description of all scenarios with needed configuration changes.

Tips & Tricks

• Videos - You can follow some videos on GateIn Portal vimeo channel, where you can see SAML2 integration in action. The videos are:

  1. http://vimeo.com/45841256 - Video with basic usecases showing GateIn Portal as SAML2 SP and as SAML2 IDP.

  2. http://vimeo.com/45895919 - Video showing integration with Salesforce and Google Apps

• SAML tracer is cool plugin to Firefox browser, which allows you to monitor HTTP requests and see wrapped SAML messages in XML format. It could be useful especially for troubleshooting. You can download plugin here

• Logging - Like for other SSO solutions, it may be good to enable trace logging for org.gatein.sso etc but in case of SAML, it's good also to enable logging for org.picketlink.identity.federation, which is base package for picketlink federation library. You can add these categories to GATEIN_HOME/standalone/configuration/standalone.xml :

  <logger category="org.gatein.sso">
    <level name="TRACE"/>
  </logger>
  <logger category="org.picketlink.identity.federation">
    <level name="TRACE"/>
  </logger>
  <logger category="org.jboss.security">
    <level name="TRACE"/>
  </logger>
  <logger category="org.picketbox">
    <level name="TRACE"/>
  </logger>
  <logger category="org.exoplatform.services.security">
    <level name="TRACE"/>
  </logger>