SeamFramework.org Community Documentation

- Prev
- Next

## Chapter 16. Security

## 16.1. Overview

The Seam Security API provides a multitude of security-related features for your Seam-based application, covering such areas as:

- Authentication - an extensible, JAAS-based authentication layer that allows users to authenticate against any security provider.

- Identity Management - an API for managing a Seam application's users and roles at runtime.

- Authorization - an extremely comprehensive authorization framework, supporting user roles, persistent and rule-based permissions, and a pluggable permission resolver for easily implementing customised security logic.

- Permission Management - a set of built-in Seam components to allow easy management of an application's security policy.

- CAPTCHA support - to assist in the prevention of automated software/scripts abusing your Seam-based site.

- And much more

This chapter will cover each of these features in detail.

## 16.2. Disabling Security

In some situations it may be necessary to disable Seam Security, for instances during unit tests or because you are using a different approach to security, such as native JAAS. Simply call the static method `Identity.setSecurityEnabled(false)` to disable the security infrastructure. Of course, it's not very convenient to have to call a static method when you want to configure the application, so as an alternative you can control this setting in components.xml:

- Entity Security

- Hibernate Security Interceptor

- Seam Security Interceptor

- Page restrictions

- Servlet API security integration

Assuming you are planning to take advantage of what Seam Security has to offer, the rest of this chapter documents the plethora of options you have for giving your user an identity in the eyes of the security model (authentication) and locking down the application by establishing constraints (authorization). Let's begin with the task of authentication since that's the foundation of any security model.

## 16.3. Authentication

The authentication features provided by Seam Security are built upon JAAS (Java Authentication and Authorization Service), and as such provide a robust and highly configurable API for handling user authentication. However, for less complex authentication requirements Seam offers a much more simplified method of authentication that hides the complexity of JAAS.

### 16.3.1. Configuring an Authenticator component

## Note

If you use Seam's Identity Management features (discussed later in this chapter) then it is not necessary to create an authenticator component (and you can skip this section).

The simplified authentication method provided by Seam 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, or alternatively to authenticate with some other third party provider. Configuring this simplified form of authentication requires the `identity` component to be configured in `components.xml`:

    <components xmlns="http://jboss.org/schema/seam/components"

                xmlns:core="http://jboss.org/schema/seam/core"

                xmlns:security="http://jboss.org/schema/seam/security"

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

                xsi:schemaLocation=

                    "http://jboss.org/schema/seam/components http://jboss.org/schema/seam/components-2.3.xsd

                     http://jboss.org/schema/seam/security http://jboss.org/schema/seam/security-2.3.xsd">

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

    </components>

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

