JBoss.orgCommunity Documentation

Chapter 19. Authentication and Authorization

19.1. Authentication in JBoss Portal
19.1.1. Configuration
19.2. JAAS Login Modules
19.2.1. org.jboss.portal.identity.auth.IdentityLoginModule
19.2.2. org.jboss.portal.identity.auth.DBIdentityLoginModule
19.2.3. org.jboss.portal.identity.auth.SynchronizingLdapLoginModule
19.2.4. org.jboss.portal.identity.auth.SynchronizingLdapExtLoginModule
19.2.5. org.jboss.portal.identity.auth.SynchronizingLoginModule

This chapter describes the authentication mechanisms in JBoss Portal

JBoss Portal is heavily standard based so it leverages Java Authentication and Authorization Service (JAAS) in JBoss Application Server. Because of this it can be configured in a very flexible manner and other authentication solutions can be plugged in easily. To better understand authentication mechanisms in JBoss Portal please refer to Security chapter. To learn more about JAAS look for proper documentation on Java Security website. To learn more about security in JBoss Application Server please read JBossSX documentation.

JBoss Portal comes with a few implementations of JAAS LoginModule interface

This LoginModule implementation extends JBossSX org.jboss.security.auth.spi.DatabaseServerLoginModule and can be used to authenticate against Database. The main purpose of this module is to be configured directly against portal database (instead of using portal identity modules like in IdentityLoginModule). So if you are using custom LoginModule implementation you can place this module with "sufficient" flag. This can be extremely useful. For example if you authenticate against LDAP server using JBossSX LdapLoginModule you can fallback to users present in portal database and not present in LDAP like "admin" user. Please look into this wiki page to learn more about DatabaseServerLoginModule configuration

Options are:

  • dsJndiName - The name of the DataSource of the database containing the Principals and Roles tables
  • principalsQuery - The prepared statement query, equivalent to: "select Password from Principals where PrincipalID=?"
  • rolesQuery - The prepared statement query, equivalent to: "select Role, RoleGroup from Roles where PrincipalID=?"
  • hashAlgorithm - The name of the java.security.MessageDigest algorithm to use to hash the password. There is no default so this option must be specified to enable hashing. When hashAlgorithm is specified, the clear text password obtained from the CallbackHandler is hashed before it is passed to UsernamePasswordLoginModule.validatePassword as the inputPassword argument. The expectedPassword as stored in the users.properties file must be comparably hashed.
  • hashEncoding - The string format for the hashed pass and st be either "base64" or "hex". Base64 is the default.
  • additionalRole - additional user Principal that will be added to user Subject.

Configuration using portal database will look like this:

<login-module code = "org.jboss.portal.identity.auth.DBIdentityLoginModule"
   <module-option name="dsJndiName">java:/PortalDS</module-option>
   <module-option name="principalsQuery">
     SELECT jbp_password FROM jbp_users WHERE jbp_uname=?
   <module-option name="rolesQuery">
     SELECT jbp_roles.jbp_name, 'Roles' FROM  jbp_role_membership INNER JOIN
     jbp_roles ON jbp_role_membership.jbp_rid = jbp_roles.jbp_rid INNER JOIN jbp_users ON
     jbp_role_membership.jbp_uid = jbp_users.jbp_uid WHERE jbp_users.jbp_uname=?
   <module-option name="hashAlgorithm">MD5</module-option>
   <module-option name="hashEncoding">HEX</module-option>
   <module-option name="additionalRole">Authenticated</module-option>


SQL query should be in single line. This code snipped was formatted like this only to fit documentation page.

This module can be used instead of the IdentityLoginModule to bind to LDAP. org.jboss.portal.identity.auth.SynchronizingLDAPLoginModule class is a wrapper around LdapLoginModule from JBossSX. It extends it so all configuration that can be applied to LdapExtLoginModule remains valid here. For a user that was authenticated successfully it will try to call the identity modules from portal, then check if such user exists or not, and if does not exist it will try to create it. Then for all roles assigned to this authenticated principal it will try to check and create them using identity modules. This behavior can be altered using following options:

  • userModuleJNDIName - JNDI name of portal UserModule. This option is obligatory if synchronizeIdentity option is set to true
  • roleModuleJNDIName - JNDI name of portal RoleModule. This option is obligatory if synchronizeIdentity and synchronizeRoles options are set to true
  • membershipModuleJNDIName - JNDI name of portal MembershipModule. This option is obligatory if synchronizeIdentity and synchronizeRoles options are set to true
  • userProfileModuleJNDIName - JNDI name of portal UserProfileModule. This option is obligatory if synchronizeIdentity option is set to true
  • synchronizeIdentity - if set to true module will check if successfully authenticated user exist in portal and if not it will try to create it. If user exists module will update its password to the one that was just validated.
  • synchronizeRoles - if set to true module will iterate over all roles assigned to authenticated user and for each it will try to check if such role exists in portal and if not it will try to create it. This option is checked only if synchronizeIdentity is set to true;
  • additionalRole - module will add this role name to the group of principals assigned to the authenticated user.
  • defaultAssignedRole - if synchronizeIdentity is set to true, module will try to assign portal role with such name to the authenticated user. If such role doesn't exist in portal, module will try to create it.

For obvious reasons this is designed to use with portal identity modules configured with DB and not LDAP

All options that apply for SynchronizingLdapLoginModule also apply here. It's the same kind of wrapper made around LdapExtLoginModule from JBossSX. Sample configuration can look like this:

 <login-module code="org.jboss.portal.identity.auth.SynchronizingLDAPExtLoginModule"
   <module-option name="synchronizeIdentity">true</module-option>
   <module-option name="synchronizeRoles">true</module-option>
   <module-option name="additionalRole">Authenticated</module-option>
   <module-option name="defaultAssignedRole">User</module-option>
   <module-option name="userModuleJNDIName">java:/portal/UserModule</module-option>
   <module-option name="roleModuleJNDIName">java:/portal/RoleModule</module-option>
   <module-option name="membershipModuleJNDIName">java:/portal/MembershipModule
   <module-option name="userProfileModuleJNDIName">java:/portal/UserProfileModule
   <module-option name="java.naming.factory.initial">com.sun.jndi.ldap.LdapCtxFactory
   <module-option name="java.naming.provider.url">ldap://example.com:10389/
   <module-option name="java.naming.security.authentication">simple</module-option>
   <module-option name="bindDN">cn=Directory Manager</module-option>
   <module-option name="bindCredential">secret</module-option>
   <module-option name="baseCtxDN">ou=People,dc=example,dc=com</module-option>
   <module-option name="baseFilter">(uid={0})</module-option>
   <module-option name="rolesCtxDN">ou=Roles,dc=example,dc=com</module-option>
   <module-option name="roleFilter">(member={1})</module-option>
   <module-option name="roleAttributeID">cn</module-option>
   <module-option name="roleRecursion">-1</module-option>
   <module-option name="searchTimeLimit">10000</module-option>
   <module-option name="searchScope">SUBTREE_SCOPE</module-option>
   <module-option name="allowEmptyPasswords">false</module-option>

This module is designed to provide synchronization support for any other LoginModule placed in the authentication stack. It leverages the fact that in JAAS authentication process occurs in two phases. In first phase when login() method is invoked it always returns "true". Because of this behavior SynchronizingLoginModule should be always used with "optional" flag. More over it should be placed after the module we want to leverage as a source for synchronization and that module should have "required" flag set. During the second phase when commit() method is invoked it gets user Subject and its Principals and tries to synchronize them into storage configured for portal identity modules. For this purposes such options are supported: