That all depends on the requirements of your application. If you have minimal security requirements, for example if you only wish to restrict certain pages and actions to users who are logged in, or who belong to a certain role, then the simplified mode will probably be sufficient. The advantages of this is a more simplified configuration, significantly less libraries to include, and a smaller memory footprint.

If on the other hand, your application requires security checks based on contextual state or complex business rules, then you will require the features provided by the advanced mode.

The simplified authentication method uses a built-in JAAS login module, SeamLoginModule, which delegates authentication to one of your own Seam components. This login module is already configured inside Seam as part of a default application policy and as such does not require any additional configuration files. It allows you to write an authentication method using the entity classes that are provided by your own application. Configuring this simplified form of authentication requires the identity component to be configured in components.xml:

<components xmlns="http://jboss.com/products/seam/components"
            xmlns:core="http://jboss.com/products/seam/core"
            xmlns:security="http://jboss.com/products/seam/security"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation=
                "http://jboss.com/products/seam/core http://jboss.com/products/seam/core-1.2.xsd 
                 http://jboss.com/products/seam/components http://jboss.com/products/seam/components-1.2.xsd
                 http://jboss.com/products/seam/drools http://jboss.com/products/seam/drools-1.2.xsd"
                 http://jboss.com/products/seam/security http://jboss.com/products/seam/security-1.2.xsd">                
        
    <security:identity authenticate-method="#{authenticator.authenticate}"/>
    
</components>

If you wish to use the advanced security features such as rule-based permission checks, all you need to do is include the Drools (JBoss Rules) jars in your classpath, and add some additional configuration, described later.

The EL expression #{authenticator.authenticate} is a method binding indicating that the authenticate method of the authenticator component will be used to authenticate the user.

The authenticate-method property specified for identity in components.xml specifies which method will be used by SeamLoginModule to authenticate users. This method takes no parameters, and is expected to return a boolean indicating whether authentication is successful or not. The user's username and password can be obtained from Identity.instance().getUsername() and Identity.instance().getPassword(), respectively. Any roles that the user is a member of should be assigned using Identity.instance().addRole(). Here's a complete example of an authentication method inside a JavaBean component:

@Name("authenticator")
public class Authenticator {
   @In EntityManager entityManager;
   
   public boolean authenticate() {
      try
      {
         User user = (User) entityManager.createQuery(
            "from User where username = :username and password = :password")
            .setParameter("username", Identity.instance().getUsername())
            .setParameter("password", Identity.instance().getPassword())
            .getSingleResult();

         if (user.getRoles() != null)
         {
            for (UserRole mr : user.getRoles())
               Identity.instance().addRole(mr.getName());
         }

         return true;
      }
      catch (NoResultException ex)
      {
         FacesMessages.instance().add("Invalid username/password");
         return false;
      }
      
   }
   
}

In the above example, both User and UserRole are application-specific entity beans. The roles parameter is populated with the roles that the user is a member of, which should be added to the Set as literal string values, e.g. "admin", "user". In this case, if the user record is not found and a NoResultException thrown, the authentication method returns false to indicate the authentication failed.

The Identity component provides both username and password properties, catering for the most common authentication scenario. These properties can be bound directly to the username and password fields on a login form. Once these properties are set, calling the identity.login() method will authenticate the user using the provided credentials. Here's an example of a simple login form:

<div>
    <h:outputLabel for="name" value="Username"/>
    <h:inputText id="name" value="#{identity.username}"/>
</div>

<div>
    <h:outputLabel for="password" value="Password"/>
    <h:inputSecret id="password" value="#{identity.password}"/>
</div>

<div>
    <h:commandButton value="Login" action="#{identity.login}"/>
</div>

Similarly, logging out the user is done by calling #{identity.logout}. Calling this action will clear the security state of the currently authenticated user.

So to sum up, there are the three easy steps to configure authentication:

To prevent users from receiving the default error page in response to a security error, it's recommended that pages.xml is configured to redirect security errors to a more "pretty" page. The two main types of exceptions thrown by the security API are:

In the case of a NotLoggedInException, it is recommended that the user is redirected to either a login or registration page so that they can log in. For an AuthorizationException, it may be useful to redirect the user to an error page. Here's an example of a pages.xml file that redirects both of these security exceptions:

<pages>

    ...
    
    <exception class="org.jboss.seam.security.NotLoggedInException">
        <redirect view-id="/login.xhtml">
            <message>You must be logged in to perform this action</message>
        </redirect>
    </exception>
    
    <exception class="org.jboss.seam.security.AuthorizationException">
        <end-conversation/>
        <redirect view-id="/security_error.xhtml">
            <message>You do not have the necessary security privileges to perform this action.</message>
        </redirect>
    </exception>
  
</pages>

