Integrating with WebSphere Application Server security using a custom interceptor

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

Before you begin

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

About this task

The provided Form SSO Interceptor authenticates users with a 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 WebSphere Application Server to obtain authenticated user credentials. After those credentials are obtained, they are cached. Subsequent logins use the cached credentials.

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 WebSphere Application Server instead of Tomcat. Follow the instructions in the section Using WebSphere Application Server instead of Apache Tomcat, with one exception: the jas.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 WebSphere Application Server, the war file must be regenerated after modifying it to use the protected version of this file.

To regenerate the war file, complete the following steps.

Procedure

  1. Navigate to the directory containing your jas.war file (the webapps directory in your Tomcat server root). Copy this file to a temporary location, such as C:\jas.
  2. Expand the WAR file. From command line, run the command: %IBM_JAVA_HOME%\jar –xvf jas.war to expand the contents of the war file.
    Note: Java must be available and the IBM_JAVA_HOME environment variable must have been created.
  3. Save the jas.war file to retrieve later:
    1. Windows: copy jas.war jas.war.bak
    2. UNIX or Linux: cp jas.war jas.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 WebSphere Application Server. The most common auth-method is FORM, which requires additional configuration parameters. Refer to your WebSphere Application Server documentation for instructions on configuring FORM in your application.
  5. From a 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  jas.war

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

    After installation, go to Applications > Enterprise Applications. Click the application name to configure it. Under Detail Properties, click the Security role to user/group mapping link. Select the All Authenticated check box for User. After making this change, save the change to the master configuration.

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

    At this point, restart WebSphere Application Server, and then restart the Build Forge server.
    Note: The jas now starts as part of the WebSphere Application Server startup process, so start WebSphere Application Server before starting 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 Application Server 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 Application Server 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 now allows WebSphere Application Server security techniques to authenticate the user, by way of an AuthServlet request to be passed to Build Forge as a user.

Procedure

  1. Open your web browser, and enter the address http://localhost. Instead of the Build Forge login form, you now see an authentication page.
  2. Enter your user credentials and click Enter.
    Note: After authentication, login occurs automatically.

    After logging out, the default jsp page is displayed instead of the login form. Subsequent logins are automatic if you are 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 WebSphere Application Server you must uninstall jas and reinstall the original jas.war file. Under Build Forge, ensure that the form-based SSO interceptor is enabled and listed as the top item. Disable the custom WebSphere Application Server interceptor. To enable your changes, you must restart WebSphere Application Server and Build Forge.

Procedure

  1. Uninstall jas and reinstall the original jas.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 WebSphere Application Server interceptor.
  4. Restart WebSphere Application Server.
  5. Restart Build Forge.

Feedback