Seam Security

Authentication is the act of establishing, or confirming, the identity of a user. In many applications a user confirms their identity by providing a username and password (also known as their credentials). Seam Security allows the developer to control how users are authenticated, by providing a flexible Authentication API that can be easily configured to allow authentication against any number of sources, including but not limited to databases, LDAP directory servers or some other external authentication service.

If none of the built-in authentication providers are suitable for your application, then it is also possible to write your own custom Authenticator implementation.

Identity Management is a set of useful APIs for managing the users, groups and roles within your application. The identity management features in Seam are provided by PicketLink IDM, and allow you to manage users stored in a variety of backend security stores, such as in a database or LDAP directory.

Seam Security contains an external authentication sub-module that provides a number of features for authenticating your application users against external authentication services, such as OpenID and SAML.

While authentication is used to confirm the identity of the user, authorization is used to control which actions a user may perform within your application. Authorization can be roughly divided into two categories; coarse-grained and fine-grained. An example of a coarse-grained restriction is allowing only members of a certain group or role to perform a privileged operation. A fine-grained restriction on the other hand may allow only a certain individual user to perform a specific action on a specific object within your application.

There are also rule-based permissions, which bridge the gap between fine-grained and coarse-grained restrictions. These permissions may be used to determine a user's privileges based on certain business logic.

The Maven artifacts for all Seam modules are hosted within the JBoss Maven repository. Please refer to the Maven Getting Started Guide for information about configuring your Maven installation to use the JBoss repository.

To use Seam Security within your Maven-based project, it is advised that you import the Seam BOM (Bill of Materials) which declares the versions for all Seam modules. First declare a property value for ${seam.version} as follows:

<properties>

  <seam.version>3.1.0.Final</seam.version>

</properties>

You can check the JBoss Maven Repository directly to determine the latest version of the Seam BOM to use.

Now add the following lines to the list of dependencies within the dependencyManagement section of your project's pom.xml file:

<dependency>

  <groupId>org.jboss.seam</groupId>

  <artifactId>seam-bom</artifactId>

  <version>${seam.version}</version>

  <type>pom</type>

  <scope>import</scope>

</dependency>

Once that is done, add the following dependency (no version is required as it comes from seam-bom):

<dependency>

  <groupId>org.jboss.seam.security</groupId>

  <artifactId>seam-security</artifactId>

</dependency>

If you wish to use the external authentication module in your application to allow authentication using OpenID or SAML, then add the following dependency also:

<dependency>

  <groupId>org.jboss.seam.security</groupId>

  <artifactId>seam-security-external</artifactId>

</dependency>

To enable many of the features of Seam Security, the Security interceptor must be configured in your application's beans.xml file. Add the following configuration to your beans.xml to enable the Security Interceptor:

    <interceptors>
        <class>org.jboss.seam.security.SecurityInterceptor</class>
    </interceptors>

This is the common base interface for both User and Group. The getKey() method should return a unique identifying value for the identity type.

Represents a user. The getId() method should return a unique value for each user.

Represents a group. The getName() method should return the name of the group, while the getGroupType() method should return the group type.

Represents a role, which is a direct one-to-one typed relationship between a User and a Group. The getRoleType() method should return the role type. The getUser() method should return the User for which the role is assigned, and the getGroup() method should return the Group that the user is associated with.

Represents a role type. The getName() method should return the name of the role type. Some examples of role types might be admin, superuser, manager, etc.

A typesafe security binding is an annotation, meta-annotated with the SecurityBindingType annotation:

import org.jboss.seam.security.annotations.SecurityBindingType;

@SecurityBindingType
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.TYPE, ElementType.METHOD})
public @interface Admin { }

The security binding annotation may also define member values, which are taken into account when matching the annotated bean class or method with an authorizer method. All member values are taken into consideration, except for those annotated with @Nonbinding, in much the same way as a qualifier binding type.

import javax.enterprise.util.Nonbinding;
import org.jboss.seam.security.annotations.SecurityBindingType;

@SecurityBindingType
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.TYPE, ElementType.METHOD})
public @interface Foo {
   String bar();
   @Nonbinding String other() default "";
}

The next step after creating the security binding type is to create a matching authorizer method. This method must contain the business logic required to perform the required authorization check, and return a boolean value indicating whether the authorization check passed or failed.

An authorizer method must be annotated with the @Secures annotation, and the security binding types for which it is performing the authorization check. An authorizer method may declare zero or more method parameters. Any parameters defined by the authorizer method are treated as injection points, and are automatically injected by the Seam Security extension. The following example demonstrates an authorizer method that injects the Identity bean, which is then used to perform the authorization check.

import org.jboss.seam.security.annotations.Secures;