Most web applications require even more sophisticated handling of login redirection, so Seam includes some special functionality for handling this problem.

You can ask Seam to redirect the user to a login screen when an unauthenticated user tries to access a particular view (or wildcarded view id) as follows:

<pages login-view-id="/login.xhtml">

    <page view-id="/members/*" login-required="true"/>
    
    ...
    
</pages>

(This is less of a blunt instrument than the exception handler shown above, but should probably be used in conjunction with it.)

After the user logs in, we want to automatically send them back where they came from, so they can retry the action that required logging in. If you add the following event listeners to components.xml, attempts to access a restricted view while not logged in will be remembered, so that upon the user successfully logging in they will be redirected to the originally requested view, with any page parameters that existed in the original request.

<event type="org.jboss.seam.notLoggedIn">
    <action expression="#{redirect.captureCurrentView}"/>
</event>
    
<event type="org.jboss.seam.postAuthenticate">
    <action expression="#{redirect.returnToCapturedView}"/>
</event>

Note that login redirection is implemented as a conversation-scoped mechanism, so don't end the conversation in your authenticate() method.

This section explores some of the advanced features provided by the security API for addressing more complex security requirements.

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

Each of the authorization mechanisms provided by the Seam Security API are built upon the concept of a user being granted roles and/or permissions. A role is a group, or type, of user that may have been granted certain privileges for performing one or more specific actions within an application. A permission on the other hand is a privilege (sometimes once-off) for performing a single, specific action. It is entirely possible to build an application using nothing but permissions, however roles offer a higher level of convenience when granting privileges to groups of users.

Roles are simple, consisting of only a name such as "admin", "user", "customer", etc. Permissions consist of both a name and an action, and are represented within this documentation in the form name:action, for example customer:delete, or customer:insert.

Let's start by examining the simplest form of authorization, component security, starting with the @Restrict annotation.

@Name("account")
public class AccountAction {
    @Restrict public void delete() {
      ...
    }
}

@Restrict @Name("account")
public class AccountAction {
    public void insert() {
      ...
    }
    @Restrict("#{s:hasRole('admin')}") 
    public void delete() {
      ...
    }
}

@Name("account")
public class AccountAction {
    @In Account selectedAccount;
    @Restrict("#{s:hasPermission('account','modify',selectedAccount)}")
    public void modify() {
        selectedAccount.modify();
    }
}

public void deleteCustomer() {
    Identity.instance().checkRestriction("#{s:hasPermission('customer','delete',selectedCustomer)}");
}

if (!Identity.instance().hasRole("admin"))
     throw new AuthorizationException("Must be admin to perform this action");

if (!Identity.instance().hasPermission("customer", "create", null))
     throw new AuthorizationException("You may not create new customers");

One indication of a well designed user interface is that the user is not presented with options for which they don't have the necessary privileges to use. Seam Security allows conditional rendering of either 1) sections of a page or 2) individual controls, based upon the privileges of the user, using the very same EL expressions that are used for component security.

Let's take a look at some examples of interface security. First of all, let's pretend that we have a login form that should only be rendered if the user is not already logged in. Using the identity.isLoggedIn() property, we can write this:

<h:form class="loginForm" rendered="#{not identity.loggedIn}">

If the user isn't logged in, then the login form will be rendered - very straight forward so far. Now let's pretend there is a menu on the page that contains some actions which should only be accessible to users in the manager role. Here's one way that these could be written:

<h:outputLink action="#{reports.listManagerReports}" rendered="#{s:hasRole('manager')}">
    Manager Reports
</h:outputLink>

This is also quite straight forward. If the user is not a member of the manager role, then the outputLink will not be rendered. The rendered attribute can generally be used on the control itself, or on a surrounding <s:div> or <s:span> control.

Now for something more complex. Let's say you have a h:dataTable control on a page listing records for which you may or may not wish to render action links depending on the user's privileges. The s:hasPermission EL function allows us to pass in an object parameter which can be used to determine whether the user has the requested permission for that object or not. Here's how a dataTable with secured links might look:

<h:dataTable value="#{clients}" var="cl">
    <h:column>
        <f:facet name="header">Name</f:facet>
        #{cl.name}
    </h:column>
    <h:column>
        <f:facet name="header">City</f:facet>
        #{cl.city}
    </h:column>   
    <h:column>
        <f:facet name="header">Action</f:facet>
        <s:link value="Modify Client" action="#{clientAction.modify}"
                rendered="#{s:hasPermission('client','modify',cl)"/>
        <s:link value="Delete Client" action="#{clientAction.delete}"
                rendered="#{s:hasPermission('client','delete',cl)"/>
    </h:column>
</h:dataTable>

