Chapter 23. Security - JBoss Seam 1.1.1 正式版英文参考手册

The authentication component of the security API is based on JAAS, allowing authentication to be carried out against one or more configurable login modules. The security API provides a login module that delegates authentication to a Seam component, making it easy to authenticate a user using the application's domain objects.

This feature allows direct access to page resources to be controlled based on the set of roles granted to the requesting user. Using a servlet filter, each request to a protected resource is validated to ensure that the user has the necessary roles to access the resource.

The s:hasRole() and s:hasPermission() EL functions can be used within the pages of an application to control which parts of a page are rendered based on the security level of the user. On the model side, component classes and/or their methods can also be annotated with the very same EL expressions to restrict the execution of methods based on the current security context.

By integrating with JBoss Rules, the security API is able to make security decisions by evaluating a set of user-defined security rules defined at deployment time. This feature allows any security checks to carry out a decision-making process which can be as simple or as complex as required, while taking into account the state of any objects asserted into the security context for the check.

The next step is to configure roles. While this step is optional (it is possible for a user to belong to a role even if it is not configured here), it is necessary if either 1) explicit permissions are required by your application, or 2) roles require membership of other roles. Create a file called security-config.xml, which goes in the META-INF directory of the Seam application's jar file. Here's an example security-config.xml file with a few roles defined.

        
<security-config>

  <roles>
    <role name="admin">
      <memberships>superuser</memberships>

      <permissions>
        <permission name="user" action="create"/>
        <permission name="user" action="modify"/>
        <permission name="user" action="delete"/>
      </permissions>
    </role>

    <role name="superuser">
      <memberships>user</memberships>

      <permissions>
        <permission name="account" action="create"/>
        <permission name="account" action="delete"/>
      </permissions>
    </role>

    <role name="user">
      <permissions>
        <permission name="customer" action="create"/>
        <permission name="customer" action="delete"/>
      </permissions>
    </role>

    <role name="guest">

    </role>

  </roles>

</security-config>
        
      

