Configuring J2EE Principal Authentication for EMC ... · Configuring J2EE Principal Authentication 4 for EMC Documentum Webtop on IBM WebSphere Executive summary This white paper

White Paper

Abstract

This white paper details the installation and configuration of J2EE Principal Authentication for the EMC® Documentum® WDK application Webtop on IBM WebSphere. March 2011

CONFIGURING J2EE PRINCIPAL AUTHENTICATION FOR EMC DOCUMENTUM WEBTOP ON IBM WEBSPHERE

2 Configuring J2EE Principal Authentication for EMC Documentum Webtop on IBM WebSphere

Copyright © 2011 EMC Corporation. All Rights Reserved. EMC believes the information in this publication is accurate of its publication date. The information is subject to change without notice. The information in this publication is provided “as is”. EMC Corporation makes no representations or warranties of any kind with respect to the information in this publication, and specifically disclaims implied warranties of merchantability or fitness for a particular purpose. Use, copying, and distribution of any EMC software described in this publication requires an applicable software license. For the most up-to-date listing of EMC product names, see EMC Corporation Trademarks on EMC.com. All other trademarks used herein are the property of their respective owners. Part Number h8213


Table of Contents

Executive summary.................................................................................................. 4

Audience ............................................................................................................................ 4

Introduction ............................................................................................................ 4

Installing and configuring Webtop on WebSphere .................................................... 4

Requirements ..................................................................................................................... 4

Installing the war file .......................................................................................................... 5

Configuring the Class loader setting ................................................................................... 8

Setting the JSP compiler option .......................................................................................... 9

Configuring J2EE Principal Authentication for Webtop ............................................. 10

Configuring web.xml ......................................................................................................... 10

Setting up the file registry ................................................................................................. 11

Setting up WebSphere for J2EE authentication ................................................................. 11

Configuring users and/or groups to the Application Roles ................................................ 14

Configuring the password encryption ............................................................................... 17

Troubleshooting .................................................................................................... 19

Resolution ........................................................................................................................ 19

Conclusion ............................................................................................................ 19


Executive summary This white paper outlines best practices and guidelines for installing and configuring J2EE Principal Authentication for an EMC® Documentum® Web Development Kit (WDK)-based application (Webtop) on an IBM WebSphere application server.

J2EE Principal Authentication allows a single login to the web server and Content Server. The identity of the user who logs in to the web application must match the login identity in the repository. While the identity of the user (username) is passed on to the web application, the same is not applicable to the user’s password. WDK then logs in to the repository for the user by employing a trusted authenticator identity. The trusted authenticator must be a superuser for the specified repository.

Audience

This white paper is intended for IT architects, engineers, support professionals, and customers. It provides basic directions for using J2EE Principal Authentication.

Introduction This white paper includes two main sections:

Installing and configuring Webtop on WebSphere

Configuring J2EE Principal Authentication for Webtop

This setup was performed with Documentum Webtop 6.5 SP3 and IBM WebSphere version 6.1.

It has been observed that the procedure provided in this paper leads to a successful install. If you choose to deviate from these steps, EMC does not guarantee that the procedure will work. A production setup may need advanced configuration, which is out of the scope of this paper. In such cases, you are expected to refer to other available documentation and judiciously continue the install.

Installing and configuring Webtop on WebSphere This section provides detailed procedures to install and configure the WDK-based application Webtop on WebSphere 6.1.

Requirements

Before you install and configure Webtop on WebSphere, you must perform the following installation tasks (as required):

• Set up the IBM WebSphere application server

• Obtain the latest Webtop war file for deployment


Installing the war file

To install the war file, proceed as follows:

1. Start the IBM WebSphere server.

