IMPORTANT NOTE: The JBoss Identity module used in this article has been superseded by the PicketLink Seam module. Please refer to these articles for information about the newest (and most feature-rich) PicketLink module for integrating your Seam application with an external SAML or OpenID based identity provider:

How to add SAML and OpenID authentication to your Seam application

External authentication example using OpenSSO

External authentication example using SSOCircle

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

JBoss Identity makes it simple to connect your JBoss Seam application to a SAMLv2 identity provider. This article describes the steps that you need to take to turn your Seam application into a Single Sign On participant.

Step 1: add a dependency to your pom file

Provided that you use Maven for building your Seam application, you should add a dependency to the pom.xml:

     <dependency>
         <groupId>org.picketlink</groupId>
         <artifactId>picketlink-seam</artifactId>
         <version>... choose a version ...</version>
     </dependency>

Step 2: activate the SAML authentication filter

The jar file that comes along with the dependency of step 1 contains a Seam servlet filter that will be responsible to sending authentication requests to your identity provider (IDP), and for validating and processing the authentication responses. The filter can be activated and configured by adding it to the components.xml file:

    <component
        name="org.picketlink.identity.seam.federation.samlAuthenticationFilter">
        <property name="serviceProviderEntityId">https://www.my-idp.com</property>
        <property name="singleSignOnServiceURL">https://www.my-idp.com/singleSignOnService</property>
        <property name="keyStoreURL">file:/etc/keystores/samlkeystore</property>
        <property name="keyStorePass">nobody_knows</property>
        <property name="idpCertificateAlias">saml</property>
        <property name="binding">HTTP_Post</property>
        <property name="signatureRequired">true</property>
    </component>

Let's explain the properties. The serviceProviderEntityId identifies the SP, and the singleSignOnServiceURL is the URL of the IDP to which the authentication request will be sent (using the HTTP_Post or HTTP_Redirect binding, depending on binding). The IDP shall send back an authentication response using the HTTP_Post binding. The HTTP_Artifact binding for responses is not supported yet. It is advisable to let the IDP sign its responses. If signatureRequired is true (which is the default), the signature of each response will be validated. The validation uses the public key of the IDP's certificate. The certificate  is read from the keystore at the location pointed to by keyStoreURL, using the  keyStorePass to get access. The idpCertificateAlias specifies the alias which identifies the certificate within the keystore.

Step 3: configure an authentication method

In the components.xml, you need to specify a method that is called upon successful authentication:

    <security:identity authenticate-method="#{authenticator.authenticate}" />

The method will be used mainly for adding roles to the Seam identity of the user that is about to be logged in. The roles can be extracted from the identity component:

   @Name("authenticator")
   public class Authenticator
   {

      @In
      private SamlIdentity identity;

      public boolean authenticate()
      {
         List<String> roles = identity.getAttributeValues("role");
         if (roles != null)
         {
            for (String role : roles)
            {
               identity.addRole(role);
            }
         }

         return true;

      }
   }

The identity component contains a map with attribute values that have been asserted by the IDP. Single valued attributes can be extracted by using the getAttributeValue method, and multivalued attributes can be retrieved with the getAttributeValues method. The name of the attribute that contains the roles is implementation dependent (look in the IDP configuration).

Step 4: add JBoss Identity jars to the lib folder of JBoss AS

In the runtime environment, you will need the JBoss Identity Federation jar file: jboss-identity-fed-<version>.jar. You should copy it to the lib folder of your JBoss application server

Step 5: configure permissions

In fact this step is just what you would do for any other authentication method: as soon as the identity of your user has been established by SAML, the user can only access the pages and components for which it has permission. You can use the regular Seam constructs for specifying the permission, for example

• <s:hasRole>, <s:hasPermission> in EL expressions on the xhtml pages
• <restrict> elements in  pages.xml

They will use the roles that are assigned with the method created in step 3.

Go...

You should be ready for running the Seam application now and logging in using the IDP. Probably it will work. If things are not working, it may be because there is no support for (partially) encrypted authentication responses yet.

You could also take a look at the sample applications that are part of the JBoss Identity Federation product to see a working Seam application that uses SAMLv2 based SSO.