### 16.3.2. Writing an authentication method

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, which indicates whether authentication is successful or not. The user's username and password can be obtained from `Credentials.getUsername()` and `Credentials.getPassword()`, respectively (you can get a reference to the `credentials` component via `Identity.instance().getCredentials()`). Any roles that the user is a member of should be assigned using `Identity.addRole()`. Here's a complete example of an authentication method inside a POJO component:

    @Name("authenticator")

    public class Authenticator {

       @In EntityManager entityManager;

       @In Credentials credentials;

       @In Identity identity;

       public boolean authenticate() {

          try {

             User user = (User) entityManager.createQuery(

                "from User where username = :username and password = :password")

                .setParameter("username", credentials.getUsername())

                .setParameter("password", credentials.getPassword())

                .getSingleResult();

             if (user.getRoles() != null) {

                for (UserRole mr : user.getRoles())

                   identity.addRole(mr.getName());

             }

             return true;

          }

          catch (NoResultException ex) {

             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.

## Tip

When writing an authenticator method, it is important that it is kept minimal and free from any side-effects. This is because there is no guarantee as to how many times the authenticator method will be called by the security API, and as such it may be invoked multiple times during a single request. Because of this, any special code that should execute upon a successful or failed authentication should be written by implementing an event observer. See the section on Security Events further down in this chapter for more information about which events are raised by Seam Security.

#### 16.3.2.1. Identity.addRole()

The `Identity.addRole()` method behaves differently depending on whether the current session is authenticated or not. If the session is not authenticated, then `addRole()` should only be called during the authentication process. When called here, the role name is placed into a temporary list of pre-authenticated roles. Once authentication is successful, the pre-authenticated roles then become "real" roles, and calling `Identity.hasRole()` for those roles will then return true. The following sequence diagram represents the list of pre-authenticated roles as a first class object to show more clearly how it fits in to the authentication process.

If the current session is already authenticated, then calling `Identity.addRole()` will have the expected effect of immediately granting the specified role to the current user.

#### 16.3.2.2. Writing an event observer for security-related events

Say for example, that upon a successful login that some user statistics must be updated. This would be done by writing an event observer for the `org.jboss.seam.security.loginSuccessful` event, like this:

       @In UserStats userStats;

       @Observer("org.jboss.seam.security.loginSuccessful")

       public void updateUserStats()

       {

          userStats.setLastLoginDate(new Date());

          userStats.incrementLoginCount();

       }

This observer method can be placed anywhere, even in the Authenticator component itself. You can find more information about security-related events later in this chapter.

### 16.3.3. Writing a login form

The `credentials` 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 `identity.login()` 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="#{credentials.username}"/>

    </div>

    <div>

        <h:outputLabel for="password" value="Password"/>

        <h:inputSecret id="password" value="#{credentials.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, and invalidate the user's session.

### 16.3.4. Configuration Summary

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

- Configure an authentication method in `components.xml`.

- Write an authentication method.

- Write a login form so that the user can authenticate.

### 16.3.5. Remember Me

Seam Security supports the same kind of "Remember Me" functionality that is commonly encountered in many online web-based applications. It is actually supported in two different "flavours", or modes - the first mode allows the username to be stored in the user's browser as a cookie, and leaves the entering of the password up to the browser (many modern browsers are capable of remembering passwords).

The second mode supports the storing of a unique token in a cookie, and allows a user to authenticate automatically upon returning to the site, without having to provide a password.

## Warning

Automatic client authentication with a persistent cookie stored on the client machine is dangerous. While convenient for users, any cross-site scripting security hole in your website would have dramatically more serious effects than usual. Without the authentication cookie, the only cookie to steal for an attacker with XSS is the cookie of the current session of a user. This means the attack only works when the user has an open session - which should be a short timespan. However, it is much more attractive and dangerous if an attacker has the possibility to steal a persistent Remember Me cookie that allows him to login without authentication, at any time. Note that this all depends on how well you protect your website against XSS attacks - it's up to you to make sure that your website is 100% XSS safe - a non-trivial achievement for any website that allows user input to be rendered on a page.

Browser vendors recognized this issue and introduced a "Remember Passwords" feature - today almost all browsers support this. Here, the browser remembers the login username and password for a particular website and domain, and fills out the login form automatically when you don't have an active session with the website. If you as a website designer then offer a convenient login keyboard shortcut, this approach is almost as convenient as a "Remember Me" cookie and much safer. Some browsers (e.g. Safari on OS X) even store the login form data in the encrypted global operation system keychain. Or, in a networked environment, the keychain can be transported with the user (between laptop and desktop for example), while browser cookies are usually not synchronized.

To summarize: While everyone is doing it, persistent "Remember Me" cookies with automatic authentication are a bad practice and should not be used. Cookies that "remember" only the users login name, and fill out the login form with that username as a convenience, are not an issue.

To enable the remember me feature for the default (safe, username only) mode, no special configuration is required. In your login form, simply bind the remember me checkbox to `rememberMe.enabled`, like in the following example:

      <div>

        <h:outputLabel for="name" value="User name"/>

        <h:inputText id="name" value="#{credentials.username}"/>

      </div>

      <div>

        <h:outputLabel for="password" value="Password"/>

        <h:inputSecret id="password" value="#{credentials.password}" redisplay="true"/>

      </div>

      <div class="loginRow">

        <h:outputLabel for="rememberMe" value="Remember me"/>

        <h:selectBooleanCheckbox id="rememberMe" value="#{rememberMe.enabled}"/>

      </div>

#### 16.3.5.1. Token-based Remember-me Authentication

To use the automatic, token-based mode of the remember me feature, you must first configure a token store. The most common scenario is to store these authentication tokens within a database (which Seam supports), however it is possible to implement your own token store by implementing the `org.jboss.seam.security.TokenStore` interface. This section will assume you will be using the provided `JpaTokenStore` implementation to store authentication tokens inside a database table.

The first step is to create a new Entity which will contain the tokens. The following example shows a possible structure that you may use:

    @Entity

    public class AuthenticationToken implements Serializable {

       private Integer tokenId;

       private String username;

       private String value;

       @Id @GeneratedValue

       public Integer getTokenId() {

          return tokenId;

       }

       public void setTokenId(Integer tokenId) {

          this.tokenId = tokenId;

       }

       @TokenUsername

       public String getUsername() {

          return username;

       }

       public void setUsername(String username) {

          this.username = username;

       }

       @TokenValue

       public String getValue() {

          return value;

       }

       public void setValue(String value) {

          this.value = value;

       }

    }

As you can see from this listing, a couple of special annotations, `@TokenUsername` and `@TokenValue` are used to configure the username and token properties of the entity. These annotations are required for the entity that will contain the authentication tokens.

The next step is to configure `JpaTokenStore` to use this entity bean to store and retrieve authentication tokens. This is done in `components.xml` by specifying the `token-class` attribute:

    <security:jpa-token-store token-class="org.jboss.seam.example.seamspace.AuthenticationToken" />

Once this is done, the last thing to do is to configure the `RememberMe` component in `components.xml` also. Its `mode` should be set to `autoLogin`:

    <security:remember-me mode="autoLogin"/>

That is all that is required - automatic authentication will now occur for users revisiting your site (as long as they check the "remember me" checkbox).

To ensure that users are automatically authenticated when returning to the site, the following section should be placed in components.xml:

            <event type="org.jboss.seam.security.notLoggedIn">

        <action execute="#{redirect.captureCurrentView}"/>

        <action execute="#{identity.tryLogin()}"/>

      </event>

      <event type="org.jboss.seam.security.loginSuccessful">

        <action execute="#{redirect.returnToCapturedView}"/>

      </event>

### 16.3.6. Handling Security Exceptions

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:

- `NotLoggedInException` - This exception is thrown if the user attempts to access a restricted action or page when they are not logged in.

- `AuthorizationException` - This exception is only thrown if the user is already logged in, and they have attempted to access a restricted action or page for which they do not have the necessary privileges.

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.

### 16.3.7. Login Redirection

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>

## Tip

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.security.notLoggedIn">

        <action execute="#{redirect.captureCurrentView}"/>

    </event>

    <event type="org.jboss.seam.security.postAuthenticate">

        <action execute="#{redirect.returnToCapturedView}"/>

    </event>

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

### 16.3.8. HTTP Authentication

Although not recommended for use unless absolutely necessary, Seam provides means for authenticating using either HTTP Basic or HTTP Digest (RFC 2617) methods. To use either form of authentication, the `authentication-filter` component must be enabled in components.xml:

      <web:authentication-filter url-pattern="*.seam" auth-type="basic"/>

To enable the filter for basic authentication, set `auth-type` to `basic`, or for digest authentication, set it to `digest`. If using digest authentication, the `key` and `realm` must also be set:

      <web:authentication-filter url-pattern="*.seam" auth-type="digest" key="AA3JK34aSDlkj" realm="My App"/>

The `key` can be any String value. The `realm` is the name of the authentication realm that is presented to the user when they authenticate.

#### 16.3.8.1. Writing a Digest Authenticator

If using digest authentication, your authenticator class should extend the abstract class `org.jboss.seam.security.digest.DigestAuthenticator`, and use the `validatePassword()` method to validate the user's plain text password against the digest request. Here is an example:

       public boolean authenticate()

       {

          try

          {

             User user = (User) entityManager.createQuery(

                "from User where username = :username")

                .setParameter("username", identity.getUsername())

                .getSingleResult();

             return validatePassword(user.getPassword());

          }

          catch (NoResultException ex)

          {

             return false;

          }

       }

### 16.3.9. Advanced Authentication Features

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

#### 16.3.9.1. Using your container's JAAS configuration

If you would rather not use the simplified JAAS configuration provided by the Seam Security API, you may instead delegate to the default system JAAS configuration by providing a `jaas-config-name` property in `components.xml`. For example, if you are using JBoss AS and wish to use the `other` policy (which uses the `UsersRolesLoginModule` login module provided by JBoss AS), then the entry in `components.xml` would look like this:

    <security:identity jaas-config-name="other"/>

Please keep in mind that doing this does not mean that your user will be authenticated in whichever container your Seam application is deployed in. It merely instructs Seam Security to authenticate itself using the configured JAAS security policy.

## 16.4. Identity Management

Identity Management provides a standard API for the management of a Seam application's users and roles, regardless of which identity store (database, LDAP, etc) is used on the backend. At the center of the Identity Management API is the `identityManager` component, which provides all the methods for creating, modifying and deleting users, granting and revoking roles, changing passwords, enabling and disabling user accounts, authenticating users and listing users and roles.

Before it may be used, the `identityManager` must first be configured with one or more `IdentityStore`s. These components do the actual work of interacting with the backend security provider, whether it be a database, LDAP server, or something else.

### 16.4.1. Configuring IdentityManager

The `identityManager` component allows for separate identity stores to be configured for authentication and authorization operations. This means that it is possible for users to be authenticated against one identity store, for example an LDAP directory, yet have their roles loaded from another identity store, such as a relational database.

Seam provides two `IdentityStore` implementations out of the box; `JpaIdentityStore` uses a relational database to store user and role information, and is the default identity store that is used if nothing is explicitly configured in the `identityManager` component. The other implementation that is provided is `LdapIdentityStore`, which uses an LDAP directory to store users and roles.

There are two configurable properties for the `identityManager` component - `identityStore` and `roleIdentityStore`. The value for these properties must be an EL expression referring to a Seam component implementing the `IdentityStore` interface. As already mentioned, if left unconfigured then `JpaIdentityStore` will be assumed by default. If only the `identityStore` property is configured, then the same value will be used for `roleIdentityStore` also. For example, the following entry in `components.xml` will configure `identityManager` to use an `LdapIdentityStore` for both user-related and role-related operations:

      <security:identity-manager identity-store="#{ldapIdentityStore}"/>

The following example configures `identityManager` to use an `LdapIdentityStore` for user-related operations, and `JpaIdentityStore` for role-related operations:

      <security:identity-manager

        identity-store="#{ldapIdentityStore}"

        role-identity-store="#{jpaIdentityStore}"/>

The following sections explain both of these identity store implementations in greater detail.

### 16.4.2. JpaIdentityStore

This identity store allows for users and roles to be stored inside a relational database. It is designed to be as unrestrictive as possible in regards to database schema design, allowing a great deal of flexibility in the underlying table structure. This is achieved through the use of a set of special annotations, allowing entity beans to be configured to store user and role records.

#### 16.4.2.1. Configuring JpaIdentityStore

`JpaIdentityStore` requires that both the `user-class` and `role-class` properties are configured. These properties should refer to the entity classes that are to be used to store both user and role records, respectively. The following example shows the configuration from `components.xml` in the SeamSpace example:

      <security:jpa-identity-store

        user-class="org.jboss.seam.example.seamspace.MemberAccount"

        role-class="org.jboss.seam.example.seamspace.MemberRole"/>

#### 16.4.2.2. Configuring the Entities

As already mentioned, a set of special annotations are used to configure entity beans for storing users and roles. The following table lists each of the annotations, and their descriptions.

Table 16.1. User Entity Annotations

Annotation | Status | Description
--- | --- | ---
`@UserPrincipal` | Required | This annotation marks the field or method containing the user's username.
`@UserPassword` | Required | This annotation marks the field or method containing the user's password. It allows a `hash` algorithm to be specified for password hashing. Possible values for `hash` are `md5`, `sha` and `none`. E.g:
    @UserPassword (hash="md5")

    public String getPasswordHash() {

      return passwordHash;

    }
If an application requires a hash algorithm that isn't supported natively by Seam, it is possible to extend the `PasswordHash` component to implement other hashing algorithms.
`@UserFirstName` | Optional | This annotation marks the field or method containing the user's first name.
`@UserLastName` | Optional | This annotation marks the field or method containing the user's last name.
`@UserEnabled` | Optional | This annotation marks the field or method containing the enabled status of the user. This should be a boolean property, and if not present then all user accounts are assumed to be enabled.
`@UserRoles` | Required | This annotation marks the field or method containing the roles of the user. This property will be described in more detail further down.

Table 16.2. Role Entity Annotations

Annotation | Status | Description
--- | --- | ---
`@RoleName` | Required | This annotation marks the field or method containing the name of the role.
`@RoleGroups` | Optional | This annotation marks the field or method containing the group memberships of the role.
`@RoleConditional` | Optional | This annotation marks the field or method indicating whether the role is conditional or not. Conditional roles are explained later in this chapter.

#### 16.4.2.3. Entity Bean Examples

As mentioned previously, `JpaIdentityStore` is designed to be as flexible as possible when it comes to the database schema design of your user and role tables. This section looks at a number of possible database schemas that can be used to store user and role records.

##### 16.4.2.3.1. Minimal schema example

In this bare minimal example, a simple user and role table are linked via a many-to-many relationship using a cross-reference table named `UserRoles`.

    @Entity

    public class User {

      private Integer userId;

      private String username;

      private String passwordHash;

      private Set<Role> roles;

      @Id @GeneratedValue

      public Integer getUserId() { return userId; }

      public void setUserId(Integer userId) { this.userId = userId; }

      @UserPrincipal

      public String getUsername() { return username; }

      public void setUsername(String username) { this.username = username; }

      @UserPassword(hash = "md5")

      public String getPasswordHash() { return passwordHash; }

      public void setPasswordHash(String passwordHash) { this.passwordHash = passwordHash; }

      @UserRoles

      @ManyToMany(targetEntity = Role.class)

      @JoinTable(name = "UserRoles",

        joinColumns = @JoinColumn(name = "UserId"),

        inverseJoinColumns = @JoinColumn(name = "RoleId"))

      public Set<Role> getRoles() { return roles; }

      public void setRoles(Set<Role> roles) { this.roles = roles; }

    }

    @Entity

    public class Role {

      private Integer roleId;

      private String rolename;

      @Id @Generated

      public Integer getRoleId() { return roleId; }

      public void setRoleId(Integer roleId) { this.roleId = roleId; }

      @RoleName

      public String getRolename() { return rolename; }

      public void setRolename(String rolename) { this.rolename = rolename; }

    }

##### 16.4.2.3.2. Complex Schema Example

This example builds on the above minimal example by including all of the optional fields, and allowing group memberships for roles.

    @Entity

    public class User {

      private Integer userId;

      private String username;

      private String passwordHash;

      private Set<Role> roles;

      private String firstname;

      private String lastname;

      private boolean enabled;

      @Id @GeneratedValue

      public Integer getUserId() { return userId; }

      public void setUserId(Integer userId) { this.userId = userId; }

      @UserPrincipal

      public String getUsername() { return username; }

      public void setUsername(String username) { this.username = username; }

      @UserPassword(hash = "md5")

      public String getPasswordHash() { return passwordHash; }

      public void setPasswordHash(String passwordHash) { this.passwordHash = passwordHash; }

      @UserFirstName

      public String getFirstname() { return firstname; }

      public void setFirstname(String firstname) { this.firstname = firstname; }

      @UserLastName

      public String getLastname() { return lastname; }

      public void setLastname(String lastname) { this.lastname = lastname; }

      @UserEnabled

      public boolean isEnabled() { return enabled; }

      public void setEnabled(boolean enabled) { this.enabled = enabled; }

      @UserRoles

      @ManyToMany(targetEntity = Role.class)

      @JoinTable(name = "UserRoles",

        joinColumns = @JoinColumn(name = "UserId"),

        inverseJoinColumns = @JoinColumn(name = "RoleId"))

      public Set<Role> getRoles() { return roles; }

      public void setRoles(Set<Role> roles) { this.roles = roles; }

    }

    @Entity

    public class Role {

      private Integer roleId;

      private String rolename;

      private boolean conditional;

      @Id @Generated

      public Integer getRoleId() { return roleId; }

      public void setRoleId(Integer roleId) { this.roleId = roleId; }

      @RoleName

      public String getRolename() { return rolename; }

      public void setRolename(String rolename) { this.rolename = rolename; }

      @RoleConditional

      public boolean isConditional() { return conditional; }

      public void setConditional(boolean conditional) { this.conditional = conditional; }

      @RoleGroups

      @ManyToMany(targetEntity = Role.class)

      @JoinTable(name = "RoleGroups",

        joinColumns = @JoinColumn(name = "RoleId"),

        inverseJoinColumns = @JoinColumn(name = "GroupId"))

      public Set<Role> getGroups() { return groups; }

      public void setGroups(Set<Role> groups) { this.groups = groups; }

    }

#### 16.4.2.4. JpaIdentityStore Events

When using `JpaIdentityStore` as the identity store implementation with `IdentityManager`, a few events are raised as a result of invoking certain `IdentityManager` methods.

##### 16.4.2.4.1. JpaIdentityStore.EVENT_PRE_PERSIST_USER

This event is raised in response to calling `IdentityManager.createUser()`. Just before the user entity is persisted to the database, this event will be raised passing the entity instance as an event parameter. The entity will be an instance of the `user-class` configured for `JpaIdentityStore`.

Writing an observer for this event may be useful for setting additional field values on the entity, which aren't set as part of the standard `createUser()` functionality.

##### 16.4.2.4.2. JpaIdentityStore.EVENT_USER_CREATED

This event is also raised in response to calling `IdentityManager.createUser()`. However, it is raised after the user entity has already been persisted to the database. Like the `EVENT_PRE_PERSIST_USER` event, it also passes the entity instance as an event parameter. It may be useful to observe this event if you also need to persist other entities that reference the user entity, for example contact detail records or other user-specific data.

##### 16.4.2.4.3. JpaIdentityStore.EVENT_USER_AUTHENTICATED

This event is raised when calling `IdentityManager.authenticate()`. It passes the user entity instance as the event parameter, and is useful for reading additional properties from the user entity that is being authenticated.

### 16.4.3. LdapIdentityStore

This identity store implementation is designed for working with user records stored in an LDAP directory. It is very highly configurable, allowing great flexibility in how both users and roles are stored in the directory. The following sections describe the configuration options for this identity store, and provide some configuration examples.

#### 16.4.3.1. Configuring LdapIdentityStore

The following table describes the available properties that can be configured in `components.xml` for `LdapIdentityStore`.

Table 16.3. LdapIdentityStore Configuration Properties

Property | Default Value | Description
--- | --- | ---
`server-address` | `localhost` | The address of the LDAP server.
`server-port` | `389` | The port number that the LDAP server is listening on.
`user-context-DN` | `ou=Person,dc=acme,dc=com` | The Distinguished Name (DN) of the context containing user records.
`user-DN-prefix` | `uid=` | This value is prefixed to the front of the username to locate the user's record.
`user-DN-suffix` | `,ou=Person,dc=acme,dc=com` | This value is appended to the end of the username to locate the user's record.
`role-context-DN` | `ou=Role,dc=acme,dc=com` | The DN of the context containing role records.
`role-DN-prefix` | `cn=` | This value is prefixed to the front of the role name to form the DN for locating the role record.
`role-DN-suffix` | `,ou=Roles,dc=acme,dc=com` | This value is appended to the role name to form the DN for locating the role record.
`bind-DN` | `cn=Manager,dc=acme,dc=com` | This is the context used to bind to the LDAP server.
`bind-credentials` | `secret` | These are the credentials (the password) used to bind to the LDAP server.
`user-role-attribute` | `roles` | This is the name of the attribute of the user record that contains the list of roles that the user is a member of.
`role-attribute-is-DN` | `true` | This boolean property indicates whether the role attribute of the user record is itself a distinguished name.
`user-name-attribute` | `uid` | Indicates which attribute of the user record contains the username.
`user-password-attribute` | `userPassword` | Indicates which attribute of the user record contains the user's password.
`first-name-attribute` | `null` | Indicates which attribute of the user record contains the user's first name.
`last-name-attribute` | `sn` | Indicates which attribute of the user record contains the user's last name.
`full-name-attribute` | `cn` | Indicates which attribute of the user record contains the user's full (common) name.
`enabled-attribute` | `null` | Indicates which attribute of the user record determines whether the user is enabled.
`role-name-attribute` | `cn` | Indicates which attribute of the role record contains the name of the role.
`object-class-attribute` | `objectClass` | Indicates which attribute determines the class of an object in the directory.
`role-object-classes` | `organizationalRole` | An array of the object classes that new role records should be created as.
`user-object-classes` | `person,uidObject` | An array of the object classes that new user records should be created as.
`security-authentication-type` | `simple` | The security level to use. Possible values are "none", "simple" and "strong".

#### 16.4.3.2. LdapIdentityStore Configuration Example

The following configuration example shows how `LdapIdentityStore` may be configured for an LDAP directory running on fictional host `directory.mycompany.com`. The users are stored within this directory under the context `ou=Person,dc=mycompany,dc=com`, and are identified using the `uid` attribute (which corresponds to their username). Roles are stored in their own context, `ou=Roles,dc=mycompany,dc=com` and referenced from the user's entry via the `roles` attribute. Role entries are identified by their common name (the `cn` attribute) , which corresponds to the role name. In this example, users may be disabled by setting the value of their `enabled` attribute to false.

      <security:ldap-identity-store

        server-address="directory.mycompany.com"

        bind-DN="cn=Manager,dc=mycompany,dc=com"

        bind-credentials="secret"

        user-DN-prefix="uid="

        user-DN-suffix=",ou=Person,dc=mycompany,dc=com"

        role-DN-prefix="cn="

        role-DN-suffix=",ou=Roles,dc=mycompany,dc=com"

        user-context-DN="ou=Person,dc=mycompany,dc=com"

        role-context-DN="ou=Roles,dc=mycompany,dc=com"

        user-role-attribute="roles"

        role-name-attribute="cn"

        user-object-classes="person,uidObject"

        enabled-attribute="enabled"

        />

### 16.4.4. Writing your own IdentityStore

Writing your own identity store implementation allows you to authenticate and perform identity management operations against security providers that aren't supported out of the box by Seam. Only a single class is required to achieve this, and it must implement the `org.jboss.seam.security.management.IdentityStore` interface.

Please refer to the JavaDoc for `IdentityStore` for a description of the methods that must be implemented.

### 16.4.5. Authentication with Identity Management

If you are using the Identity Management features in your Seam application, then it is not required to provide an authenticator component (see previous Authentication section) to enable authentication. Simply omit the `authenticate-method` from the `identity` configuration in `components.xml`, and the `SeamLoginModule` will by default use `IdentityManager` to authenticate your application's users, without any special configuration required.

### 16.4.6. Using IdentityManager

The `IdentityManager` can be accessed either by injecting it into your Seam component as follows:

      @In IdentityManager identityManager;

or by accessing it through its static `instance()` method:

      IdentityManager identityManager = IdentityManager.instance();

The following table describes `IdentityManager`'s API methods:

Table 16.4. Identity Management API

Method | Returns | Description
--- | --- | ---
`createUser(String name, String password)` | `boolean` | Creates a new user account, with the specified name and password. Returns `true` if successful, or `false` if not.
`deleteUser(String name)` | `boolean` | Deletes the user account with the specified name. Returns `true` if successful, or `false` if not.
`createRole(String role)` | `boolean` | Creates a new role, with the specified name. Returns `true` if successful, or `false` if not.
`deleteRole(String name)` | `boolean` | Deletes the role with the specified name. Returns `true` if successful, or `false` if not.
`enableUser(String name)` | `boolean` | Enables the user account with the specified name. Accounts that are not enabled are not able to authenticate. Returns `true` if successful, or `false` if not.
`disableUser(String name)` | `boolean` | Disables the user account with the specified name. Returns `true` if successful, or `false` if not.
`changePassword(String name, String password)` | `boolean` | Changes the password for the user account with the specified name. Returns `true` if successful, or `false` if not.
`isUserEnabled(String name)` | `boolean` | Returns `true` if the specified user account is enabled, or `false` if it isn't.
`grantRole(String name, String role)` | `boolean` | Grants the specified role to the specified user or role. The role must already exist for it to be granted. Returns `true` if the role is successfully granted, or `false` if it is already granted to the user.
`revokeRole(String name, String role)` | `boolean` | Revokes the specified role from the specified user or role. Returns `true` if the specified user is a member of the role and it is successfully revoked, or `false` if the user is not a member of the role.
`userExists(String name)` | `boolean` | Returns `true` if the specified user exists, or `false` if it doesn't.
`listUsers()` | `List` | Returns a list of all user names, sorted in alpha-numeric order.
`listUsers(String filter)` | `List` | Returns a list of all user names filtered by the specified filter parameter, sorted in alpha-numeric order.
`listRoles()` | `List` | Returns a list of all role names.
`getGrantedRoles(String name)` | `List` | Returns a list of the names of all the roles explicitly granted to the specified user name.
`getImpliedRoles(String name)` | `List` | Returns a list of the names of all the roles implicitly granted to the specified user name. Implicitly granted roles include those that are not directly granted to a user, rather they are granted to the roles that the user is a member of. For example, is the `admin` role is a member of the `user` role, and a user is a member of the `admin` role, then the implied roles for the user are both the `admin`, and `user` roles.
`authenticate(String name, String password)` | `boolean` | Authenticates the specified username and password using the configured Identity Store. Returns `true` if successful or `false` if authentication failed. Successful authentication implies nothing beyond the return value of the method. It does not change the state of the `Identity` component - to perform a proper Seam login the `Identity.login()` must be used instead.
`addRoleToGroup(String role, String group)` | `boolean` | Adds the specified role as a member of the specified group. Returns true if the operation is successful.
`removeRoleFromGroup(String role, String group)` | `boolean` | Removes the specified role from the specified group. Returns true if the operation is successful.
`listRoles()` | `List` | Lists the names of all roles.

Using the Identity Management API requires that the calling user has the appropriate authorization to invoke its methods. The following table describes the permission requirements for each of the methods in `IdentityManager`. The permission targets listed below are literal String values.

Table 16.5. Identity Management Security Permissions

Method | Permission Target | Permission Action
--- | --- | ---
`createUser()` | `seam.user` | `create`
`deleteUser()` | `seam.user` | `delete`
`createRole()` | `seam.role` | `create`
`deleteRole()` | `seam.role` | `delete`
`enableUser()` | `seam.user` | `update`
`disableUser()` | `seam.user` | `update`
`changePassword()` | `seam.user` | `update`
`isUserEnabled()` | `seam.user` | `read`
`grantRole()` | `seam.user` | `update`
`revokeRole()` | `seam.user` | `update`
`userExists()` | `seam.user` | `read`
`listUsers()` | `seam.user` | `read`
`listRoles()` | `seam.role` | `read`
`addRoleToGroup()` | `seam.role` | `update`
`removeRoleFromGroup()` | `seam.role` | `update`

The following code listing provides an example set of security rules that grants access to all Identity Management-related methods to members of the `admin` role:

    rule ManageUsers
      no-loop
      activation-group "permissions"
    when
      check: PermissionCheck(name == "seam.user", granted == false)
      Role(name == "admin")
    then
      check.grant();
    end

    rule ManageRoles
      no-loop
      activation-group "permissions"
    when
      check: PermissionCheck(name == "seam.role", granted == false)
      Role(name == "admin")
    then
      check.grant();
    end

## 16.5. Error Messages

The security API produces a number of default faces messages for various security-related events. The following table lists the message keys that can be used to override these messages by specifying them in a `message.properties` resource file. To suppress the message, just put the key with an empty value in the resource file.

Table 16.6. Security Message Keys

Message Key | Description
--- | ---
`org.jboss.seam.loginSuccessful` | This message is produced when a user successfully logs in via the security API.
`org.jboss.seam.loginFailed` | This message is produced when the login process fails, either because the user provided an incorrect username or password, or because authentication failed in some other way.
`org.jboss.seam.NotLoggedIn` | This message is produced when a user attempts to perform an action or access a page that requires a security check, and the user is not currently authenticated.
`org.jboss.seam.AlreadyLoggedIn` | This message is produced when a user that is already authenticated attempts to log in again.

## 16.6. Authorization

There are a number of authorization mechanisms provided by the Seam Security API for securing access to components, component methods, and pages. This section describes each of these. An important thing to note is that if you wish to use any of the advanced features (such as rule-based permissions) then your `components.xml` may need to be configured to support this - see the Configuration section above.

### 16.6.1. Core concepts

Seam Security is built around the premise of users being granted roles and/or permissions, allowing them to perform operations that may not otherwise be permissible for users without the necessary security privileges. Each of the authorization mechanisms provided by the Seam Security API are built upon this core concept of roles and permissions, with an extensible framework providing multiple ways to secure application resources.

#### 16.6.1.1. What is a role?

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. They are simple constructs, consisting of just a name such as "admin", "user", "customer", etc. They can be granted either to users (or in some cases to other roles), and are used to create logical groups of users for the convenient assignment of specific application privileges.

#### 16.6.1.2. What is a permission?

A permission 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. They are slightly more complex in structure than roles, essentially consisting of three "aspects"; a target, an action, and a recipient. The target of a permission is the object (or an arbitrary name or class) for which a particular action is allowed to be performed by a specific recipient (or user). For example, the user "Bob" may have permission to delete customer objects. In this case, the permission target may be "customer", the permission action would be "delete" and the recipient would be "Bob".

Within this documentation, permissions are generally represented in the form `target:action` (omitting the recipient, although in reality one is always required).

### 16.6.2. Securing components

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

## @Restrict vs Typesafe security annotations

While using the `@Restrict` annotation provides a powerful and flexible method for security component methods due to its ability to support EL expressions, it is recommended that the typesafe equivalent (described later) be used, at least for the compile-time safety it provides.

#### 16.6.2.1. The @Restrict annotation

Seam components may be secured either at the method or the class level, using the `@Restrict` annotation. If both a method and it's declaring class are annotated with `@Restrict`, the method restriction will take precedence (and the class restriction will not apply). If a method invocation fails a security check, then an exception will be thrown as per the contract for `Identity.checkRestriction()` (see Inline Restrictions). A `@Restrict` on just the component class itself is equivalent to adding `@Restrict` to each of its methods.

An empty `@Restrict` implies a permission check of `componentName:methodName`. Take for example the following component method:

    @Name("account")

    public class AccountAction {

        @Restrict public void delete() {

          ...

        }

    }

In this example, the implied permission required to call the `delete()` method is `account:delete`. The equivalent of this would be to write `@Restrict("#{s:hasPermission('account','delete')}")`. Now let's look at another example:

    @Restrict @Name("account")

    public class AccountAction {

        public void insert() {

          ...

        }

        @Restrict("#{s:hasRole('admin')}")

        public void delete() {

          ...

        }

    }

This time, the component class itself is annotated with `@Restrict`. This means that any methods without an overriding `@Restrict` annotation require an implicit permission check. In the case of this example, the `insert()` method requires a permission of `account:insert`, while the `delete()` method requires that the user is a member of the `admin` role.

Before we go any further, let's address the `#{s:hasRole()}` expression seen in the above example. Both `s:hasRole` and `s:hasPermission` are EL functions, which delegate to the correspondingly named methods of the `Identity` class. These functions can be used within any EL expression throughout the entirety of the security API.

Being an EL expression, the value of the `@Restrict` annotation may reference any objects that exist within a Seam context. This is extremely useful when performing permission checks for a specific object instance. Look at this example:

    @Name("account")

    public class AccountAction {

        @In Account selectedAccount;

        @Restrict("#{s:hasPermission(selectedAccount,'modify')}")

        public void modify() {

            selectedAccount.modify();

        }

    }

The interesting thing to note from this example is the reference to `selectedAccount` seen within the `hasPermission()` function call. The value of this variable will be looked up from within the Seam context, and passed to the `hasPermission()` method in `Identity`, which in this case can then determine if the user has the required permission for modifying the specified `Account` object.

#### 16.6.2.2. Inline restrictions

Sometimes it might be desirable to perform a security check in code, without using the `@Restrict` annotation. In this situation, simply use `Identity.checkRestriction()` to evaluate a security expression, like this:

    public void deleteCustomer() {

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

    }

If the expression specified doesn't evaluate to `true`, either

- if the user is not logged in, a `NotLoggedInException` exception is thrown or

- if the user is logged in, an `AuthorizationException` exception is thrown.

It is also possible to call the `hasRole()` and `hasPermission()` methods directly from Java code:

    if (!Identity.instance().hasRole("admin"))

         throw new AuthorizationException("Must be admin to perform this action");

    if (!Identity.instance().hasPermission("customer", "create"))

         throw new AuthorizationException("You may not create new customers");

### 16.6.3. Security in the user interface

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(cl,'modify')}"/>

            <s:link value="Delete Client" action="#{clientAction.delete}"

                    rendered="#{s:hasPermission(cl,'delete')}"/>

        </h:column>

    </h:dataTable>

### 16.6.4. Securing pages

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. If no explicit restriction is specified by the `restrict` element, an implied permission of `/viewId.xhtml:render` will be checked when the page is accessed via a non-faces (GET) request, and a permission of `/viewId.xhtml:restore` will be required when any JSF postback (form submission) originates from the page. Otherwise, the specified restriction will be evaluated as a standard security expression. Here's a couple of examples:

    <page view-id="/settings.xhtml">

        <restrict/>

    </page>

This page has an implied permission of `/settings.xhtml:render` required for non-faces requests and an implied permission of `/settings.xhtml:restore` for faces requests.

    <page view-id="/reports.xhtml">

        <restrict>#{s:hasRole('admin')}</restrict>

    </page>

Both faces and non-faces requests to this page require that the user is a member of the `admin` role.

### 16.6.5. Securing Entities

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 `entity:action`, where the permission target is the entity instance, 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 relevant entity lifecycle method (annotated as follows):

- `@PostLoad` - Called after an entity instance is loaded from the database. Use this method to configure a `read` permission.

- `@PrePersist` - Called before a new instance of the entity is inserted. Use this method to configure an `insert` permission.

- `@PreUpdate` - Called before an entity is updated. Use this method to configure an `update` permission.

- `@PreRemove` - Called before an entity is deleted. Use this method to configure a `delete` permission.

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() {}

## Using /META-INF/orm.xml

You can also specify the call back method in `/META-INF/orm.xml`:

    <?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">

       <entity class="Customer">

          <pre-persist method-name="prePersist" />

       </entity>

    </entity-mappings>

Of course, you still need to annotate the `prePersist()` method on `Customer` with `@Restrict`

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 inserted into the working memory (in this case `MemberBlog`):

    rule InsertMemberBlog
      no-loop
      activation-group "permissions"
    when
      principal: Principal()
      memberBlog: MemberBlog(member : member -> (member.getUsername().equals(principal.getName())))
      check: PermissionCheck(target == memberBlog, action == "insert", granted == false)
    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 "`principal: Principal()`" structure that can be seen in the example code is a variable binding - it binds the instance of the `Principal` object from the working memory (placed there during authentication) and assigns it to a variable called `principal`. 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.

#### 16.6.5.1. Entity security with JPA

Security checks for EJB3 entity beans are performed with an `EntityListener`. You can install this listener by using the following `META-INF/orm.xml` file:

    <?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>

#### 16.6.5.2. Entity security with a Managed Hibernate Session

If you are using a Hibernate `SessionFactory` configured via Seam, and are using annotations, or `orm.xml`, then you don't need to do anything special to use entity security.

### 16.6.6. Typesafe Permission Annotations

Seam provides a number of annotations that may be used as an alternative to `@Restrict`, which have the added advantage of providing compile-time safety as they don't support arbitrary EL expressions in the same way that `@Restrict` does.

Out of the box, Seam comes with annotations for standard CRUD-based permissions, however it is a simple matter to add your own. The following annotations are provided in the `org.jboss.seam.annotations.security` package:

- @Insert

- @Read

- @Update

- @Delete

To use these annotations, simply place them on the method or parameter for which you wish to perform a security check. If placed on a method, then they should specify a target class for which the permission will be checked. Take the following example:

      @Insert(Customer.class)
      public void createCustomer() {
        ...
      }

In this example, a permission check will be performed for the user to ensure that they have the rights to create new `Customer` objects. The target of the permission check will be `Customer.class` (the actual `java.lang.Class` instance itself), and the action is the lower case representation of the annotation name, which in this example is `insert`.

It is also possible to annotate the parameters of a component method in the same way. If this is done, then it is not required to specify a permission target (as the parameter value itself will be the target of the permission check):

      public void updateCustomer(@Update Customer customer) {
        ...
      }

To create your own security annotation, you simply need to annotate it with `@PermissionCheck`, for example:

    @Target({METHOD, PARAMETER})

    @Documented

    @Retention(RUNTIME)

    @Inherited

    @PermissionCheck

    public @interface Promote {

       Class value() default void.class;

    }

If you wish to override the default permission action name (which is the lower case version of the annotation name) with another value, you can specify it within the `@PermissionCheck` annotation:

    @PermissionCheck("upgrade")

### 16.6.7. Typesafe Role Annotations

In addition to supporting typesafe permission annotation, Seam Security also provides typesafe role annotations that allow you to restrict access to component methods based on the role memberships of the currently authenticated user. Seam provides one such annotation out of the box, `org.jboss.seam.annotations.security.Admin`, used to restrict access to a method to users that are a member of the `admin` role (so long as your own application supports such a role). To create your own role annotations, simply meta-annotate them with `org.jboss.seam.annotations.security.RoleCheck`, like in the following example:

    @Target({METHOD})
    @Documented
    @Retention(RUNTIME)
    @Inherited
    @RoleCheck
    public @interface User {
    }

Any methods subsequently annotated with the `@User` annotation as shown in the above example will be automatically intercepted and the user checked for the membership of the corresponding role name (which is the lower case version of the annotation name, in this case `user`).

### 16.6.8. The Permission Authorization Model

Seam Security provides an extensible framework for resolving application permissions. The following class diagram shows an overview of the main components of the permission framework:

The relevant classes are explained in more detail in the following sections.

#### 16.6.8.1. PermissionResolver

This is actually an interface, which provides methods for resolving individual object permissions. Seam provides the following built-in `PermissionResolver` implementations, which are described in more detail later in the chapter:

- `RuleBasedPermissionResolver` - This permission resolver uses Drools to resolve rule-based permission checks.

- `PersistentPermissionResolver` - This permission resolver stores object permissions in a persistent store, such as a relational database.

##### 16.6.8.1.1. Writing your own PermissionResolver

It is very simple to implement your own permission resolver. The `PermissionResolver` interface defines only two methods that must be implemented, as shown by the following table. By deploying your own `PermissionResolver` implementation in your Seam project, it will be automatically scanned during deployment and registered with the default `ResolverChain`.

Table 16.7. PermissionResolver interface

Return type | Method | Description
--- | --- | ---
`boolean` | `hasPermission(Object target, String action)` | This method must resolve whether the currently authenticated user (obtained via a call to `Identity.getPrincipal()`) has the permission specified by the `target` and `action` parameters. It should return `true` if the user has the permission, or `false` if they don't.
`void` | `filterSetByAction(Set<Object> targets, String action)` | This method should remove any objects from the specified set, that would return `true` if passed to the `hasPermission()` method with the same `action` parameter value.

## Note

As they are cached in the user's session, any custom `PermissionResolver` implementations must adhere to a couple of restrictions. Firstly, they may not contain any state that is finer-grained than session scope (and the scope of the component itself should either be application or session). Secondly, they must not use dependency injection as they may be accessed from multiple threads simultaneously. In fact, for performance reasons it is recommended that they are annotated with `@BypassInterceptors` to bypass Seam's interceptor stack altogether.

#### 16.6.8.2. ResolverChain

A `ResolverChain` contains an ordered list of `PermissionResolver`s, for the purpose of resolving object permissions for a particular object class or permission target.

The default `ResolverChain` consists of all permission resolvers discovered during application deployment. The `org.jboss.seam.security.defaultResolverChainCreated` event is raised (and the `ResolverChain` instance passed as an event parameter) when the default `ResolverChain` is created. This allows additional resolvers that for some reason were not discovered during deployment to be added, or for resolvers that are in the chain to be re-ordered or removed.

The following sequence diagram shows the interaction between the components of the permission framework during a permission check (explanation follows). A permission check can originate from a number of possible sources, for example - the security interceptor, the `s:hasPermission` EL function, or via an API call to `Identity.checkPermission`:

- 1. A permission check is initiated somewhere (either in code or via an EL expression) resulting in a call to `Identity.hasPermission()`.

- 1.1. `Identity` invokes `PermissionMapper.resolvePermission()`, passing in the permission to be resolved.

- 1.1.1. `PermissionMapper` maintains a `Map` of `ResolverChain` instances, keyed by class. It uses this map to locate the correct `ResolverChain` for the permission's target object. Once it has the correct `ResolverChain`, it retrieves the list of `PermissionResolver`s it contains via a call to `ResolverChain.getResolvers()`.

- 1.1.2. For each `PermissionResolver` in the `ResolverChain`, the `PermissionMapper` invokes its `hasPermission()` method, passing in the permission instance to be checked. If any of the `PermissionResolver`s return `true`, then the permission check has succeeded and the `PermissionMapper` also returns `true` to `Identity`. If none of the `PermissionResolver`s return true, then the permission check has failed.

### 16.6.9. RuleBasedPermissionResolver

One of the built-in permission resolvers provided by Seam, `RuleBasedPermissionResolver` allows permissions to be evaluated based on a set of Drools (JBoss Rules) security rules. A couple of the advantages of using a rule engine are 1) a centralized location for the business logic that is used to evaluate user permissions, and 2) speed - Drools uses very efficient algorithms for evaluating large numbers of complex rules involving multiple conditions.

