Quick guide to implementing SiteMinder WebSphere Application Server Agent

This is a quick guide on integrating SiteMinder with WebSphere 6.1 via the TAI. The sample application protected with J2EE security is the snoop servlet deployed as part of the DefaultApplication that comes with WebSphere. The snoop servlet will display all header information as configured by SiteMinder policies. A pdf of this guide is available here for download.

Required Servers

Server1: Windows 2003sp2, Java, Jboss, CA SiteMinder R12sp1 Policy Server, CA SiteMinder R12sp1 UI, Sun LDAP 5.2, MS SLQ 2005

Server 2: Solaris10 Sparc, java, WebSphere 6.1.0.13+, JCE patch, IBM HTTP Server 6.1

Prerequisites:
LDAP

LDAP instance to be used by WebSphere and SiteMinder as the user repository.
Required LDAP entries:
Uid=wsadmin,ou=people,dc=ca,dc=com
To be used as a WebSphere Admin

Uid=tester,ou=people,dc=ca,dc=com
To be used as a application test user

Cn=WASaccess,ou=groups,dc=ca,dc=com
Group to give access to snoop application
Add tester as member of group.


WebSphere 6.1.0.13 or higher

Standard or Deployment Manager

SM WebSphere ASA 6.0 plus CR 6 or higher

smasa-6.0-was-unix.zip
smasa-6.0-cr006-was.zip

Pre-Agent Setup

WebSphere Configurations

Setup WebSphere global security using the same LDAP repository to be used by SiteMinder.

Login to the WebSphere Admin console using the admin ID created at the time of install. http://: 9043/ibm/console/logon.jsp

Configure Global security using the LDAP user store.

Expand Security and click on Secure administration, applications, and infrastructure. Click on Security Configuration Wizard.

Select Enable application security
Select Use Java 2 security to restrict application access to local resources
Click Next

Select Standalone LDAP registry, click on Next.

Enter the required info to connect to your LDAP repository. Click Next to continue.

Make note of the Primary administrative user name. You will need it later.
The final screen will be a summary screen. Click on Finish to save changes.

Click Save to implement the updates.

Log out of console to restart WebSphere. You will need to shut down the WebSphere server. Shut down using the following command:

/AppServer/bin/stopServer.sh (appservername)
example:
/opt/WebSphere/AppServer/bin/stopServer.sh server1
ADMU0116I: Tool information is being logged in file
/opt/WebSphere/AppServer/profiles/AppSrv01/logs/server1/stopServer.log
ADMU0128I: Starting tool with the AppSrv01 profile
ADMU3100I: Reading configuration for server: server1
ADMU3201I: Server stop request issued. Waiting for stop status.
ADMU4000I: Server server1 stop completed.

Before you restart the WebSphere environment, it is important to update the security property file to update the admin user and password with the WebSphere Primary administrative user name you used previously. This will allow the start, stop, and communication of WebSphere components without being prompted for the username and password.

On the WebSphere server,
/AppServer/profiles/AppSrv01/properties/soap.client.props
example:
/opt/WebSphere/AppServer/profiles/AppSrv01/properties/soap.client.props

modify the following lines:
#------------------------------------------------------------------------------
# SOAP Client Security Enablement
#
# - security enabled status ( false[default], true )
#------------------------------------------------------------------------------
com.ibm.SOAP.securityEnabled=true

com.ibm.SOAP.loginUserid=wsadmin
com.ibm.SOAP.loginPassword=password

There is a way to encrypt the password and this can be done by the WebSphere admin if required.

Start WebSphere. Start up using the following command:

/AppServer/bin/startServer.sh (appservername)
example:
/opt/WebSphere/AppServer/bin/startServer.sh server1
ADMU0116I: Tool information is being logged in file
/opt/WebSphere/AppServer/profiles/AppSrv01/logs/server1/startServer.log
ADMU0128I: Starting tool with the AppSrv01 profile
ADMU3100I: Reading configuration for server: server1
ADMU3200I: Server launched. Waiting for initialization status.
ADMU3000I: Server server1 open for e-business; process id is 1827

