PicketLink SAML SSO for Web Containers

In this article, we look at the settings to run PicketLink Federation component to achieve SAML based Single Sign On (SSO) for a generic web container. We do recommend PicketLink bindings for JBoss Application Server or Apache Tomcat, if you are able to.

 

The User Guide provides the settings for JBoss Application Server and Apache Tomcat.

 

But if your web container is not these two, you can still use PicketLink and read on.


Identity Provider

 

Since you have a JavaEE Web Container, you will need the IDP war. The war file should contain a picketlink-handlers.xml in the WEB-INF folder of your war file.

 

The picketlink-handlers.xml should look as follows:

<Handlers xmlns="urn:picketlink:identity-federation:handler:config:1.0">
  <Handler class="org.picketlink.identity.federation.web.handlers.saml2.SAML2IssuerTrustHandler"/>
  <Handler class="org.picketlink.identity.federation.web.handlers.saml2.SAML2LogOutHandler"/>
  <Handler class="org.picketlink.identity.federation.web.handlers.saml2.SAML2AuthenticationHandler"/>
</Handlers>

 

The above file declares the various handlers.

 

Now, you will need a file called as picketlink-idfed.xml that declares the configuration settings for the IDP.

<PicketLinkIDP xmlns="urn:picketlink:identity-federation:config:1.0" >
<IdentityURL>http://localhost:8080/idp-standalone/</IdentityURL>
<Trust>
   <Domains>localhost,jboss.com,jboss.org</Domains>
</Trust>
<KeyProvider ClassName="org.picketlink.identity.federation.core.impl.KeyStoreKeyManager">
  <Auth Key="KeyStoreURL" Value="jbid_test_keystore.jks" />
  <Auth Key="KeyStorePass" Value="store123" />
  <Auth Key="SigningKeyPass" Value="test123" />
  <Auth Key="SigningKeyAlias" Value="servercert" />
  <ValidatingAlias Key="localhost" Value="servercert"/>
  <ValidatingAlias Key="127.0.0.1" Value="servercert"/>
</KeyProvider>

</PicketLinkIDP>

 

In this configuration file, we have the following settings:

  • IdentityURL:  This is the URL of the IDP
  • Trust: This element lists all the domains the IDP trusts. You need to use the Domains element.
  • KeyProvider:  This element declares the Trust based on certificates. Note that we declare the validating certificate for each domain using the ValidatingAlias.

 

The web.xml should look as follows:

<?xml version="1.0" encoding="ISO-8859-1"?>
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
   version="2.5"> 

  <display-name>Standalone IDP</display-name>
  <description>
    IDP Standalone Application
  </description>

  <!-- Listeners -->
  <listener>
    <listener-class>org.picketlink.identity.federation.web.core.IdentityServer</listener-class>
  </listener>


  <!-- Create the servlet -->
  <servlet>
    <servlet-name>IDPLoginServlet</servlet-name>
    <servlet-class>org.picketlink.identity.federation.web.servlets.IDPLoginServlet</servlet-class>
  </servlet>
  <servlet>
    <servlet-name>IDPServlet</servlet-name>
    <servlet-class>org.picketlink.identity.federation.web.servlets.IDPServlet</servlet-class>
  </servlet>

  <servlet-mapping>
    <servlet-name>IDPLoginServlet</servlet-name>
    <url-pattern>/</url-pattern>
  </servlet-mapping>

  <servlet-mapping>
    <servlet-name>IDPServlet</servlet-name>
    <url-pattern>/IDPServlet</url-pattern>
  </servlet-mapping>

</web-app>

 

It is very important to follow the order. The URL mapping for the IDP should always point to IDPLoginServlet. The IDPLoginServlet then forwards to the IDPServlet.

 

We use the authentication via users.properties and roles.properties shipped under classes directory of WEB-INF directory.

 

users.properties

manager=tomcat

 

roles.properties

manager=manager,sales,employee

 

Service Provider

 

Each web application that acts as a service provider needs to use a central IDP for its authentication needs.

 

Step 1: Use a picketlink-handlers.xml in your WEB-INF of your war file.

<Handlers xmlns="urn:picketlink:identity-federation:handler:config:1.0"> 
  <Handler class="org.picketlink.identity.federation.web.handlers.saml2.SAML2IssuerTrustHandler"/>
  <Handler class="org.picketlink.identity.federation.web.handlers.saml2.SAML2LogOutHandler"/> 
  <Handler class="org.picketlink.identity.federation.web.handlers.saml2.SAML2AuthenticationHandler"/>   
</Handlers>

 

Step 2: Use a picketlink-idfed.xml in your WEB-INF of your war file. This file declares the configuration for your service provider.

<PicketLinkSP xmlns="urn:picketlink:identity-federation:config:1.0" ServerEnvironment="tomcat">
 <IdentityURL>http://localhost:8080/idp-standalone/</IdentityURL>
 <ServiceURL>http://localhost:8080/sales-standalone/</ServiceURL>
 <Trust>
    <Domains>localhost,jboss.com,jboss.org,redhat.com</Domains>
 </Trust>
 <KeyProvider ClassName="org.picketlink.identity.federation.core.impl.KeyStoreKeyManager">
    <Auth Key="KeyStoreURL" Value="jbid_test_keystore.jks" />
    <Auth Key="KeyStorePass" Value="store123" />
    <Auth Key="SigningKeyPass" Value="test123" />
    <Auth Key="SigningKeyAlias" Value="servercert" />
    <ValidatingAlias Key="localhost" Value="servercert"/>
    <ValidatingAlias Key="127.0.0.1" Value="servercert"/>
 </KeyProvider>

</PicketLinkSP>

 

In this configuration file, we have the following settings:

  • IdentityURL:  This is the URL of the IDP
  • ServiceURL: This is the URL of the Service Provider.
  • Trust: This element lists all the domains the SP trusts. You need to use the Domains element.
  • KeyProvider:  This element declares the Trust based on certificates. Note that we declare the validating certificate for each domain using the ValidatingAlias.

 

 

Your web.xml should define the SPFilter setting.

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
   version="2.5">

   <description>Sales Standalone Application</description>

   <filter>
     <description>
        The SP Filter intersects all requests at the SP and sees if there is a need to contact the IDP.
     </description>
     <filter-name>SPFilter</filter-name>
     <filter-class>org.picketlink.identity.federation.web.filters.SPFilter</filter-class>
     <init-param>
       <param-name>ROLES</param-name>
       <param-value>sales,manager</param-value>
     </init-param>
   </filter>

   <filter-mapping>
     <filter-name>SPFilter</filter-name>
     <url-pattern>/*</url-pattern>
     <dispatcher>REQUEST</dispatcher>
   </filter-mapping>
</web-app>

 

The setting for SPFilter is very important as it handles the security of the web application.

 

The index.jsp of this service provider was as follows:

<div align="center">
<h1>SalesTool</h1>
<br/>
Welcome to the Sales Tool

<br/>
Here is your sales chart:
<br/>
<img src="piechart.gif"/>

<br/>
<a href="?GLO=true">Click to LogOut</a>
</div>

 

You can see that the LogOut link has the query parameter "GLO=true".

 

Note

  1. If your web container is JBoss Application Server or Apache Tomcat, then follow the User Guide.
  2. The above article handles SAML Global Logout also.
  3. You can download idp-standalone.war and sales-standalone.war from Downloads section.