#### 16.6.9.1. Requirements

If using the rule-based permission features provided by Seam Security, the following jar files are required by Drools to be distributed with your project:

- knowledge-api.jar

- drools-compiler.jar

- drools-core.jar

- drools-decisiontables.jar

- drools-templates.jar

- janino.jar

- antlr-runtime.jar

- mvel2.jar

#### 16.6.9.2. Configuration

The configuration for `RuleBasedPermissionResolver` requires that a Drools rule base is first configured in `components.xml`. By default, it expects that the rule base is named `securityRules`, as per the following example:

    <components xmlns="http://jboss.org/schema/seam/components"

                  xmlns:core="http://jboss.org/schema/seam/core"

                  xmlns:security="http://jboss.org/schema/seam/security"

                  xmlns:drools="http://jboss.org/schema/seam/drools"

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

                  xsi:schemaLocation=

                      "http://jboss.org/schema/seam/core http://jboss.org/schema/seam/core-2.3.xsd

                       http://jboss.org/schema/seam/components http://jboss.org/schema/seam/components-2.3.xsd

                       http://jboss.org/schema/seam/drools http://jboss.org/schema/seam/drools-2.3.xsd

                       http://jboss.org/schema/seam/security http://jboss.org/schema/seam/security-2.3.xsd">

         <drools:rule-base name="securityRules">

             <drools:rule-files>

                 <value>/META-INF/security.drl</value>

             </drools:rule-files>

         </drools:rule-base>

      </components>