2. Log in to the Administrative console (for example, http://localhost:9060/admin).

3. Select Applications > Install New Applications.

4. Under Path to the new application, select Local file system.

5. Browse the location of the Webtop.war file in your computer.

6. Under Context root, type the preferred value of webtop.

7. Click Next. The Select Installation options page appears.

8. Retain the default settings.


9. Click Next. The Map modules to servers page appears.

10. Select the webtop.war module.

11. Click Next. The Map virtual hosts to Web modules page appears.


12. Select the webtop.war web module and click Next. The Summary page appears.

13. Retain the default settings and click Finish.

WebSphere takes some time to install the webtop.war file.

After successful installation, a message appears that states "ADMA5013I: Application webtop_war installed successfully.” This is shown in the following screenshot.


Configuring the Class loader setting

To configure the Class loader policy for the war file, proceed as follows:

1. Select Applications > Enterprise Applications. The Enterprise Applications page appears.

2. Select webtop_war > Manage Modules link > webtop.war.


3. In the General Properties area, select Class loaded with application class loader first as the Class loader order property. Select Apply > OK.

4. Click Save to save the changes made to the master configuration.

5. Log out from the console and restart the server.

Setting the JSP compiler option

To configure the JSP compiler settings for the war file, proceed as follows:

1. Navigate to <WAS INSTALL HOME>\ AppServer\profiles\AppSrv01\config\cells\<Machine Name> Node01Cell \applications\webtop_war.ear\deployments\webtop_war\webtop.war\WEB-INF.

2. Add the following JSP attributes to modify the content on the ibm-web-ext.xmi file:

<jspAttributes xmi:id="JSPAttribute_1178213473751" name="jdkSourceLevel" value="15"/>

<jspAttributes xmi:id="JSPAttribute_3" name="useJDKCompiler" value="true"/>

The installation of the Webtop application on IBM WebSphere is complete. Restart the application server and access the Webtop URL. The default port to access Webtop on WebSphere is port 9080 (for example, http://localhost:9080/webtop).

http://localhost:9080/webtop


Configuring J2EE Principal Authentication for Webtop This section provides detailed procedures to configure J2EE Principal Authentication for Webtop on WebSphere.

Configuring web.xml

The web.xml file will be configured either in the application binaries (the application's EAR file) or from the configuration repository, depending on how the application was deployed into the WebSphere application server.

If the application was deployed with the “Use Binary Configuration” flag as TRUE, then the application binary directory web.xml file will be modified, or the web.xml file of the configuration repository directory will be modified.

Example of a configuration repository directory:

WAS_ROOT/profiles/profilename/config/cells/cellname/applications/webtop.ear/deployments/webtop.war/webtop/WEB-INF

Example of an application binaries directory:

WAS_ROOT/profiles/profilename/installedApps/nodename/

webtop.ear/webtop.war/WEB-INF

1. Modify the content of the web.xml file by adding the following “security-role” before the “security-constraint” elements.

<security-role>

<description></description>

<role-name>WebtopUsers</role-name>

</security-role>

2. Uncomment the J2EE Authentication section of the web.xml file and modify the “role-name” as mentioned in the “security-role” section.

<security-constraint>

<web-resource-collection>

<web-resource-name>webtop</web-resource-name>


<url-pattern>/*</url-pattern>

<http-method>GET</http-method>

<http-method>POST</http-method>

</web-resource-collection>

<auth-constraint>



<role-name> WebtopUsers </role-name>

</auth-constraint>

</security-constraint>

Setting up the file registry

To set up the file registry, two files need to be created in the local file system for users and groups, named “users.prop” and “groups.prop”. For a silent login to occur, the user listed here must have the same username as in the repository. The group identifiers listed here, along with the user as a member, must be present in the repository as mentioned below.

User list:

user1:password:123:567,987:User1

user2:password:345:789:User2

dmadmin:password:678:567,987:dmadmin

Format:

<user name>:<password>:<unique user identifier>:<identifiers of groups user belongs to commas separated>:<Display Name>

Group list:

group1:567:user1,dmadmin:Group1

group2:789:user2:Group2

admin:987:user1,dmadmin:Admin

Format:

<group-name>:<group identifier>:<users that belong to the group comma separated>:<display name>

Setting up WebSphere for J2EE authentication

To set up WebSphere for J2EE Authentication, proceed as follows:

1. Ensure that the Java EE Principal Authentication is listed at the top of the list of authentication schemes in the file called com.documentum.web.formext.session.AuthenticationSchemes.properties.

2. Add the repository name to the app.xml file.

3. Add the following tag to the custom app.xml file or Webtop’s app.xml file.

<authentication>



<domain></domain>


<docbase>mydocbase</docbase>



<service_class>com.documentum.web.formext.session.AuthenticationService </service_class>

</authentication>

4. To configure J2EE authentication on WebSphere, open the Administrative console and navigate to Security on the left navigation bar.

5. Click Secure Administration, applications and infrastructure.

6. Click Security Configuration Wizard.

7. Retain the default settings and click Next to continue. The Select user repository page appears.


8. Select Standalone custom registry and click Next.

9. In the Primary administrative user name field, enter the username that you use to log in to the WebSphere Administrative console.

10. Enter two custom properties, “usersFile” and “groupsFile”, in the Name field. Provide the path location for the filenames “users.prop” and “groups.prop” as shown below.

11. Click Next. The Summary page appears.

12. Click Finish.



14. Restart the application server to use the new security configuration.

15. Log in to the Administrative console with the username that you provided in the Primary administrative user name field.

Configuring users and/or groups to the Application Roles

As a Primary administrative user, you can assign users and/or groups to Application Roles that are defined in the web.xml file for the Webtop application.


1. Log in to the Administrative console of WebSphere as a Primary administrative user. Select Applications > Enterprise Applications > webtop_war.

2. In the Detail Properties area, click Security role to user/group mapping. The Security role to user/group mapping page appears.

3. Select the checkbox for the Webtop user’s role and click Look up users.

4. Click Search to retrieve all users present in the users.prop file.


5. Use >> or << to add the required users from the Available list to the Selected list.

6. Click OK. The Security role to user/group mapping page appears.

7. Click OK. A message appears that states that changes have been made to your local configuration.



9. Restart the application.

Configuring the password encryption

For completion of Principal Authentication, an encrypted password must be created for the principal user. To configure the encryption password, proceed as follows:

1. Set “IBM Websphere JDK” and “Java_Home” in your classpath for encrypting the password.

2. Set “com.documentum.web.formext.session.TrustedAuthenticatorTool”, “WEB-INF\lib\dfc.jar”, and “WEB-INF\lib\commons-io-1.2.jar” in the classpath.

3. Run the following command on a single line in the command prompt.

java –classpath "%CLASSPATH%;path_to_WEBINF/classes" TrustedAuthenticatorTool password

The output is as follows:

Encrypted: [xD4vF3arqb5mW44mpltbXg==], Decrypted: [password]

4. Configure the TrustedAuthenticatorCredentials.properties file located in:

/WEB-INF/classes/com/documentum/web/formext/session

Each repository must have an entry for the superuser, encrypted password, and domain, if needed.

The following are sample entries:

Repository_name.user


Repository_name.new-pw

Repository_name.domain

5. For preferences or presets repository passwords, paste the encrypted form of the password into the app.xml file in the custom directory. Insert the encrypted preferences password into <preferencesrepository>.<password>, or the encrypted presets password into <presets>.<password>.

6. The symmetric keys for encryption and decryption are stored in a file named wdk.keystore. This file must be stored in a secure location on the local file system.

7. Configure the KeystoreCredentials.properties file, located in /WEB-INF/classes/com/documentum/web/formext/session, and specify the location of the wdk.keystore file.

8. Override the use of the default DFC config directory in order to substitute the new location of keystore file.

An example is keystore.file.location=C:/Documentum/config/wdk.keystore, use_dfc_config_dir=false.

By default, the keystore file location is created in the DFC config directory, which contains the dfc.properties file and is specified as the value of dfc.config.dir in dfc.properties.

9. Restart the application server for the configuration changes to take effect.

10. Access the Webtop URL (for example, http://localhost:9080/webtop). The first time you access the resource, the login screen appears, prompting you to enter your login credentials, as shown below.


11. If multiple repositories are present, select the repository you need to access. After this, every time you access the Webtop URL, you will be logged in directly to the repository, unless you clear your browser cookies.

Troubleshooting You may encounter errors when installing the Webtop application on WebSphere.

For example, while performing a UCF operation with a WDK application (for example, Webtop) installed on IBM WebSphere 6, the following error is generated:

Stack Trace:

sun.io.MalformedInputException

at sun.io.ByteToCharUTF8.convert(ByteToCharUTF8.java:262)

at sun.nio.cs.StreamDecoder$ConverterSD.convertInto(StreamDecoder.java:314)

at sun.nio.cs.StreamDecoder$ConverterSD.implRead(StreamDecoder.java:364)

at sun.nio.cs.StreamDecoder.read(StreamDecoder.java:250)

Resolution 1. Log in to the Administrative console.

2. Select Servers > Application servers > WebSphere_Portal.

3. Under the Server Infrastructure area, select Java and Process Management > Process Definition > Java Virtual Machine.

4. In the Generic JVM arguments field, add a space followed by the text:

-Dibm.stream.nio=true

5. Select Apply > Save to save the changes made to the master configuration.

6. Restart the application server.

Conclusion Using the procedures described in this paper, the EMC Documentum WDK web application is successfully installed on IBM and configured with J2EE Principal Authentication.

Documents

Configuring J2EE Principal Authentication for EMC ... · Configuring J2EE Principal Authentication 4 for EMC Documentum Webtop on IBM WebSphere Executive summary This white paper