public class Restrictions {      
  public @Secures @Admin boolean isAdmin(Identity identity) {
    return identity.hasRole("admin", "USERS", "GROUP");
  }
}

Once the security binding annotation and the matching authorizer method have been created, the security binding type may be applied to a bean class or method. If applied at the class level, every method of the bean class will have the security restriction applied. Methods annotated with a security binding type also inherit any security bindings on their declaring class. Both bean classes and methods may be annotated with multiple security bindings.

public @ConversationScoped class UserAction {
  public @Admin void deleteUser(String userId) {
    // code
  }
}

If a security check fails when invoking a method annotated with a security binding type, an AuthorizationException is thrown. Solder can be used to handle this exception gracefully, for example by redirecting them to an error page or displaying an error message. Here's an example of an exception handler that creates a JSF error message:

@HandlesExceptions
public class ExceptionHandler {
   @Inject FacesContext facesContext;
   public void handleAuthorizationException(@Handles CaughtException<AuthorizationException> evt) {
      facesContext.addMessage(null, new FacesMessage(FacesMessage.SEVERITY_ERROR,
            "You do not have the necessary permissions to perform that operation", ""));
      evt.handled();      
   }
}

Seam Security provides one security binding annotation out of the box, @LoggedIn. This annotation may be applied to a bean to restrict its methods to only those users that are currently authenticated.

import org.jboss.seam.security.annotations.LoggedIn;
      
public @LoggedIn class CustomerAction {
  public void createCustomer() {
    // code 
  }
}

While JpaIdentityStore should be compatible with a large variety of database schemas, the following diagram displays the recommended database schema to use:

Seam Security provides two annotations for configuring your entity beans for use with JpaIdentityStore. The first, @IdentityEntity is a class annotation used to mark an entity bean so that JpaIdentityStore knows it contains identity-related data. It has a single member of type EntityType, that tells JpaIdentityStore what type of identity data it contains. Possible values are:

The second one, IdentityProperty, is a field or method annotation which is used to configure which properties of the bean contain identity values. This annotation declares two values, value and attributeName:

Let's start by looking at identity object. In the recommended database schema, the IDENTITY_OBJECT table is responsible for storing objects such as users and groups. This table may be represented by the following entity bean:

@Entity

@IdentityEntity(IDENTITY_OBJECT)

public class IdentityObject implements Serializable {  

    @Id @GeneratedValue private Long id;

     

    @IdentityProperty(PropertyType.NAME)

    private String name;

     

    @ManyToOne @IdentityProperty(PropertyType.TYPE)

    @JoinColumn(name = "IDENTITY_OBJECT_TYPE_ID")

    private IdentityObjectType type;


    // snip getter and setter methods

}

In the above code both the name and type fields are annotated with @IdentityProperty. This tells JpaIdentityStore that these two fields are significant in terms of identity management-related state. By annotating the name field with @IdentityProperty(PropertyType.NAME), JpaIdentityStore knows that this field is used to store the name of the identity object. Likewise, the @IdentityProperty(PropertyType.TYPE) annotation on the type field indicates that the value of this field is used to represent the type of identity object.

The IdentityObjectType entity is simply a lookup table containing the names of the valid identity types. The field representing the actual name of the type itself should be annotated with @IdentityProperty(PropertyType.NAME):

@Entity

public class IdentityObjectType implements Serializable {   


   @Id @GeneratedValue private Long id;

   @IdentityProperty(PropertyType.NAME) private String name;        

   

   // snip getter and setter methods

}

The credentials table is used to store user credentials, such as passwords. Here's an example of an entity bean configured to store identity object credentials:

@Entity

@IdentityEntity(IDENTITY_CREDENTIAL)      

public class IdentityObjectCredential implements Serializable {   

   @Id @GeneratedValue private Long id;

   

   @ManyToOne @JoinColumn(name = "IDENTITY_OBJECT_ID")

   private IdentityObject identityObject;

   

   @ManyToOne @IdentityProperty(PropertyType.TYPE)

   @JoinColumn(name = "CREDENTIAL_TYPE_ID")

   private IdentityObjectCredentialType type;

   

   @IdentityProperty(PropertyType.VALUE)

   private String value;        

   

   // snip getter and setter methods

}

The IdentityObjectCredentialType entity is used to store a list of valid credential types. Like IdentityObjectType, it is a simple lookup table with the field representing the credential type name annotated with @IdentityProperty(PropertyType.NAME):

@Entity

public class IdentityObjectCredentialType implements Serializable

{  

   @Id @GeneratedValue private Long id;

   

   @IdentityProperty(PropertyType.NAME)

   private String name;        

   

   // snip getter and setter methods

}

The relationship table stores associations between identity objects. Here's an example of an entity bean that has been configured to store identity object relationships:

@Entity

@IdentityEntity(IDENTITY_RELATIONSHIP)