The default rule base name can be overridden by specifying the `security-rules` property for `RuleBasedPermissionResolver`:

      <security:rule-based-permission-resolver security-rules="#{prodSecurityRules}"/>

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

#### 16.6.9.3. Writing Security Rules

The first step to writing security rules is to create a new rule file in the `/META-INF` directory of your application's jar file. Usually this file would be named something like `security.drl`, however you can name it whatever you like as long as it is configured correspondingly 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 Drools documentation, however to get started here's an extremely simple example:

    package MyApplicationPermissions;

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

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

Let's break this down step by step. The first thing we see is the package declaration. A package in Drools 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(target == "customer", action == "delete")

In plain english, this condition is stating that there must exist a `PermissionCheck` object with a `target` property equal to "customer", and an `action` property equal to "delete" within the working memory.

So what is the working memory? Also known as a "stateful session" in Drools terminology, the working memory 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 inserted into the working memory. This `PermissionCheck` corresponds exactly to the permission that is being checked, so for example if you call `hasPermission("account", "create")` then a `PermissionCheck` object with a `target` equal to "account" and `action` equal to "create" will be inserted into the working memory for the duration of the permission check.

Besides the `PermissionCheck` facts, there is also a `org.jboss.seam.security.Role` fact for each of the roles that the authenticated user is a member of. These `Role` facts are synchronized with the user's authenticated roles at the beginning of every permission check. As a consequence, any `Role` object that is inserted into the working memory during the course of a permission check will be removed before the next permission check occurs, if the authenticated user is not actually a member of that role. Besides the `PermissionCheck` and `Role` facts, the working memory also contains the `java.security.Principal` object that was created as a result of the authentication process.