Log back into the WebSphere Console. A few more changes to the LDAP filters are required.

Expand Security. Click on Secure Administration, application, and infrastructure. Under Available realm definitions, click on Configure.

Next, click under Advanced Lightweight Directory Access protocol (LDAP) user registry settings.

Under General Properties, change the following filters
(This is specific for Sun LDAP using groups)

Group Filter
(&(cn=%v)(objectclass=ldapsubentry)) to
(&(cn=%v)(objectclass=groupofuniquenames))

Group member ID map
nsRole:nsRole to
groupofuniquenames:uniquemember

Click on Apply when completed.

Click on Save to apply changes.

You will need to restart the WebSphere environment again.

./stopServer.sh server1
./startServer.sh server

Next, the snoop servlet will have security added
Log into WebSphere Admin console. http://: 9043/ibm/console/logon.jsp

Expand Applications, select Enterprise Applications. Click on DefaultApplication.

Under Detail Properties, click on Security role to user/group mapping.

By default, snoop has an application role defined named All Role. By having the current mapping to Everyone, there is no requirements for access.

You want to change the setting to only allow users who are members of the cn=WASaccess group. Unselect Everyone?. Click on select and click on Look up groups.

Under Search String enter the fully qualified name of the group we will use to control access to snoop. cn=WASaccess,ou=groups,dc=cg,dc=com

Once it is found, it will show up under Available:
Select the group and using the arrow keys, move it to the Selected: box.

Click on OK when done.

Once you are returned to the Security role to user/group mapping. The Mapped groups should display the selected group. Click on OK.

Click on Save to apply the new settings.

Restart the DefaultApplication by clicking on Stop, and upon completion, Start.

You can now test the WebSphere security by trying to access the snoop servlet.
On a default WebSphere Application, the URL is:
http://:9080/snoop
example: http://slpux01.cg.com:9080/snoop

a basic pop-up window will appear for login. Enter your test ID and password.

Upon successful authentication, you will see the snoop servlet.

You have now concluded protecting snoop servlet using WebSphere Security.

SiteMinder Configurations

The next phase is to configure the SiteMinder Policy Server to create the required objects for the WebSphere Application Server Agent and to create a realm to protect the snoop servlet.

Agent

Create an agent. Example:

WebSphere Agent ACO
Using ApacheDefaultSettings as a template, create a new ACO
Example:

At a minimum, modify or add the following parameters:
challengeforCredentials=NO
By using ‘NO’, only basic auth pop-up will be used if you login directly to the WebSphere application. You can still establish an SMSESSION ahead of time and you will not get a basic auth pop-up when you reach the snoop servlet.
ChallengeforCredentials=YES
By selecting YES, you are able to use forms-based login based on your auth scheme attached to your realms policy.
DefaultAgentName=(same as agent previously created)
FCCCompatMode=NO
LogAppend=YES
Logfile=YES
LogFileName=/opt/smwasasa/logs/ASA.log (or any other appropriate location)

User Directory
Setup the LDAP user directory to be the same as the one being used by WebSphere Security.

You will also need to create some Attribute Mappings to be used by the policies you will create later.

Securing the snoop servlet using EPM. Create an Application protecting /snoop and using the LDAP Directory you defined previously as the shared user store.

Create Application Resource protecting * and assigning GET, POST as the actions.

Create Role based on the Directory mapping you completed earlier. WASaccess with an expression value of TRUE. This will define a role for any users that are members of the WASAccess role which is mapped to the cn=WASaccess group in the user directory.

Create a policy to map the WASAccess role to the snoop Resource.

You have configured the minimum to have a working integration of WebSphere and SiteMinder.

Solaris Configurations

Patch WebSphere’s JAVA with JCE encryption files.

Download and install the Jave JCE jar files.
http://www.ibm.com/developerworks/java/jdk/security/50/

2 jar files are included in the JCE download.
US_export_policy.jar
local_policy.jar