public class IdentityObjectRelationship implements Serializable

{   

   @Id @GeneratedValue private Long id;

   

   @IdentityProperty(PropertyType.NAME)

   private String name;

   

   @ManyToOne @IdentityProperty(PropertyType.TYPE) @JoinColumn(name = "RELATIONSHIP_TYPE_ID")

   private IdentityObjectRelationshipType relationshipType;

   

   @ManyToOne @IdentityProperty(PropertyType.RELATIONSHIP_FROM) @JoinColumn(name = "FROM_IDENTITY_ID")

   private IdentityObject from;

   

   @ManyToOne @IdentityProperty(PropertyType.RELATIONSHIP_TO) @JoinColumn(name = "TO_IDENTITY_ID")

   private IdentityObject to;        

   

   // snip getter and setter methods

}

The name property is annotated with @IdentityProperty(PropertyType.NAME) to indicate that this field contains the name value for named relationships. An example of a named relationship is a role, which uses the name property to store the role type name.

The relationshipType property is annotated with @IdentityProperty(PropertyType.TYPE) to indicate that this field represents the type of relationship. This is typically a value in a lookup table.

The from property is annotated with @IdentityProperty(PropertyType.RELATIONSHIP_FROM) to indicate that this field represents the IdentityObject on the from side of the relationship.

The to property is annotated with @IdentityProperty(PropertyType.RELATIONSHIP_TO) to indicate that this field represents the IdentityObject on the to side of the relationship.

The IdentityObjectRelationshipType entity is a lookup table containing the valid relationship types. The @IdentityProperty(PropertyType.NAME) annotation is used to indicate the field containing the relationship type names:

@Entity

public class IdentityObjectRelationshipType implements Serializable {   

   @Id @GeneratedValue private Long id;

   

   @IdentityProperty(PropertyType.NAME)

   private String name;

   

   // snip getter and setter methods

}

The attribute table is used to store any additional information that is to be associated with identity objects. Here's an example of an entity bean used to store attributes:

@Entity

@IdentityEntity(IDENTITY_ATTRIBUTE)

public class IdentityObjectAttribute implements Serializable {

   

   @Id @GeneratedValue private Integer attributeId;

   

   @ManyToOne 

   @JoinColumn(name = "IDENTITY_OBJECT_ID")

   private IdentityObject identityObject;

   

   @IdentityProperty(PropertyType.NAME)

   private String name;

   

   @IdentityProperty(PropertyType.VALUE)

   private String value;

   

   // snip getter and setter methods

}

The name field is annotated with @IdentityProperty(PropertyType.NAME) to indicate that this field contains the attribute name. The value field is annotated with @IdentityProperty(PropertyType.VALUE) to indicate that this field contains the attribute value.

Users and groups are managed by a PersistenceManager, which can be obtained by calling getPersistenceManager() on the IdentitySession object:

PersistenceManager pm = identitySession.getPersistenceManager();

Once you have the PersistenceManager object, you can create User objects with the createUser() method:

User user = pm.createUser("john");

Similarly, you can create Group objects with the createGroup() method:

Group headOffice = pm.createGroup("Head Office", "OFFICE");

You can also remove users and groups by calling the removeUser() or removeGroup() method.

Relationships are used to associate User objects with Group objects. Relationships can be managed with the RelationshipManager object, which can be obtained by calling getRelationshipManager() on the IdentitySession:

RelationshipManager rm = identitySession.getRelationshipManager();

Relationships are created by invoking the associateUser() method, and passing in the group and user objects that should be associated:

rm.associateUser(headOffice, user);

Roles are managed via the RoleManager object, which can be obtained by invoke the getRoleManager() method on the IdentitySession object:

RoleManager roleManager = identitySession.getRoleManager();

Roles are an association between a user and a group, however they are slightly more complex than a simple group membership as the association also has a role type. The role type is generally used to describe a particular function of the user within the group. Role types are represented by the RoleType object, and can be created with the createRoleType() method:

RoleType manager = roleManager.createRoleType("manager");

Roles can be assigned to users by invoking the createRole() method, and passing in the RoleType, User and Group:

Role r = roleManager.createRole(manager, user, headOffice);

If your project is Maven-based, then add the following dependency to your project:

<dependency>
  <groupId>org.jboss.seam.security</groupId>
  <artifactId>seam-security-external</artifactId>
</dependency>

If you are not using Maven, you must add the seam-security-external.jar library to your project, which can be found in the Seam Security downloadable distribution.

The external authentication module provides support for OpenID based on OpenID4Java, an open source OpenID library (licensed under the Apache v2 license) with both Relying Party and Identity Provider capabilities. This feature allows your application to authenticate its users against an external OpenID provider, such as Google or Yahoo, or to turn your application into an OpenID provider itself.