Page security requires that the application is using a pages.xml file, however is extremely simple to configure. Simply include a <restrict/> element within the page elements that you wish to secure. By default, if a value is not provided for the restrict element, an implied permission of {viewId}:render will be checked for whenever accessing that page. Otherwise the value will be evaluated as a standard security expression. Here's a couple of examples:

<page view-id="/settings.xhtml">
    <restrict/>
</page>
        
<page view-id="/reports.xhtml">    
    <restrict>#{s:hasRole('admin')}</restrict>
</page>

In the above example, the first page has an implied permission restriction of /settings.xhtml:render, while the second one checks that the user is a member of the admin role.

Seam security also makes it possible to apply security restrictions to read, insert, update and delete actions for entities.

To secure all actions for an entity class, add a @Restrict annotation on the class itself:

@Entity
@Name("customer")
@Restrict
public class Customer {
  ...
}

If no expression is specified in the @Restrict annotation, the default security check that is performed is a permission check of entityName:action, where entityName is the Seam component name of the entity (or the fully-qualified class name if no @Name is specified), and the action is either read, insert, update or delete.

It is also possible to only restrict certain actions, by placing a @Restrict annotation on the relevent entity lifecycle method (annotated as follows):

Here's an example of how an entity would be configured to perform a security check for any insert operations. Please note that the method is not required to do anything, the only important thing in regard to security is how it is annotated:

  @PrePersist @Restrict
  public void prePersist() {}      
   

And here's an example of an entity permission rule that checks if the authenticated user is allowed to insert a new MemberBlog record (from the seamspace example). The entity for which the security check is being made is automatically asserted into the working memory (in this case MemberBlog):

rule InsertMemberBlog
  no-loop
  activation-group "permissions"  
when
  check: PermissionCheck(name == "memberBlog", action == "insert", granted == false)
  Principal(principalName : name)
  MemberBlog(member : member -> (member.getUsername().equals(principalName)))
then
  check.grant();
end;

This rule will grant the permission memberBlog:insert if the currently authenticated user (indicated by the Principal fact) has the same name as the member for which the blog entry is being created. The "name : name" structure that can be seen in the Principal fact (and other places) is a variable binding - it binds the name property of the Principal to a variable called name. Variable bindings allow the value to be referred to in other places, such as the following line which compares the member's username to the Principal name. For more details, please refer to the JBoss Rules documentation.

Finally, we need to install a listener class that integrates Seam security with your JPA provider.

<?xml version="1.0" encoding="UTF-8"?>
<entity-mappings xmlns="http://java.sun.com/xml/ns/persistence/orm"
                 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                 xsi:schemaLocation="http://java.sun.com/xml/ns/persistence/orm http://java.sun.com/xml/ns/persistence/orm_1_0.xsd"
                 version="1.0">
                 
    <persistence-unit-metadata>
        <persistence-unit-defaults>
            <entity-listeners>
                <entity-listener class="org.jboss.seam.security.EntitySecurityListener"/>
            </entity-listeners>
        </persistence-unit-defaults>
    </persistence-unit-metadata>
    
</entity-mappings>

So how does the security API know whether a user has the customer:modify permission for a specific customer? Seam Security provides quite a novel method for determining user permissions, based on JBoss Rules. A couple of the advantages of using a rule engine are 1) a centralized location for the business logic that is behind each user permission, and 2) speed - JBoss Rules uses very efficient algorithms for evaluating large numbers of complex rules involving multiple conditions.

Seam Security expects to find a RuleBase component called securityRules which it uses to evaluate permission checks. This is configured in components.xml as follows:

<components xmlns="http://jboss.com/products/seam/components"
            xmlns:core="http://jboss.com/products/seam/core"
            xmlns:security="http://jboss.com/products/seam/security"
            xmlns:drools="http://jboss.com/products/seam/drools"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation=
                "http://jboss.com/products/seam/core http://jboss.com/products/seam/core-1.2.xsd 
                 http://jboss.com/products/seam/components http://jboss.com/products/seam/components-1.2.xsd
                 http://jboss.com/products/seam/drools http://jboss.com/products/seam/drools-1.2.xsd"
                 http://jboss.com/products/seam/security http://jboss.com/products/seam/security-1.2.xsd">                 
        
   <drools:rule-base name="securityRules">
       <drools:rule-files>
           <value>/META-INF/security.drl</value>
       </drools:rule-files>
   </drools:rule-base>    
   
</components>

Once the RuleBase component is configured, it's time to write the security rules.

For this step you need to create a file called security.drl in the /META-INF directory of your application's jar file. In actual fact this file can be called anything you want, and exist in any location as long as it is configured appropriately in components.xml.

So what should the security rules file contain? At this stage it might be a good idea to at least skim through the JBoss Rules documentation, however to get started here's an extremely simple example:

package MyApplicationPermissions;