copy these 2 files to
/AppServer/java/jre/lib/security/
example:
/opt/WebSphere/AppServer/java/jre/lib/security/

Set PATH to use WebSphere JAVA
Example:
# echo $PATH
/usr/sbin:/usr/bin
# PATH=/opt/WebSphere/AppServer/java/jre/bin:$PATH
# echo $PATH
/opt/WebSphere/AppServer/java/jre/bin:/usr/sbin:/usr/bin
# which java
/opt/WebSphere/AppServer/java/jre/bin/java
#

Install the WebSphere Application Server Agent

# ./ca-asa-6.0-was-unix.bin –i console

===============================================================================
Choose Install Folder
---------------------

Please choose the folder where the product will be installed.

Where would you like to install?

Default Install Folder: /opt/smwasasa

ENTER AN ABSOLUTE PATH, OR PRESS TO ACCEPT THE DEFAULT
: /opt/smwasasa

INSTALL FOLDER IS: /opt/smwasasa
IS THIS CORRECT? (Y/N): Y

Create Install Directory?
-------------------------
The directory /opt/smwasasa does not exist. Create it?

->1- No, go back
2- Yes, continue

ENTER THE NUMBER OF THE DESIRED CHOICE, OR PRESS TO ACCEPT THE
DEFAULT: 2

===============================================================================
Choose WebSphere Folder
-----------------------

Please enter the folder where WebSphere 6.0 is installed.

Full path (DEFAULT: /opt/WebSphere/AppServer):

Host Registration
-----------------
Would you like to create a trusted host?

1- Yes, create trusted host.
->2- No, use existing file.

ENTER THE NUMBER FOR YOUR CHOICE, OR PRESS TO ACCEPT THE DEFAULT:
: 1

===============================================================================
Host Registration
-----------------

Please enter configuration data.

Policy Server IP Address: (DEFAULT: ): smr12.cg.com

SM Admin Username: (DEFAULT: siteminder):
SM Admin Password: (DEFAULT: ): password

Host Name: (DEFAULT: localhost): slpux01-WAS
Host Config Object: (DEFAULT: ): Development

Agent Configuration
-------------------
Please enter the agent configuration object name.

Agent configuration object name: (DEFAULT: ): slpux01-WAS

Installation Complete
---------------------
Congratulations. CA eTrust SiteMinder Agent v6.0 for WebSphere has been
successfully installed to:

/opt/smwasasa

Install the WebSphere ASA CR

Extract the latest cr available for the WebSphere ASA. For this example:
smasa-6.0-cr006-was.zip is used.

The CR6 contains the following jars:
nete_asa.jar
smagentapi.jar
smwebsphereasa.jar
Java64/sm_jsafe.jar
Java64/sm_jsafeJCE.jar

Copy nete_asa.jar, smagentapi.jar, smwebsphereasa.jar to
/AppServer/lib/ext
example:
/opt/WebSphere/AppServer/lib/ext

Copy sm_jsafe.jar, sm_jsafeJCE.jar to
/AppServer/java/jre/lib/ext
example:
/opt/WebSphere/AppServer/java/jre/lib/ext


Post Install Configurations

Configure the agent modules you need. This example will only implement TAI. As such, the login module and JAAC provider need to be turned off.

Go to
Example:
/opt/smwasasa/conf

Modify the AsaAgent-az.conf file to turn off the WebAgent.

EnableWebAgent="NO"
HostConfigFile="/opt/smwasasa/conf/SmHost.conf"
AgentConfigObject="slpux01-WAS"

Repeat the process for the AsaAgent-auth.conf

EnableWebAgent="NO"
HostConfigFile="/opt/smwasasa/conf/SmHost.conf"
AgentConfigObject="slpux01-WAS"

Only the AsaAgent-assertion.conf should be enabled.

EnableWebAgent="YES"
HostConfigFile="/opt/smwasasa/conf/SmHost.conf"
AgentConfigObject="slpux01-WAS"

Modify the smagent.properties
Change logappend to YES. Makes tailing the log easier.