To use OpenID in your own application, you must configure Seam Security to use OpenIdAuthenticator, an Authenticator implementation that performs authentication against an OpenID provider. This authenticator is a named, session-scoped bean, with the following declaration:

public @Named("openIdAuthenticator") @SessionScoped class OpenIdAuthenticator

<?xml version="1.0" encoding="UTF-8"?>

<beans xmlns="http://java.sun.com/xml/ns/javaee"

   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

   xmlns:s="urn:java:ee" 

   xmlns:security="urn:java:org.jboss.seam.security"

   xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://jboss.org/schema/cdi/beans_1_0.xsd">



   <security:Identity>

      <s:modifies/>

      <security:authenticatorClass>org.jboss.seam.security.external.openid.OpenIdAuthenticator</security:authenticatorClass>

   </security:Identity>

<h:outputLabel value="Authenticate using:"/>

<h:selectOneRadio id="authenticator" value="#{identity.authenticatorName}">

  <f:selectItem itemLabel="OpenID" itemValue="openIdAuthenticator" />

  <f:selectItem itemLabel="Custom" itemValue="customAuthenticator" />

</h:selectOneRadio>

Seam provides built-in support for a number of well-known OpenID providers. The OpenIdAuthenticator bean may be configured to select which OpenID provider will be used to process an authentication request. Each concrete provider implements the following interface:

public interface OpenIdProvider {

   String getCode();

   String getName();

   String getUrl();

}

The following table lists the providers that come pre-packaged in Seam:

To select one of the built-in providers to use for an authentication request, the providerCode property of the OpenIdAuthenticator bean should be set to one of the Code values from the above table. The OpenIdAuthenticator bean provides a convenience method called getProviders() that returns a list of all known providers. This may be used in conjunction with a radio group to allow the user to select which OpenID provider they wish to authenticate with - see the following JSF snippet for an example:

<h:selectOneRadio value="#{openIdAuthenticator.providerCode}">

  <f:selectItems value="#{openIdAuthenticator.providers}" var="p" itemValue="#{p.code}" itemLabel="#{p.name}"/>

</h:selectOneRadio>

<h:outputLabel value="If you have selected the Custom OpenID provider, please provide a URL:"/>

<h:inputText value="#{customOpenIdProvider.url}"/>

Your application must provide an implementation of the OpenIdRelyingPartySpi interface to process OpenID callback events. This interface declares the following methods:

public interface OpenIdRelyingPartySpi {

   void loginSucceeded(OpenIdPrincipal principal, ResponseHolder responseHolder);

   void loginFailed(String message, ResponseHolder responseHolder);      

      

The implementation is responsible for processing the response of the OpenID authentication, and is typically used to redirect the user to an appropriate page depending on whether authentication was successful or not.

There are two API calls that must be made in the case of a successful authentication. The first one should notify the OpenIdAuthenticator that the authentication attempt was successful, and pass it the OpenIdPrincipal object:

openIdAuthenticator.success(principal);

Secondly, a DeferredAuthenticationEvent must be fired to signify that a deferred authentication attempt has been completed:

deferredAuthentication.fire(new DeferredAuthenticationEvent());

After making these two API calls, the implementation may perform whatever additional logic is required. The following code shows a complete example:

import java.io.IOException;


import javax.enterprise.event.Event;

import javax.inject.Inject;

import javax.servlet.ServletContext;


import org.jboss.seam.security.events.DeferredAuthenticationEvent;

import org.jboss.seam.security.external.api.ResponseHolder;

import org.jboss.seam.security.external.openid.OpenIdAuthenticator;

import org.jboss.seam.security.external.openid.api.OpenIdPrincipal;

import org.jboss.seam.security.external.spi.OpenIdRelyingPartySpi;


public class OpenIdRelyingPartySpiImpl implements OpenIdRelyingPartySpi {

   @Inject private ServletContext servletContext;

   @Inject OpenIdAuthenticator openIdAuthenticator;   

   @Inject Event<DeferredAuthenticationEvent> deferredAuthentication;


   public void loginSucceeded(OpenIdPrincipal principal, ResponseHolder responseHolder) {

      try {

         openIdAuthenticator.success(principal);

         deferredAuthentication.fire(new DeferredAuthenticationEvent());

         

         responseHolder.getResponse().sendRedirect(servletContext.getContextPath() + "/UserInfo.jsf");

      } catch (IOException e) {

         throw new RuntimeException(e);

      }

   }


   public void loginFailed(String message, ResponseHolder responseHolder) {

      try {

         responseHolder.getResponse().sendRedirect(servletContext.getContextPath() + "/AuthenticationFailed.jsf");

      } catch (IOException e) {

         throw new RuntimeException(e);

      }

   }

}