In the above example, we can see that there are four distinct roles: admin, superuser, user and guest. Strictly speaking, the guest entry is redundant as it declares no permissions nor contains any memberships of other roles. What is most of interest here are the permissions and role memberships, which are explained in further detail as follows.

          
<security-config>
          
  <security-constraint>
    <web-resource-collection>
      <web-resource-name>Secure Page</web-resource-name>
      <url-pattern>/secure/*</url-pattern>
    </web-resource-collection>
    
    <auth-constraint>
      <role-name>admin</role-name>
    </auth-constraint>
  </security-constraint>          
  
</security-config>  
          
        

          
  <component class="org.jboss.seam.security.config.SecurityConfiguration">
    <property name="securityErrorPage">/security/generalSecurityError.seam</property>
  </component>
                 
        

The Seam security filter is a servlet filter that provides page security features. It is an optional component in that if your application does not require page security, then there is no requirement to install the security filter. To configure which pages are secure, see the previous section on page security. To configure the security filter, add the following entries to web.xml:

        
    <!-- Seam security filter -->
    
    <filter>
      <filter-name>Seam Security Filter</filter-name>
      <filter-class>org.jboss.seam.security.filter.SeamSecurityFilter</filter-class>
    </filter>
    
    <filter-mapping>
      <filter-name>Seam Security Filter</filter-name>
      <url-pattern>*.seam</url-pattern>
    </filter-mapping>        
        
      

This file also goes into the Seam application's META-INF directory. It contains all the rules that make up an application's authorization policy, and is described further down in the Authorization section.

One of the simplest ways to authenticate a user is to delegate the authentication to a Seam component. There is a special login module, SeamLoginModule that allows this. Configure this login module in security-config.xml, and in its authMethod option specify an EL method expression. By default the method that you specify should accept the parameters [java.lang.String, java.lang.String, java.util.Set], however this can be customised (see section further down). The third java.util.Set parameter is a set to which the authentication method should add any roles that the authenticating user is a member of. Here's a complete example:

        
@Name("authenticator")
public class AuthenticatorAction 
{
  @In(create=true)
    private EntityManager entityManager;

  public boolean authenticate(String username, String password, Set<String> roles) 
  {
    try
    {            
       User user = (User) entityManager.createQuery(
          "from User where username = :username and password = :password")
          .setParameter("username", username)
          .setParameter("password", password)
          .getSingleResult();
  
       for (UserRole r : user.getRoles())
          roles.add(r.getName());
       
       return true;
    }
    catch (NoResultException ex)
    {
       log.warn("Invalid username/password");
       return false;
    }      
  }   
}        
        
      

Based on the above example, the EL expression that would need to be specified in the authMethod option for the login module would be #{authenticator.authenticate}.

Now that the login module has been configured, and an authentication method written, all that is left is to perform a JAAS login. This is the easiest step, as shown by the following example:

        
   public void login()
   {
      try
      {
         CallbackHandler cbh = SeamSecurityManager.instance().createCallbackHandler(
               user.getUsername(), user.getPassword());
         
         LoginContext lc = SeamSecurityManager.instance().createLoginContext(null, cbh);
         lc.login();
      }
      catch (LoginException ex)
      {
         FacesMessages.instance().add("Invalid login");
      }
   }        
        
      

The first thing that happens in the above code is the creation of a CallbackHandler which is going to be responsible for providing the user's credentials (their username and password) to the login module. The CallbackHandler is created by a convenience method in SeamSecurityManager, and knows how to handle NameCallback and PasswordCallback callback types.

The next thing that happens is the creation of a LoginContext. There is a factory method in SeamSecurityManager for creating this, as the login context doesn't use the standard configuration (it uses an application-specific configuration). If the application policy isn't configured with a name, then it will have a default name and the String parameter passed to createLoginContext() can be null. If your application has multiple application policies configured, then you can specify which one to use by providing the policy name to createLoginContext():

        
  LoginContext lc = SeamSecurityManager.instance().createLoginContext("special", cbh);        
        
      

The final step is the call to lc.login(), which calls each of the configured login modules in turn, passing in the callback handler to each one and performing an authentication based on the configured login module flags.

Once the user is successfully authenticated, calls to Identity.loggedIn() will return true for the duration of the session.

In some situations it may be necessary to perform authentication that isn't based on a simple username/password combination. The good news is that this is not very difficult, however it requires a few additional steps. This section will walk through an example where authentication requires a Company ID in addition to a username and password.

The first step is to subclass the SeamLoginModule class and override the getLoginParams() method to return the appropriate parameters for the custom authentication method.

        
public class CustomLoginModule extends SeamLoginModule 
{           
   @Override public Object[] getLoginParams()
      throws Exception
   {
      CompanyCallback cbCompany = new CompanyCallback("Enter company ID");
      NameCallback cbName = new NameCallback("Enter username");
      PasswordCallback cbPassword = new PasswordCallback("Enter password", false);

      // Get the username and password from the callback handler
      callbackHandler.handle(new Callback[] { cbCompany, cbName, cbPassword });
      username = cbName.getName();
      
      return new Object[] { cbCompany.getCompanyId(), username, 
                            new String(cbPassword.getPassword()), roles };
   }        
}
        
      

Since CompanyCallback is a custom callback it needs to be created also:

        
public class CompanyCallback implements Callback, Serializable {
  private String prompt;
  private int companyId;
  public CompanyCallback(String prompt) {
    if (prompt == null || "".equals(prompt))
      throw new IllegalArgumentException();
    this.prompt = prompt;
  }        
  public String getPrompt() {
    return prompt;
  }
  public int getCompanyId() {
    return companyId;
  }
  public void setCompanyId(int companyId) {
    this.companyId = companyId;
  }
}  
        
      

So far so good, now it's time to configure the custom login module in security-config.xml:

        
  <loginmodules>
    <loginmodule class="com.acme.security.CustomLoginModule" flag="required">
      <option name="paramTypes">java.lang.Integer,java.lang.String,java.lang.String,java.util.Set</option>
      <option name="authMethod">#{authenticator.authenticate}</option>      
    </loginmodule>
  </loginmodules>         
        
      

The important thing to note above is that the paramTypes option is specified, based on the customised parameters that are going to be sent to the authentication method. Now that they have been configured, it is time to write the authentication method:

        
@Name("authenticator")       
public class CustomAuthenticator {
  @In(create=true)
  private EntityManager entityManager;

  public boolean authenticate(int companyId, String username, String password, Set<String> roles) 
  {
    try
    {            
       User user = (User) entityManager.createQuery(
          "from User where companyId = :companyId and username = :username and password = :password")
          .setParameter("companyId", companyId)
          .setParameter("username", username)
          .setParameter("password", password)          
          .getSingleResult();
  
       for (UserRole r : user.getRoles())
          roles.add(r.getName());
       
       return true;
    }
    catch (NoResultException ex)
    {
       log.warn("Invalid username/password");
       return false;
    }      
  }  
}
        
      

As can be seen in the above example, the customised authentication method contains the additional companyId parameter. The last thing to do is write a login method:

        
@Name("loginAction")
public class LoginAction implements LoginLocal {
   @In(create = true) EntityManager entityManager;
   @In(required = false) User user;

   public void login()
   {
      try
      {
         CallbackHandler cbh = createCallbackHandler(user.getCompanyId(), 
               user.getUsername(), user.getPassword());
         
         LoginContext lc = SeamSecurityManager.instance().createLoginContext(cbh);
         lc.login();
      }
      catch (LoginException ex)
      {
         FacesMessages.instance().add("Invalid login");
      }
   }  
        
   private CallbackHandler createCallbackHandler(final int companyId, 
         final String username, final String password)
   {
      return new CallbackHandler() {
         public void handle(Callback[] callbacks) 
            throws IOException, UnsupportedCallbackException 
         {
            for (int i = 0; i < callbacks.length; i++)
            {
               if (callbacks[i] instanceof CompanyCallback)
                  ((CompanyCallback) callbacks[i]).setCompanyId(companyId);
               else if (callbacks[i] instanceof NameCallback)
                  ((NameCallback) callbacks[i]).setName(username);
               else if (callbacks[i] instanceof PasswordCallback)
                  ((PasswordCallback) callbacks[i]).setPassword(password.toCharArray());
               else
                  throw new UnsupportedCallbackException(callbacks[i],
                        "Unsupported callback");
            }
            
         }
      };
   }        
        
      

The most significant thing to note in the above code is the createCallbackHandler() method. It returns a callback handler that knows how to handle a CompanyCallback, in addition to the standard NameCallback and PasswordCallback.

That wraps up the creation of a customised authentication process. Based on the above steps, it should be possible to create a customised authentication based on any combination of credentials.

The Seam security API provides two types of authorization checks; role checks and permission checks. Role checks are simple checks to determine if a user is a member of a specific role. They are equivalent in function to the isUserInRole() method found within the servlet specification. Role checks can be performed by using the s:hasRole() EL function. Here's a few examples of role checks.

This first example demonstrates how to restrict access to the Seam component secureAction to all users besides those in the admin role.

        
@Name("secureAction")
@Restrict("#{s:hasRole('admin')}")
public class SecureAction {
   // ...
}
        
      

This example demonstrates how to restrict access to a method of a Seam component to users in the superuser role.

        
  @Restrict("#{s:hasRole('superuser')}")
  public void secureMethod {
    // ...
  }
        
      

This last example shows how an inline security check can be performed within the body of a method, rather than using the @Restrict annotation.

        
  public String changeUserPassword() {
    // code here
    Identity.instance().checkRestriction("#{s:hasRole('superuser')}");    
    // code here
  }  
        
      

The first time that a permission check is performed after a user is authenticated, a security context is created for that user and placed into the user's session context. This security context (which in fact is an instance of org.drools.WorkingMemory) is populated with all of the Principals for the authenticated user, plus all of the explicitly granted permissions granted to the user's role/s, as instances oforg.jboss.seam.security.SeamPermission. To make this a little clearer, here's a diagram:

In this diagram, the database contains a user "bob", who is a member of the "user" role. The security configuration file, security-config.xml defines a role called "user" that has the explicitly assigned permissions customer:create, account:create and invoice:create. After bob authenticates, his Security Context will contain all of the permissions granted to him through his role memberships, as well as any Principals created as a result of the authentication process. This includes his roles, which exist in a SimpleGroup principal with the name of "roles".

As mentioned previously, permissions can either be explicitly granted, or they can be granted as the result of a rule-based decision. Strictly speaking though, all permissions must be granted via a security rule; this includes explicit permissions also. By having all permissioning under the control of the rule engine, it is easier to configure any custom security requirements for your application. So what does this mean? For starters, granting explicit permissions without specifying a minimal security policy will mean that any security checks for those permissions will fail. What does a minimal security policy look like? Here's an example security-rules.drl file with a default security policy defined:

        
package MyProjectPermissions;

import org.jboss.seam.security.Identity;
import org.jboss.seam.security.rules.PermissionCheck;
import org.jboss.seam.security.SeamPermission;        
        
rule DefaultPolicy
  salience -10
  activation-group "permissions"  
when
  c: PermissionCheck(granted == false)
  p: SeamPermission()
  eval( p.getName().equals(c.getName()) && p.getAction().equals(c.getAction()))
then
  c.grant();
end;        
        
      

If you're familiar with JBoss Rules then this example should make at least some sense already. In a nutshell, what this rule does is "catch" any permission checks that haven't already been granted by any higher priority rules, and grant the permission if a SeamPermission instance having the same name and action as the PermissionCheck exists within the security context.

A couple of notes about this rule; first of all, the salience -10 line means that this rule will have a lower priority than any other rules with a higher salience (the default salience if not specified is 0). This assigns rules for any dynamic permissions (that don't have an explicit SeamPermission in the security context) a higher firing priority. Secondly, the activation-group value means that once the first rule within the activation group fires, no other rules within the same activation group will fire.