logfilename="/opt/smwasasa/log/SmWasAsaDefault.log"
loglevel="4"
logappend="YES"
logfile="YES"
logconsole="NO"
smazconf="/opt/smwasasa/conf/AsaAgent-az.conf"
smauthconf="/opt/smwasasa/conf/AsaAgent-auth.conf"
smassertionconf="/opt/smwasasa/conf/AsaAgent-assertion.conf"

Copy the smagent.properties file to
/AppServer/profiles//properties
example:
/opt/WebSphere/AppServer/profiles/AppSrv01/properties

Grant J2SE permissions for jars under by modifying the WebSphere Application server.policy file.

This file is located at /AppServer/profiles//properties
Example:

/opt/WebSphere/AppServer/profiles/AppSrv01/properties

Add the following lines to the bottom of the server.policy file.

grant codeBase "file:/ASA_HOME/lib/-" {

permission java.security.AllPermission;

};


Configure Agent settings on WebSphere Console

Login to WebSphere console. Default URL is
https://:9043/ibm/console/login.jsp

Configure the SiteMinder Agent class loader

Expand the Server tab, click on Application servers.

Click on server1. Under Server Infrastructure, click on Process Definition.

Under Additional Properties, click on Java Virtual Machine.

Under Additional Properties, click on Custom Properties.

Create 2 new variables.
smasa.home=/opt/smwasasa
log4j.ignoreTCL=true

Click on Apply and then Save to apply the changes.

Click on Apply and then Save to apply the changes.

Enable the SiteMinder TAI

Expand Security. Under Authentication, expand Web Security. Click on Trust Association.

Under General Properties, click on Enable trust association. Click on Apply and Save changes.

Return to same screen. Under Additional Properties, click on Interceptors.

Click on New. Enter new Interceptor class name:
com.netegrity.siteminder.websphere.auth.SmTrustAssociationInterceptor

Click on Apply and Save.

You now need to restart the WebSphere Environment. Shut down the WebSphere environment.

/opt/WebSphere/AppServer/bin/stopServer.sh server1

Once the server is completely shut down, clean out any existing WebSphere and ASA logs.

WebSphere logs are located at:
/AppServer/profiles//logs/
example:
/opt/WebSphere/AppServer/profiles/AppSrv01/logs/server1
delete all *.log files

ASA logs are located at:
/log
example:
/opt/smwasasa/log
delete any *.log files.

Start the WebSphere environment
/opt/WebSphere/AppServer/bin/startServer.sh server1

As soon as the WebSphere SystemOut.log is created, start to tail it.
tail –f SystemOut.log

Look for the following message in the SystemOut.log

SMINFO: SiteMinder TAI agent conf file not specified in configuration properties - checking environment
SMINFO: SiteMinder ASA Home 'smasa.home' resolved to: /opt/smwasasa
SMINFO: Configuring SiteMinder TAI with agent conf file = /opt/smwasasa/conf/AsaAgent-assertion.conf
SMINFO: Configuring SiteMinder TAI with processed agent conf file = /opt/smwasasa/conf/AsaAgent-assertion.conf
SMINFO: SiteMinder TAI successfully initialized

Once you get the message:
WSVR0001I: Server server1 open for e-business
The server is up and operational.

Testing the WebSphere SiteMinder Integration.

Open a browser and go to the snoop servet:

http::9080/snoop

If you selected challengeforcredentials=no,
A basic auth popup will appear. Login with your test credentials. The snoop servlet page will be loaded. Look for Client cookies to validate a SMSESSION has been established.

If you configured challengeforcredentials=yes,
You will be re-directed to the location of your login forms web server as defined in your Authentication Scheme.

Once you are authenticated, validate that an SMSESSION is created.

Validate IDs that are not members of the WASAccess group are not allowed to access the snoop servlet.

You should fail to login. Besides a browser error, you should also get an error in the WebSphere SystemOut.log

SECJ0129E: Authorization failed for wsadmin while invoking GET on default_host://snoop, Authorization failed, Not granted any of the required roles: All Role

DONE