Chapter 4. Security

4.1. Authentication

4.1.1. Authentication

The JBoss Enterprise BRMS Platform uses the Java Authentication and Authorization Service for verifying user credentials. This service is supplied by the application server and is used to access a separate authentication system. The separate system could be a Lightweight Directory Access Protocol (LDAP), Active Directory server, or JDBC database.

4.1.2. Configuring Authentication

Configure which authentication method is to be used via the jboss-brms.war/WEB-INF/components.xml file. The default configuration has many "commented out" options but the actual settings look like this: 
<security:identity authenticate-method="#{authenticator.authenticate}" jaas-config-name="jmx-console"/>
<component name="org.jboss.seam.security.roleBasedPermissionResolver">
   <property name="enableRoleBasedAuthorization">false</property>
</component>

Note

In JBoss BRMS 5.1 and earlier versions, the components.xml file looks like this: 
<security:identity authenticate-method="#{authenticator.authenticate}" jaas-config-name="jmx-console"/> 
<security:role-based-permission-resolver enable-role-based-authorization="false"/>

Important

This default configuration uses the account names, passwords, and roles that are defined in the jmx-console authentication policy. Red Hat recommends editing this policy to tailor it for your specific environment.
To configure authentication, follow these steps:
  1. Edit the appropriate JBoss login module of the application server.
  2. Configure the JBoss Enterprise BRMS Platform to use that module.

Note

Many JBoss login modules provide a means of specifying one or more roles for each user. The JBoss Enterprise BRMS Platform has its own mechanism for managing user roles.

Warning

If role-based authorization is disabled, all users effectively have the admin role. This gives them complete access to the JBoss Enterprise BRMS Platform.

4.1.3. Password Configuration for JAAS

When using the default JAAS authentication system, usernames and passwords need to be synchronized between JBoss Enterprise BRMS, the Process Designer, and the Business Central console. If the same usernames and passwords are not used, the different components will not function together.
If the additional users are added to the brms-users.properties file, they also need to be synchronized for the Process Designer and Business Central Console.

Procedure 4.1. Synchronizing Usernames and Passwords

  1. Process Designer: To edit the usernames and passwords for the Process Designer, which is a separate application integrated with JBoss Enterprise BRMS, open the designer.war/profiles/jbpm.xml file and edit the usr and pwd properties: 
    usr="admin" pwd="admin"
  2. Business Central Console. To edit the usernames and passwords for the Business Central Console, open the business-central-server.war/WEB-INF/classes/jbpm.console.properties file and edit the guvnor.usr and guvnor.pwd properties: 
    guvnor.usr=admin
guvnor.pwd=admin

4.1.4. Example Authentication: UserRolesLoginModule

This example illustrates the use of the org.jboss.security.auth.spi.UsersRolesLoginModule login module to access a set of user accounts stored in the props/brms-users.properties and props/brms-roles.properties files.

Procedure 4.2.  Authentication Example: UserRolesLoginModule

  1. Ensure the Authentication System is Configured Correctly

    This login module uses two files to store the login name, password, and roles assigned to each user. Create the brms-users.properties and brms-roles.properties files in the jboss-as-web/server/PROFILE/conf/props/ directory and then specify at least one user in brms-users.properties using this format: username=password. (the brms-roles.properties file can be left empty.)

  2. Shut Down

    Shut down the application server before making these changes.

  3. Configure the JBoss Login Module

    To configure the JBoss Login Modules, open jboss-as-web/server/PROFILE/conf/login-config.xml in a text editor. It is an XML file containing a <policy> element with several <application-policy> child elements. Each <application-policy> element defines a different authentication scheme. Add the following <application-policy> XML snippet as a new child of the <policy> element: 
    <!--BRMS Platform Security Domain-->
<application-policy name="brms">
   <authentication>
       <login-module
           code="org.jboss.security.auth.spi.UsersRolesLoginModule"
           flag="required">
            <module-option name="usersProperties">
                props/brms-users.properties
            </module-option>
            <module-option name="rolesProperties">
                props/brms-roles.properties
            </module-option>
        </login-module>
    </authentication>
</application-policy>

  4. Configure the BRMS Platform to use the Login Module

    Open the jboss-as-web/server/PROFILE/deploy/JBoss-BRMS.war/WEB-INF/components.xml file. It contains one <components> element with several child elements, including <security:identity> .
    Comment out the existing <security:identity> elements to prevent conflicts. Add the following <security:identity> element: 
    <security:identity authenticate-
method="#{authenticator.authenticate}" jaas-config-name="brms"/>
    The jaas-config-name property must be the same as the application-policy. If the application-policy property was changed in the previous step, modify the jaas-config-name property here to match.

  5. Restart

    Restart the application server.

4.1.5. Example Authentication: LDAP

LDAP is a popular choice for larger enterprises. The basic configuration steps are the same as the previous example although the details of the configuration will differ.

Procedure 4.3.  Authentication Example Two: LDAP

  1. Ensure the LDAP Server is Configured Correctly

    Check that firewall and network configuration settings are not preventing communication between the application server and the LDAP server.

  2. Shut Down

    Shut down the application server before making these changes.

  3. Configure the JBoss Login Module

    To configure the JBoss Login Modules, open jboss-as-web/server/PROFILE/conf/login-config.xml in a text editor. It is an XML file containing a <policy> element with several <application-policy> child elements. Each <application-policy> element defines a different authentication scheme. Add the following <application-policy> XML snippet as a new child of the <policy> element: 
    <application-policy name="brms">
 <authentication>
  <login-module code="org.jboss.security.auth.spi.LdapExtLoginModule" 
      flag="required" >
    <module-option name="java.naming.provider.url">
        ldap://ldap.company.com:389
    </module-option>
    <module-option name="bindDN">DEPARTMENT\someadmin</module-option>
    <module-option name="bindCredential">password</module-option>
    <module-option name="baseCtxDN">cn=Users,dc=company,dc=com
    </module-option>
    <module-option name="baseFilter">(sAMAccountName={0})</module-option>
    <module-option name="rolesCtxDN">cn=Users,dc=company,dc=com
    </module-option>
    <module-option name="roleFilter">(sAMAccountName={0})</module-option>
    <module-option name="roleAttributeID">memberOf</module-option>
    <module-option name="roleAttributeIsDN">true</module-option>
    <module-option name="roleNameAttributeID">cn</module-option>
    <module-option name="roleRecursion">-1</module-option>
    <module-option name="searchScope">ONELEVEL_SCOPE</module-option>
  </login-module>
 </authentication>
</application-policy>
    Update the values in this configuration file with those appropriate for your LDAP server.

  4. Configure the BRMS Platform to use the Login Module

    Open the jboss-as-web/server/PROFILE/deploy/jboss-brms.war/WEB-INF/components.xml file. It contains one <components> element with several child elements, including <security:identity> .
    Comment out the existing <security:identity> elements to prevent conflicts. Add the following <security:identity> element: 
    <security:identity authenticate-method="#{authenticator.authenticate}" jaas-config-name="brms"/>
    The jaas-config-name property must be the same as the application-policy. If the application-policy property was changed in the previous step, modify the jaas-config-name property here to match.

  5. Restart

    Restart the application server.