Integrating with WAS security using a custom interceptor

This section describes how to create an SSO interceptor to integrate with WebSphere Application Server (WAS) security.

Before you begin

The provided Form SSO Interceptor authenticates users with form-based login page. The following is an example of how to create a custom SSO interceptor. The custom interceptor uses a custom interceptor class.

The interceptor class accesses WAS to obtain authenticated user credentials. After those credentials are obtained, they are cached. Subsequent logins use the cached credentials.

Prerequisite: A user must be configured in WAS with LDAP user credentials.
Note: You must make the Build Forge LDAP domain containing the WAS users the "default" LDAP server. To do this, go to this Build Forge LDAP domain, and select "Make Default."

Protecting your authorization service (AuthServlet)

Build Forge normally runs its services as an application in the provided Apache Tomcat application server.

About this task

The following instructions configure Build Forge to use WAS instead of Tomcat. Follow the instructions in the section Using WebSphere Application Server instead of Apache Tomcat, with one exception: the rbf-services.war file contains a file named web.xml that you need to extract and modify to add a security constraint. Before installing this application under WAS, the war file will need to be regenerated after modifying it to use the protected version of this file.

To do this, follow these instructions:

Procedure

  1. Navigate to the directory containing your rbf-services.war file (the webapps directory in your Tomcat server root). Copy this file to a temporary location, such as C:\rbf.
  2. Expand the WAR file. From command line, run the command: %IBM_JAVA_HOME%\jar –xvf rbf-services.war to expand the contents of the war file.
    Note: Java must be available and the IBM_JAVA_HOME environment variable must already have been created.
  3. Save the rbf-services.war file to retrieve later:
    1. Windows: copy rbf-services.war rbf-services.war.bak
    2. UNIX or Linux: cp rbf-services.war rbf-services.war.bak
  4. Find the web.xml file in the WEB-INF directory (from the files expanded from the war file). Edit this file to add a security context. For example, add the following lines at the end of the file just before the </web-app> tag:
    <security-constraint id="SecurityConstraint_1">
             <web-resource-collection id="WebResourceCollection_1">
                <web-resource-name>/*</web-resource-name>
                <url-pattern>/AuthServlet/*</url-pattern>
                <http-method>GET</http-method>
                <http-method>POST</http-method>
                <http-method>PUT</http-method>
                <http-method>DELETE</http-method>
             </web-resource-collection>
             <auth-constraint id="AuthConstraint_1">
                <description>myconstraint:+:</description>
                <role-name>User</role-name>
             </auth-constraint>
             <user-data-constraint id="UserDataConstraint_1">
                <transport-guarantee>NONE</transport-guarantee>
             </user-data-constraint>
          </security-constraint>
          <login-config id="LoginConfig_1">
             <auth-method>BASIC</auth-method>
             <realm-name>full-qualified-domain</realm-name>
          </login-config>
          <security-role id="SecurityRole_1">
             <role-name>User</role-name>
          </security-role>
    Note: The <auth-method> can be any J2EE auth-method supported by WAS. The most common auth-method is FORM, which requires additional configuration parameters. Refer to your WebSphere documentation for instructions on configuring FORM in your application.
  5. From command line, regenerate the war file (called from the same directory that it was extracted to) by running the following command:
    %IBM_JAVA_HOME%\jar –cvf  rbf-services.war

    You should now have a new version of rbf-services that has been modified to protect the AuthServlet with J2EE constraints. Complete the installation instructions for running with WAS and install this version of the rbf-services.war via Applications->Install New Application. Make sure that Build Forge is not running while configuring WAS.

    After this is installed, go to Applications->Enterprise Applications. Click the application name to configure it. Under Detail Properties, click the link entitled Security role to user/group mapping. Select the All Authenticated checkbox for User. After making this change, be sure to save to the master configuration.

    Application Security also needs to be enabled under WAS. To do this, go to Security->Secure administration, applications, and infrastructure. Make sure that Enable application security is checked.

    At this point, restart the WAS server, and then restart the Build Forge server.
    Note: The rbf-services should now start as part of the WAS startup process, so WAS needs to be started before Build Forge.

Creating a new SSO configuration

Create a new SSO configuration to use the interceptor.

Procedure

  1. In the Build Forge console, go to Administration->Security->SSO.
  2. Click Add SSO Configuration.
  3. Set properties for the configuration.
    • Name - Enter a name for this configuration.
    • Java Class - Enter com.buildforge.services.server.sso.was.WebSphereSSOInterceptor
    • Active - Select Yes.
  4. Click Save.
  5. Move this configuration to appear first in the list. In the menu to the left of the configuration name, select Move to Top.

Mapping LDAP users or an LDAP group to local users

Map LDAP users or an LDAP group to local users, such as the local root user.

About this task

After you create a WebSphere SSO interceptor, you can configure the interceptor to:
  • Map LDAP users to local users, including root
  • Map an LDAP group to a local user, such as root

To set up a mapping, define an environment and then reference that environment in the interceptor.

Defining an environment

Procedure

  1. In the Build Forge console, click Environments.
  2. Specify a name for the environment and click Save Environment.
  3. To map LDAP users to local users, set and save the following variables:
    1. Set ldap_user_list_mapping to LDAP_user1|local_user1;LDAP_user2|local_user2;LDAP_user3|local_user3
    2. Set ldap_realm_name to LDAP_domain_name
    For example, assume the following environment is set:
    	ldap_user_list_mapping = user1|root;user2|root;user3|root
    	ldap_realm_name = bluepages.ibm.com:389

    In this case, LDAP user1, user2, and user3 are all mapped to the local root user.

  4. To map members of a specific LDAP group to a local user, set and save the following variables:
    1. Set ldap_group_name_mapping to LDAP_group|local_user
    2. Set ldap_realm_name to LDAP_domain_name
    Note: If you use both types of mappings, the user mapping takes precedence over the group mapping.
    For an example of a group mapping, assume the following environment is set:
    	ldap_group_name_mapping = cn=bf_admin,ou=memberlist,ou=ibmgroups,o=ibm.com|root
    	ldap_realm_name = bluepages.ibm.com:389

    In this case, users who are members of the LDAP group cn=bf_admin,ou=memberlist,ou=ibmgroups,o=ibm.com are mapped to the local root user.

Referencing the environment

Procedure

  1. In the Build Forge console, click Administration->Security->SSO.
  2. Click the name of the WebSphere SSO interceptor.
  3. Set the Environment property for the configuration to the environment you just defined.
  4. Click Save.
  5. Move this configuration to appear first in the list. In the menu to the left of the configuration name, select Move to Top.

Running the SSO custom interceptor

You can now log in using your new configurations.

About this task

This customized SSO interceptor will now allow WAS security techniques to authenticate the user, via an AuthServlet request to be passed to Build Forge as a user.

Procedure

  1. Open your web browser. Enter the address http://localhost.
  2. Instead of the Build Forge login form, you will now see an authentication page. Enter your user credentials and hit Enter.
  3. After authentication, note that login should occur automatically.
  4. After logging out, it will display the default jsp page instead of the login form. Subsequent logins will be automatic if the user is still authenticated.

Reverting to form-based SSO

You can revert to using the SSO login form.

About this task

To reconfigure the systems to use the Form Login, under WAS you must uninstall rbf-services and reinstall the original rbf-services.war file. Under Build Forge, ensure that the form-based SSO interceptor is enabled and listed as the top item. Disable the Custom WAS interceptor. WAS and Build Forge need to be restarted for these changes to take place.

Procedure

  1. Uninstall rbf-services and reinstall the original rbf-services.war file.
  2. Under Build Forge, ensure that the form SSO interceptor is enabled and listed as the first item (see "Build Forge SSO security configurations," above).
  3. Disable the Custom WAS interceptor.
  4. Restart WAS.
  5. Restart Build Forge.

Feedback