import org.jboss.seam.security.PermissionCheck;
import org.jboss.seam.security.Role;

rule CanUserDeleteCustomers
when
  c: PermissionCheck(name == "customer", action == "delete")
  Role(name == "admin")
then
  c.grant();
end;

Let's break this down. The first thing we see is the package declaration. A package in JBoss Rules is essentially a collection of rules. The package name can be anything you want - it doesn't relate to anything else outside the scope of the rule base.

The next thing we can notice is a couple of import statements for the PermissionCheck and Role classes. These imports inform the rules engine that we'll be referencing these classes within our rules.

Finally we have the code for the rule. Each rule within a package should be given a unique name (usually describing the purpose of the rule). In this case our rule is called CanUserDeleteCustomers and will be used to check whether a user is allowed to delete a customer record.

Looking at the body of the rule definition we can notice two distinct sections. Rules have what is known as a left hand side (LHS) and a right hand side (RHS). The LHS consists of the conditional part of the rule, i.e. a list of conditions which must be satisfied for the rule to fire. The LHS is represented by the when section. The RHS is the consequence, or action section of the rule that will only be fired if all of the conditions in the LHS are met. The RHS is represented by the then section. The end of the rule is denoted by the end; line.

If we look at the LHS of the rule, we see two conditions listed there. Let's examine the first condition:

c: PermissionCheck(name == "customer", action == "delete")

In plain english, this condition is stating that there must exist a PermissionCheck object with a name property equal to "customer", and an action property equal to "delete" within the working memory. What is the working memory? It is a session-scoped object that contains the contextual information that is required by the rules engine to make a decision about a permission check. Each time the hasPermission() method is called, a temporary PermissionCheck object, or Fact, is asserted into the working memory. This PermissionCheck corresponds exactly to the permission that is being checked, so for example if you call hasPermission("account", "create", null) then a PermissionCheck object with a name equal to "account" and action equal to "create" will be asserted into the working memory for the duration of the permission check.

So what else is in the working memory? Besides the short-lived temporary facts asserted during a permission check, there are some longer-lived objects in the working memory that stay there for the entire duration of a user being authenticated. These include any java.security.Principal objects that are created as part of the authentication process, plus a org.jboss.seam.security.Role object for each of the roles that the user is a member of. It is also possible to assert additional long-lived facts into the working memory by calling RuleBasedIdentity.instance().getSecurityContext().assertObject(), passing the object as a parameter.

Getting back to our simple example, we can also notice that the first line of our LHS is prefixed with c:. This is a variable binding, and is used to refer back to the object that is matched by the condition. Moving onto the second line of our LHS, we see this:

Role(name == "admin")

This condition simply states that there must be a Role object with a name of "admin" within the working memory. As mentioned, user roles are asserted into the working memory as long-lived facts. So, putting both conditions together, this rule is essentially saying "I will fire if you are checking for the customer:delete permission and the user is a member of the admin role".

So what is the consequence of the rule firing? Let's take a look at the RHS of the rule:

c.grant()

The RHS consists of Java code, and in this case is invoking the grant() method of the c object, which as already mentioned is a variable binding for the PermissionCheck object. Besides the name and action properties of the PermissionCheck object, there is also a granted property which is initially set to false. Calling grant() on a PermissionCheck sets the granted property to true, which means that the permission check was successful, allowing the user to carry out whatever action the permission check was intended for.

rule CanDoAnythingToCustomersIfYouAreAnAdmin
when
  c: PermissionCheck(name == "customer")
  Role(name == "admin")
then
  c.grant();
end;        
        

To get up and running, it is necessary to configure the Seam Resource Servlet, which will provide the Captcha challenge images to your pages. This requires the following entry in web.xml:

<servlet>
    <servlet-name>Seam Resource Servlet</servlet-name>
    <servlet-class>org.jboss.seam.servlet.ResourceServlet</servlet-class>
</servlet>
    
<servlet-mapping>
    <servlet-name>Seam Resource Servlet</servlet-name>
    <url-pattern>/seam/resource/*</url-pattern>
</servlet-mapping>

Adding a captcha challenge to a page is extremely easy. Seam provides a page-scoped component, captcha, which provides everything that is required, including built-in captcha validation. Here's an example:

<div>
    <h:graphicImage value="/seam/resource/captcha?#{captcha.id}"/>
</div>
  
<div>
    <h:outputLabel for="verifyCaptcha">Enter the above letters</h:outputLabel>
    <h:inputText id="verifyCaptcha" value="#{captcha.response}" required="true"/>
    <div class="validationError"><h:message for="verifyCaptcha"/></div>
</div>

That's all there is to it. The graphicImage control displays the Captcha challenge, and the inputText receives the user's response. The response is automatically validated against the Captcha when the form is submitted.