It is also possible to insert additional long-lived facts into the working memory by calling `RuleBasedPermissionResolver.instance().getSecurityContext().insert()`, passing the object as a parameter. The exception to this is `Role` objects, which as already discussed are synchronized at the start of each permission check.

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 (in this case, the `PermissionCheck`). Moving on to 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 already mentioned, user roles are inserted into the working memory at the beginning of each permission check. 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.

#### 16.6.9.4. Non-String permission targets

So far we have only seen permission checks for String-literal permission targets. It is of course also possible to write security rules for permission targets of more complex types. For example, let's say that you wish to write a security rule to allow your users to create blog comments. The following rule demonstrates how this may be expressed, by requiring the target of the permission check to be an instance of `MemberBlog`, and also requiring that the currently authenticated user is a member of the `user` role:

    rule CanCreateBlogComment
      no-loop
      activation-group "permissions"
    when
      blog: MemberBlog()
      check: PermissionCheck(target == blog, action == "create", granted == false)
      Role(name == "user")
    then
      check.grant();
    end

#### 16.6.9.5. Wildcard permission checks

It is possible to implement a wildcard permission check (which allows all actions for a given permission target), by omitting the `action` constraint for the `PermissionCheck` in your rule, like this:

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

This rule allows users with the `admin` role to perform any action for any `customer` permission check.

