Chapter 15. Authentication and Authorization
Prev |  | Next

## Chapter 15. Authentication and Authorization

### Boleslaw Dawidowicz

`<boleslaw dot dawidowicz at redhat dot com>`

This chapter describes the authentication mechanisms in JBoss Portal

## 15.1. Authentication 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.

### 15.1.1. Configuration

You can configure the JAAS authentication stack in jboss-portal.sar/conf/login-config.xml. It is important to remember that authorisation in portal starts at the JAAS level - configured LoginModules apply proper Principal objects representing the roles of authenticated user. As you can see in jboss-portal.sar/portal-server.war/WEB-INF/web.xml portal servlet is secured with specified role ("Authenticated"). In the default portal configuration this role is dynamically added by IdentityLoginModule. If you reconfigure the default JAAS authentication chain with other LoginModule implementations, you should remember that you must deal with that security constraints in order to be able to access portal. For example if you place only one LoginModule that will authenticate users against LDAP server you may consider adding all users in your LDAP tree to such role.

## 15.2. JAAS Login Modules

JBoss Portal comes with a few implementations of JAAS LoginModule interface

### 15.2.1. org.jboss.portal.identity.auth.IdentityLoginModule

This is the standard portal LoginModule implementation that uses portal identity modules in order to search users and roles. By default it is the only configured LoginModule in the portal authentication stack. Its behaviour can be altered with the following options:

- userModuleJNDIName - JNDI name of portal UserModule.
- roleModuleJNDIName - JNDI name of portal RoleModule.
- membershipModuleJNDIName - JNDI name of portal MembershipModule.
- additionalRole - additional user Principal that will be added to user Subject. This is important as in default portal configuration it is the role that portal servlet is secured with.
- havingRole - only users belonging to role specified with this option will be authenticated.
- unauthenticatedIdentity - the principal to use when a null username and password are seen.

### Note

IdentityLoginModule extends org.jboss.security.auth.spi.UsernamePasswordLoginModule so if you are familiar with JBossSX you can apply few other options like "password-stacking". Please refer to JBossSX documentation.

### 15.2.2. org.jboss.portal.identity.auth.DBIdentityLoginModule

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"
                  flag="sufficient">
       <module-option name="dsJndiName">java:/PortalDS</module-option>
       <module-option name="principalsQuery">
         SELECT jbp_password FROM jbp_users WHERE jbp_uname=?
       </module-option/>
       <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>
       <module-option name="hashAlgorithm">MD5</module-option>
       <module-option name="hashEncoding">HEX</module-option>
       <module-option name="additionalRole">Authenticated</module-option>
    </login-module>

### Note

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

### 15.2.3. org.jboss.portal.identity.auth.SynchronizingLdapLoginModule

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

### 15.2.4. org.jboss.portal.identity.auth.SynchronizingLdapExtLoginModule

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"
                   flag="required">
       <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>
       <module-option name="userProfileModuleJNDIName">java:/portal/UserProfileModule
       </module-option>
       <module-option name="java.naming.factory.initial">com.sun.jndi.ldap.LdapCtxFactory
       </module-option>
       <module-option name="java.naming.provider.url">ldap://example.com:10389/
       </module-option>
       <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>
    </login-module>

### 15.2.5. org.jboss.portal.identity.auth.SynchronizingLoginModule

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 behaviour 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:

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

### Note

Example of usage in LDAP authentication can be found in next chapter.

Prev | Up | Next
Chapter 14. JBoss Portal Identity Management | Home | Chapter 16. LDAP