### 16.6.10. PersistentPermissionResolver

Another built-in permission resolver provided by Seam, `PersistentPermissionResolver` allows permissions to be loaded from persistent storage, such as a relational database. This permission resolver provides ACL style instance-based security, allowing for specific object permissions to be assigned to individual users and roles. It also allows for persistent, arbitrarily-named permission targets (not necessarily object/class based) to be assigned in the same way.

#### 16.6.10.1. Configuration

Before it can be used, `PersistentPermissionResolver` must be configured with a valid `PermissionStore` in `components.xml`. If not configured, it will attempt to use the default permission store, `JpaIdentityStore` (see section further down for details). To use a permission store other than the default, configure the `permission-store` property as follows:

      <security:persistent-permission-resolver permission-store="#{myCustomPermissionStore}"/>

#### 16.6.10.2. Permission Stores

A permission store is required for `PersistentPermissionResolver` to connect to the backend storage where permissions are persisted. Seam provides one `PermissionStore` implementation out of the box, `JpaPermissionStore`, which is used to store permissions inside a relational database. It is possible to write your own permission store by implementing the `PermissionStore` interface, which defines the following methods:

Table 16.8. PermissionStore interface

Return type | Method | Description
--- | --- | ---
`List<Permission>` | `listPermissions(Object target)` | This method should return a `List` of `Permission` objects representing all the permissions granted for the specified target object.
`List<Permission>` | `listPermissions(Object target, String action)` | This method should return a `List` of `Permission` objects representing all the permissions with the specified action, granted for the specified target object.
`List<Permission>` | `listPermissions(Set<Object> targets, String action)` | This method should return a `List` of `Permission` objects representing all the permissions with the specified action, granted for the specified set of target objects.
`boolean` | `grantPermission(Permission)` | This method should persist the specified `Permission` object to the backend storage, returning true if successful.
`boolean` | `grantPermissions(List<Permission> permissions)` | This method should persist all of the `Permission` objects contained in the specified `List`, returning true if successful.
`boolean` | `revokePermission(Permission permission)` | This method should remove the specified `Permission` object from persistent storage.
`boolean` | `revokePermissions(List<Permission> permissions)` | This method should remove all of the `Permission` objects in the specified list from persistent storage.
`List<String>` | `listAvailableActions(Object target)` | This method should return a list of all the available actions (as Strings) for the class of the specified target object. It is used in conjunction with permission management to build the user interface for granting specific class permissions (see section further down).

#### 16.6.10.3. JpaPermissionStore

This is the default `PermissionStore` implementation (and the only one provided by Seam), which uses a relational database to store permissions. Before it can be used it must be configured with either one or two entity classes for storing user and role permissions. These entity classes must be annotated with a special set of security annotations to configure which properties of the entity correspond to various aspects of the permissions being stored.

If you wish to use the same entity (i.e. a single database table) to store both user and role permissions, then only the `user-permission-class` property is required to be configured. If you wish to use separate tables for storing user and role permissions, then in addition to the `user-permission-class` property you must also configure the `role-permission-class` property.

For example, to configure a single entity class to store both user and role permissions:

    <security:jpa-permission-store user-permission-class="com.acme.model.AccountPermission" />

To configure separate entity classes for storing user and role permissions:

    <security:jpa-permission-store user-permission-class="com.acme.model.UserPermission"

        role-permission-class="com.acme.model.RolePermission" />

##### 16.6.10.3.1. Permission annotations

As mentioned, the entity classes that contain the user and role permissions must be configured with a special set of annotations, contained within the `org.jboss.seam.annotations.security.permission` package. The following table lists each of these annotations along with a description of how they are used:

Table 16.9. Entity Permission annotations

Annotation | Target | Description
--- | --- | ---
`@PermissionTarget` | `FIELD,METHOD` | This annotation identifies the property of the entity that will contain the permission target. The property should be of type `java.lang.String`.
`@PermissionAction` | `FIELD,METHOD` | This annotation identifies the property of the entity that will contain the permission action. The property should be of type `java.lang.String`.
`@PermissionUser` | `FIELD,METHOD` | This annotation identifies the property of the entity that will contain the recipient user for the permission. It should be of type `java.lang.String` and contain the user's username.
`@PermissionRole` | `FIELD,METHOD` | This annotation identifies the property of the entity that will contain the recipient role for the permission. It should be of type `java.lang.String` and contain the role name.
`@PermissionDiscriminator` | `FIELD,METHOD` | This annotation should be used when the same entity/table is used to store both user and role permissions. It identifies the property of the entity that is used to discriminate between user and role permissions. By default, if the column value contains the string literal `user`, then the record will be treated as a user permission. If it contains the string literal `role`, then it will be treated as a role permission. It is also possible to override these defaults by specifying the `userValue` and `roleValue` properties within the annotation. For example, to use `u` and `r` instead of `user` and `role`, the annotation would be written like this:
    @PermissionDiscriminator

    (userValue="u", roleValue="r")

##### 16.6.10.3.2. Example Entity

Here is an example of an entity class that is used to store both user and role permissions. The following class can be found inside the SeamSpace example:

    @Entity

    public class AccountPermission implements Serializable {

       private Integer permissionId;

       private String recipient;

       private String target;

       private String action;

       private String discriminator;

       @Id @GeneratedValue

       public Integer getPermissionId() {

          return permissionId;

       }

       public void setPermissionId(Integer permissionId) {

          this.permissionId = permissionId;

       }

       @PermissionUser @PermissionRole

       public String getRecipient() {

          return recipient;

       }

       public void setRecipient(String recipient) {

          this.recipient = recipient;

       }

       @PermissionTarget

       public String getTarget() {

          return target;

       }

       public void setTarget(String target) {

          this.target = target;

       }

       @PermissionAction

       public String getAction() {

          return action;

       }

       public void setAction(String action) {

          this.action = action;

       }

       @PermissionDiscriminator

       public String getDiscriminator() {

          return discriminator;

       }

       public void setDiscriminator(String discriminator) {

          this.discriminator = discriminator;

       }

    }

As can be seen in the above example, the `getDiscriminator()` method has been annotated with the `@PermissionDiscriminator` annotation, to allow `JpaPermissionStore` to determine which records represent user permissions and which represent role permissions. In addition, it can also be seen that the `getRecipient()` method is annotated with both `@PermissionUser` and `@PermissionRole` annotations. This is perfectly valid, and simply means that the `recipient` property of the entity will either contain the name of the user or the name of the role, depending on the value of the `discriminator` property.

##### 16.6.10.3.3. Class-specific Permission Configuration

A further set of class-specific annotations can be used to configure a specific set of allowable permissions for a target class. These permissions can be found in the `org.jboss.seam.annotation.security.permission` package:

Table 16.10. Class Permission Annotations

Annotation | Target | Description
--- | --- | ---
`@Permissions` | `TYPE` | A container annotation, this annotation may contain an array of `@Permission` annotations.
`@Permission` | `TYPE` | This annotation defines a single allowable permission action for the target class. Its `action` property must be specified, and an optional `mask` property may also be specified if permission actions are to be persisted as bitmasked values (see next section).

Here's an example of the above annotations in action. The following class can also be found in the SeamSpace example:

    @Permissions({

       @Permission(action = "view"),

       @Permission(action = "comment")

    })

    @Entity

    public class MemberImage implements Serializable {

This example demonstrates how two allowable permission actions, `view` and `comment` can be declared for the entity class `MemberImage`.

##### 16.6.10.3.4. Permission masks

By default, multiple permissions for the same target object and recipient will be persisted as a single database record, with the `action` property/column containing a comma-separated list of the granted actions. To reduce the amount of physical storage required to persist a large number of permissions, it is possible to use a bitmasked integer value (instead of a comma-separated list) to store the list of permission actions.

For example, if recipient "Bob" is granted both the `view` and `comment` permissions for a particular `MemberImage` (an entity bean) instance, then by default the `action` property of the permission entity will contain "`view,comment`", representing the two granted permission actions. Alternatively, if using bitmasked values for the permission actions, as defined like so:

    @Permissions({

       @Permission(action = "view", mask = 1),

       @Permission(action = "comment", mask = 2)

    })

    @Entity

    public class MemberImage implements Serializable {

The `action` property will instead simply contain "3" (with both the 1 bit and 2 bit switched on). Obviously for a large number of allowable actions for any particular target class, the storage required for the permission records is greatly reduced by using bitmasked actions.

Obviously, it is very important that the `mask` values specified are powers of 2.

##### 16.6.10.3.5. Identifier Policy

When storing or looking up permissions, `JpaPermissionStore` must be able to uniquely identify specific object instances to effectively operate on its permissions. To achieve this, an identifier strategy may be assigned to each target class for the generation of unique identifier values. Each identifier strategy implementation knows how to generate unique identifiers for a particular type of class, and it is a simple matter to create new identifier strategies.

The `IdentifierStrategy` interface is very simple, declaring only two methods:

    public interface IdentifierStrategy {

       boolean canIdentify(Class targetClass);

       String getIdentifier(Object target);

    }

The first method, `canIdentify()` simply returns `true` if the identifier strategy is capable of generating a unique identifier for the specified target class. The second method, `getIdentifier()` returns the unique identifier value for the specified target object.

Seam provides two `IdentifierStrategy` implementations, `ClassIdentifierStrategy` and `EntityIdentifierStrategy` (see next sections for details).

To explicitly configure a specific identifier strategy to use for a particular class, it should be annotated with `org.jboss.seam.annotations.security.permission.Identifier`, and the value should be set to a concrete implementation of the `IdentifierStrategy` interface. An optional `name` property can also be specified, the effect of which is dependent upon the actual `IdentifierStrategy` implementation used.

##### 16.6.10.3.6. ClassIdentifierStrategy

This identifier strategy is used to generate unique identifiers for classes, and will use the value of the `name` (if specified) in the `@Identifier` annotation. If there is no `name` property provided, then it will attempt to use the component name of the class (if the class is a Seam component), or as a last resort it will create an identifier based on the name of the class (excluding the package name). For example, the identifier for the following class will be "`customer`":

    @Identifier(name = "customer")

    public class Customer {

The identifier for the following class will be "`customerAction`":

    @Name("customerAction")

    public class CustomerAction {

Finally, the identifier for the following class will be "`Customer`":

    public class Customer {

##### 16.6.10.3.7. EntityIdentifierStrategy

This identifier strategy is used to generate unique identifiers for entity beans. It does so by concatenating the entity name (or otherwise configured name) with a string representation of the primary key value of the entity. The rules for generating the name section of the identifier are similar to `ClassIdentifierStrategy`. The primary key value (i.e. the id of the entity) is obtained using the `PersistenceProvider` component, which is able to correctly determine the value regardless of which persistence implementation is used within the Seam application. For entities not annotated with `@Entity`, it is necessary to explicitly configure the identifier strategy on the entity class itself, for example:

    @Identifier(value = EntityIdentifierStrategy.class)

    public class Customer {

For an example of the type of identifier values generated, assume we have the following entity class:

    @Entity

    public class Customer {

      private Integer id;

      private String firstName;

      private String lastName;

      @Id

      public Integer getId() { return id; }

      public void setId(Integer id) { this.id = id; }

      public String getFirstName() { return firstName; }

      public void setFirstName(String firstName) { this.firstName = firstName; }

      public String getLastName() { return lastName; }

      public void setLastName(String lastName) { this.lastName = lastName; }

    }

For a `Customer` instance with an `id` value of `1`, the value of the identifier would be "`Customer:1`". If the entity class is annotated with an explicit identifier name, like so:

    @Entity

    @Identifier(name = "cust")

    public class Customer {

Then a `Customer` with an `id` value of `123` would have an identifier value of "`cust:123`".

## 16.7. Permission Management

In much the same way that Seam Security provides an Identity Management API for the management of users and roles, it also provides a Permissions Management API for the management of persistent user permissions, via the `PermissionManager` component.

### 16.7.1. PermissionManager

The `PermissionManager` component is an application-scoped Seam component that provides a number of methods for managing permissions. Before it can be used, it must be configured with a permission store (although by default it will attempt to use `JpaPermissionStore` if it is available). To explicitly configure a custom permission store, specify the `permission-store` property in components.xml:

    <security:permission-manager permission-store="#{ldapPermissionStore}"/>

The following table describes each of the available methods provided by `PermissionManager`:

Table 16.11. PermissionManager API methods

Return type | Method | Description
--- | --- | ---
`List<Permission>` | `listPermissions(Object target, String action)` | Returns a list of `Permission` objects representing all of the permissions that have been granted for the specified target and action.
`List<Permission>` | `listPermissions(Object target)` | Returns a list of `Permission` objects representing all of the permissions that have been granted for the specified target and action.
`boolean` | `grantPermission(Permission permission)` | Persists (grants) the specified `Permission` to the backend permission store. Returns true if the operation was successful.
`boolean` | `grantPermissions(List<Permission> permissions)` | Persists (grants) the specified list of `Permission`s to the backend permission store. Returns true if the operation was successful.
`boolean` | `revokePermission(Permission permission)` | Removes (revokes) the specified `Permission` from the backend permission store. Returns true if the operation was successful.
`boolean` | `revokePermissions(List<Permission> permissions)` | Removes (revokes) the specified list of `Permission`s from the backend permission store. Returns true if the operation was successful.
`List<String>` | `listAvailableActions(Object target)` | Returns a list of the available actions for the specified target object. The actions that this method returns are dependent on the `@Permission` annotations configured on the target object's class.

### 16.7.2. Permission checks for PermissionManager operations

Invoking the methods of `PermissionManager` requires that the currently-authenticated user has the appropriate authorization to perform that management operation. The following table lists the required permissions that the current user must have.

Table 16.12. Permission Management Security Permissions

Method | Permission Target | Permission Action
--- | --- | ---
`listPermissions()` | The specified `target` | `seam.read-permissions`
`grantPermission()` | The target of the specified `Permission`, or each of the targets for the specified list of `Permission`s (depending on which method is called). | `seam.grant-permission`
`grantPermission()` | The target of the specified `Permission`. | `seam.grant-permission`
`grantPermissions()` | Each of the targets of the specified list of `Permission`s. | `seam.grant-permission`
`revokePermission()` | The target of the specified `Permission`. | `seam.revoke-permission`
`revokePermissions()` | Each of the targets of the specified list of `Permission`s. | `seam.revoke-permission`

## 16.8. SSL Security

Seam includes basic support for serving sensitive pages via the HTTPS protocol. This is easily configured by specifying a `scheme` for the page in `pages.xml`. The following example shows how the view `/login.xhtml` is configured to use HTTPS:

    <page view-id="/login.xhtml" scheme="https"/>

This configuration is automatically extended to both `s:link` and `s:button` JSF controls, which (when specifying the `view`) will also render the link using the correct protocol. Based on the previous example, the following link will use the HTTPS protocol because `/login.xhtml` is configured to use it:

    <s:link view="/login.xhtml" value="Login"/>

Browsing directly to a view when using the incorrect protocol will cause a redirect to the same view using the correct protocol. For example, browsing to a page that has `scheme="https"` using HTTP will cause a redirect to the same page using HTTPS.

It is also possible to configure a default scheme for all pages. This is useful if you wish to use HTTPS for a only few pages. If no default scheme is specified then the normal behavior is to continue use the current scheme. So once the user accessed a page that required HTTPS, then HTTPS would continue to be used after the user navigated away to other non-HTTPS pages. (While this is good for security, it is not so great for performance!). To define HTTP as the default `scheme`, add this line to `pages.xml`:

    <page view-id="*" scheme="http" />

Of course, if none of the pages in your application use HTTPS then it is not required to specify a default scheme.

You may configure Seam to automatically invalidate the current HTTP session each time the scheme changes. Just add this line to `components.xml`:

    <web:session invalidate-on-scheme-change="true"/>

This option helps make your system less vulnerable to sniffing of the session id or leakage of sensitive data from pages using HTTPS to other pages using HTTP.

### 16.8.1. Overriding the default ports

If you wish to configure the HTTP and HTTPS ports manually, they may be configured in `pages.xml` by specifying the `http-port` and `https-port` attributes on the `pages` element:

    <pages xmlns="http://jboss.org/schema/seam/pages"

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

           xsi:schemaLocation="http://jboss.org/schema/seam/pages http://jboss.org/schema/seam/pages-2.3.xsd"

           no-conversation-view-id="/home.xhtml"

           login-view-id="/login.xhtml"

           http-port="8080"

           https-port="8443">

## 16.9. CAPTCHA

Though strictly not part of the security API, Seam provides a built-in CAPTCHA (Completely Automated Public Turing test to tell Computers and Humans Apart) algorithm to prevent automated processes from interacting with your application.

### 16.9.1. Configuring the CAPTCHA Servlet

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.SeamResourceServlet</servlet-class>

    </servlet>

    <servlet-mapping>

        <servlet-name>Seam Resource Servlet</servlet-name>

        <url-pattern>/seam/resource/*</url-pattern>

    </servlet-mapping>

### 16.9.2. Adding a CAPTCHA to a form

Adding a CAPTCHA challenge to a form is extremely easy. Here's an example:

    <h:graphicImage value="/seam/resource/captcha"/>

    <h:inputText id="verifyCaptcha" value="#{captcha.response}" required="true">

       <s:validate />

    </h:inputText>

    <h:message for="verifyCaptcha"/>

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.

### 16.9.3. Customising the CAPTCHA algorithm

You may customize the CAPTCHA algorithm by overriding the built-in component:

    @Name("org.jboss.seam.captcha.captcha")

    @Scope(SESSION)

    public class HitchhikersCaptcha extends Captcha

    {

       @Override @Create

       public void init()

       {

          setChallenge("What is the answer to life, the universe and everything?");

          setCorrectResponse("42");

       }

       @Override

       public BufferedImage renderChallenge()

       {

           BufferedImage img = super.renderChallenge();

           img.getGraphics().drawOval(5, 3, 60, 14); //add an obscuring decoration

           return img;

       }

    }

## 16.10. Security Events

The following table describes a number of events (see Chapter 7, Events, interceptors and exception handling) raised by Seam Security in response to certain security-related events.

Table 16.13. Security Events

Event Key | Description
--- | ---
`org.jboss.seam.security.loginSuccessful` | Raised when a login attempt is successful.
`org.jboss.seam.security.loginFailed` | Raised when a login attempt fails.
`org.jboss.seam.security.alreadyLoggedIn` | Raised when a user that is already authenticated attempts to log in again.
`org.jboss.seam.security.notLoggedIn` | Raised when a security check fails when the user is not logged in.
`org.jboss.seam.security.notAuthorized` | Raised when a security check fails when the user is logged in however doesn't have sufficient privileges.
`org.jboss.seam.security.preAuthenticate` | Raised just prior to user authentication.
`org.jboss.seam.security.postAuthenticate` | Raised just after user authentication.
`org.jboss.seam.security.loggedOut` | Raised after the user has logged out.
`org.jboss.seam.security.credentialsUpdated` | Raised when the user's credentials have been changed.
`org.jboss.seam.security.rememberMe` | Raised when the Identity's rememberMe property is changed.

## 16.11. Run As

Sometimes it may be necessary to perform certain operations with elevated privileges, such as creating a new user account as an unauthenticated user. Seam Security supports such a mechanism via the `RunAsOperation` class. This class allows either the `Principal` or `Subject`, or the user's roles to be overridden for a single set of operations.

The following code example demonstrates how `RunAsOperation` is used, by calling its `addRole()` method to provide a set of roles to masquerade as for the duration of the operation. The `execute()` method contains the code that will be executed with the elevated privileges.

        new RunAsOperation() {

           public void execute() {

              executePrivilegedOperation();

           }

        }.addRole("admin")

         .run();

In a similar way, the `getPrincipal()` or `getSubject()` methods can also be overriden to specify the `Principal` and `Subject` instances to use for the duration of the operation. Finally, the `run()` method is used to carry out the `RunAsOperation`.

## 16.12. Extending the Identity component

Sometimes it might be necessary to extend the Identity component if your application has special security requirements. The following example (contrived, as credentials would normally be handled by the `Credentials` component instead) shows an extended Identity component with an additional `companyCode` field. The install precedence of `APPLICATION` ensures that this extended Identity gets installed in preference to the built-in Identity.

    @Name("org.jboss.seam.security.identity")

    @Scope(SESSION)

    @Install(precedence = APPLICATION)

    @BypassInterceptors

    @Startup

    public class CustomIdentity extends Identity

    {

       private static final LogProvider log = Logging.getLogProvider(CustomIdentity.class);

       private String companyCode;

       public String getCompanyCode()

       {

          return companyCode;

       }

       public void setCompanyCode(String companyCode)

       {

          this.companyCode = companyCode;

       }

       @Override

       public String login()

       {

          log.info("###### CUSTOM LOGIN CALLED ######");

          return super.login();

       }

    }

## Warning

Note that an `Identity` component must be marked `@Startup`, so that it is available immediately after the `SESSION` context begins. Failing to do this may render certain Seam functionality inoperable in your application.

## 16.13. OpenID

OpenID is a community standard for external web-based authentication. The basic idea is that any web application can supplement (or replace) its local handling of authentication by delegating responsibility to an external OpenID server of the user's choose. This benefits the user, who no longer has to remember a name and password for every web application he uses, and the developer, who is relieved of some of the burden of maintaining a complex authentication system.

When using OpenID, the user selects an OpenID provider, and the provider assigns the user an OpenID. The id will take the form of a URL, for example `http://maximoburrito.myopenid.com` however, it's acceptable to leave off the `http://` part of the identifier when logging into a site. The web application (known as a relying party in OpenID-speak) determines which OpenID server to contact and redirects the user to the remote site for authentication. Upon successful authentication the user is given the (cryptographically secure) token proving his identity and is redirected back to the original web application.The local web application can then be sure the user accessing the application controls the OpenID he presented.

It's important to realize at this point that authentication does not imply authorization. The web application still needs to make a determination of how to use that information. The web application could treat the user as instantly logged in and give full access to the system or it could try and map the presented OpenID to a local user account, prompting the user to register if he hasn't already. The choice of how to handle the OpenID is left as a design decision for the local application.

### 16.13.1. Configuring OpenID

Seam uses the openid4java package and requires four additional JARs to make use of the Seam integration. These are: `htmlparser.jar`, `openid4java.jar`, `openxri-client.jar` and `openxri-syntax.jar`.

OpenID processing requires the use of the `OpenIdPhaseListener`, which should be added to your `faces-config.xml` file. The phase listener processes the callback from the OpenID provider, allowing re-entry into the local application.

    <lifecycle>

        <phase-listener>org.jboss.seam.security.openid.OpenIdPhaseListener</phase-listener>

    </lifecycle>

With this configuration, OpenID support is available to your application. The OpenID support component, `org.jboss.seam.security.openid.openid`, is installed automatically if the openid4java classes are on the classpath.

### 16.13.2. Presenting an OpenIdDLogin form

To initiate an OpenID login, you can present a simply form to the user asking for the user's OpenID. The `#{openid.id}` value accepts the user's OpenID and the `#{openid.login}` action initiates an authentication request.

    <h:form>

        <h:inputText value="#{openid.id}" />

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

    </h:form>

When the user submits the login form, he will be redirected to his OpenID provider. The user will eventually return to your application through the Seam pseudo-view `/openid.xhtml`, which is provided by the `OpenIdPhaseListener`. Your application can handle the OpenID response by means of a `pages.xml` navigation from that view, just as if the user had never left your application.

### 16.13.3. Logging in immediately

The simplest strategy is to simply login the user immediately. The following navigation rule shows how to handle this using the `#{openid.loginImmediately()}` action.

    <page view-id="/openid.xhtml">

        <navigation evaluate="#{openid.loginImmediately()}">

            <rule if-outcome="true">

                <redirect view-id="/main.xhtml">

                    <message>OpenID login successful...</message>

                </redirect>

            </rule>

            <rule if-outcome="false">

                <redirect view-id="/main.xhtml">

                    <message>OpenID login rejected...</message>

                </redirect>

            </rule>

        </navigation>

    </page>

This `loginImmediately()` action checks to see if the OpenID is valid. If it is valid, it adds an OpenIDPrincipal to the identity component, marks the user as logged in (i.e. `#{identity.loggedIn}` will be true) and returns true. If the OpenID was not validated, the method returns false, and the user re-enters the application un-authenticated. If the user's OpenID is valid, it will be accessible using the expression `#{openid.validatedId}` and `#{openid.valid}` will be true.

### 16.13.4. Deferring login

You may not want the user to be immediately logged in to your application. In that case, your navigation should check the `#{openid.valid}` property and redirect the user to a local registration or processing page. Actions you might take would be asking for more information and creating a local user account or presenting a captcha to avoid programmatic registrations. When you are done processing, if you want to log the user in, you can call the `loginImmediately` method, either through EL as shown previously or by directly interaction with the `org.jboss.seam.security.openid.OpenId` component. Of course, nothing prevents you from writing custom code to interact with the Seam identity component on your own for even more customized behaviour.

### 16.13.5. Logging out

Logging out (forgetting an OpenID association) is done by calling `#{openid.logout}`. If you are not using Seam security, you can call this method directly. If you are using Seam security, you should continue to use `#{identity.logout}` and install an event handler to capture the logout event, calling the OpenID logout method.

    <event type="org.jboss.seam.security.loggedOut">

        <action execute="#{openid.logout}" />

    </event>

It's important that you do not leave this out or the user will not be able to login again in the same session.

- PrevChapter 15. Seam and JBoss Rules
- Top of page
- Front page
- NextChapter 17. Internationalization, localization an...