Type of Submission: Article

Title: Configuring IBM Case Manager/ Content Navigator for SAML Single Sign-on
Subtitle: Deploying P8 Application using FileNet Deployment Manager

Keywords: SAML, Case Manager, Content Navigator, Single Sign-on, SSO, WebSphere, ACS,
TAI

Prefix:
Given: Manoj
Middle: K.
Family: Khilnani
Suffix:

Job Title: Senior Managing Consultant

Email: mkhilnan@us.ibm.com
Bio: Manoj Khilnani is a Senior Managing Consultant working with IBM Software Services for
Federal (ISSF). He is a certified IT Specialist and WebSphere and ECM Consultant. He has 16
years of software development life-cycle experience. In the last few years, he has extensively
worked on ECM products and Single Sign-on security for FileNet P8.

Company: IBM

Abstract: SAML (Security Assertion XML Language) is an open standard format for
exchanging authentication and authorization data between different providers. In the
enterprise world, the customers require single sign-on across all the applications
irrespective of the implementation details. SAML being open source and XML based
fits this requirement. The IBM Case Manager and Content Navigator are applications
that run on WebSphere Application Server. This allows the Case manager to leverage
any Single Sign-on capabilites provided by WebSphere. WebSphere Application Server
acts as a Service Provider in the SAML Sign-on environment. It depends on Identity
Provider to authenticate the user and send the SAML XML assertion for consumption.
This article describes the steps to achieve a successful SAML based Case manager
application configuration.

Page 1 of 14
1. Introduction ............................................................................................................. 3
2. Planning.................................................................................................................. 4
2.1 Pre-Requisities ................................................................................................................................ 4
2.2 Send ICN Service Provider Information to the Identity Provider ..................................................... 4
2.3 Collect Identity Provider Metadata file ............................................................................................ 4
3. Installing SAML ACS Application ............................................................................ 5
3.1 Verify the Security ........................................................................................................................... 5
3.2 Install SAML ACS application into ICN Server ............................................................................... 5
3.3 Map WebSphereSamlSP Application ............................................................................................. 5
4. Configure SAML TAI ............................................................................................... 6
4.1 Enable SAML TAI SSO ................................................................................................................... 6
4.2 Validate SAML TAI SSO Initial Setup ............................................................................................. 6
4.3 Configure WAS as SP partner: ....................................................................................................... 7
4.3.1 Add identity provider using metadata of the IdP ........................................................................ 7
4.4 Add IdP realms to the list of inbound trusted realms ...................................................................... 8
4.5 Configure SAML TAI SSO Additional Parameters .......................................................................... 8
4.6 Export WAS SP Metadata file: ...................................................................................................... 10
5. Redeploy ICN ....................................................................................................... 11
6. UnRestricted JCE Policy Files .............................................................................. 12
7. Tracing.................................................................................................................. 13
8. References ........................................................................................................... 14

Page 2 of 14
1. Introduction
This document describes the procedure for SAML TAI configuration of IBM Case Manager which runs on
WebSphere 8.5.
SAML Web SSO feature requires SAML Assertion Consumer Service (ACS) application and enabling SAML
TAI. The WebSphere can only act as a SAML Service Provider (SP) and not an Identity Provide (IdP).

WebSphere only supports IdP-initiated SSO and bookmark-style SP-initiated SSO. The below diagram shows
the WebSphere as bookmark-style SP-initiated SSO

Page 3 of 14
2. Planning

2.1 Pre-Requisities

• IBM Case Manager is installed and configured

• SSL is configured for the IBM Case Manager
Verify the SSL URL: https://<loadbalancer_icnserver>/navigator/?desktop=icm

2.2 Collect Identity Provider Metadata file

Collect the below identity provider (IdP) information

• IdP metadata file
• IdP URL: This url will allow the user to authenticate and redirect back to the WAS Service Provider
(SP) target application URL
Example:
https://<IDP_Host>/<URL>?PartnerSpId=https://<loadbalancer_icnserver>
/samlsps/WASSSO&RelayState=https://<loadbalancer_icnserver>/navigator/?dekstop=icm

2.3 Send ICN Service Provider Information to the Identity Provider

If required send below information to the Identity provider

• Entity ID of your Service provider
• Assertion Consumer Service (ACS )URL.
By default both are same values https://<was host>:<port>/samlsps/<random name>
e.g. https://<loadbalancer_icnserver>/samlsps/WASSSO
samlsps is WAS ACS application which will be deployed on the ICN cluster and
served by the load balancer.

Page 4 of 14
3. Installing SAML ACS Application

3.1 Verify the Security

1. Login to the WAS administrative console using admin id and password.
2. Navigate to Security > Global Security.
3. Verify that the Administrative security and Application security are turned on.
4. Click Logout

3.2 Install SAML ACS application into ICN Server

1. Open command prompt and go to appserver profile bin directory
> cd c:\IBM\WebSphere\AppServer\bin
2. Verify that the cluster/servers are started where we plan to install the ACS application
3. Execute the install SAML ACS script (installSamlACS.py)
Single Node installation

wsadmin -f C:\IBM\WebSphere\AppServer\bin\installSamlACS.py install <NodeName> server1 -
username <wasadmin> -password <wasadmin password>

Cluster installation

wsadmin -f C:\IBM\WebSphere\AppServer\bin\installSamlACS.py install <ClusterName> -
username <wasadmin> -password <wasadmin password>

Verify the success message

ADMA5013I: Application WebSphereSamlSP installed successfully.

3.3 Map WebSphereSamlSP Application

1. Login to the WAS administrative console using admin id and password.
2. Go to the WebSphereSamlSP Application
3. Click Manage Modules
4. Modify the mapping to required clusters and web servers
5. Regenerate web server plugin
6. Restart web servers

Page 5 of 14
4. Configure SAML TAI

4.1 Enable SAML TAI SSO

1. Open command prompt and go to dmgr or appserver profile bin directory
> cd c:\IBM\WebSphere\AppServer\profiles\Dmgr01\bin
2. Go to wsadmin prompt
> ./wsadmin.sh –lang jython
Enter user id and password
3. Enable the SAML Trust Authentication Interceptor from wsadmin prompt
wsadmin> AdminTask.addSAMLTAISSO('-enable true –acsUrl
https://<hostname>:<sslport>/samlsps/WASSSO')
Single Node Installation: hostname is the host name of the system where WebSphere Application is
installed and sslport is the Web server SSL port number (WC_defaulthost_secure).
Cluster installation: hostname is the load balancer which serves the ICN cluster and sslport is the
load balancer SSL port number

wsadmin> AdminConfig.save()
wsadmin> quit

4. Restart the ICN cluster/application servers

4.2 Validate SAML TAI SSO Initial Setup

1. Login to the WAS administrative console using admin id and password.

2. Navigate to Security > Global Security.
3. Expand Web and SPI Security
4. Click Trust Association
5. Verify the Enable trust association is enabled
6. Click Interceptors
7. Click com.ibm.ws.security.web.saml.ACSTrustAssociationInterceptor
8. Verify the 2 parameters
a. sso_1.sp.acsUrl: https://<loadbalancer_icnserver>/samlsps/WASSSO

Page 6 of 14
 b. sso_1.sp.idMap: localRealm
idAssertion - the user specified in the SAML assertion is not checked in the local registry
localRealm - the user specified in the SAML assertion is verified in the local registry
localRealmThenAssertion - the user specified in the SAML assertion is first checked in the local registry,
if it does not exist, WAS proceed with idAssertion.

9. Navigate to Security > Global Security.

10. Click custom properties
11. Verify and update the 2 parameters
a. com.ibm.websphere.security.DeferTAItoSSO :
com.ibm.ws.security.web.saml.ACSTrustAssociationInterceptor
b. com.ibm.websphere.security.InvokeTAIbeforeSSO :
com.ibm.ws.security.web.saml.ACSTrustAssociationInterceptor
Avoid trouble: The property com.ibm.websphere.security.DeferTAItoSSO, was previously used in the
default configuration of all installed servers. Now it is only used as part of the SAML configuration.
Therefore, even if this property already exists in your system configuration, you must change its
value to com.ibm.ws.security.web.saml.ACSTrustAssociationInterceptor. Multiple
values, separated with commas, cannot be specified for this property. It must be set to a single SAML
TAI.

4.3 Configure WAS as SP partner:

4.3.1 Add identity provider using metadata of the IdP

1. Open command prompt and go to dmgr or appserver profile bin directory
> cd c:\IBM\WebSphere\AppServer\profiles\Dmgr01\bin
2. Go to wsadmin prompt
> wsadmin –lang jython
Enter user id and password
3. Import IdP Metadata file from wsadmin prompt
wsadmin> AdminTask.importSAMLIdpMetadata('-idpMetadataFileName <IdPMetaDataFile> -idpId 1 -
ssoId 1 -signingCertAlias <idpAlias>')
where IdpMetaDataFile is the full path name of the IdP metadata file, and IdpAlias is any alias name
that you specify for the imported certificate.
idpAlias= SAMLSignerCert
wsadmin> AdminConfig.save()
wsadmin> quit
4. Restart the cluster/application server s

Page 7 of 14
Verify: The signer cert (SAMLSignerCert) is added to the NodeDefaultTrustStore.

4.4 Add IdP realms to the list of inbound trusted realms

For each Identity provider that is used with your WebSphere Application Server service provider, you must
grant inbound trust to all the realms that are used by the identity provider.

1. Login to the WAS administrative console using admin id and password.

2. Navigate to Security > Global Security.
3. Under user account repository, click Configure.
4. Click Trusted authentication realms - inbound.
5. Click Add External Realm.
6. Fill in the IdP external realm name.
7. Click OK and Save changes to the master configuration.

4.5 Configure SAML TAI SSO Additional Parameters

1. Login to the WAS administrative console using admin id and password.

2. Navigate to Security > Global Security.
3. Expand Web and SPI Security
4. Click Trust Association
5. Verify the Enable trust association is enabled
6. Click Interceptors
7. Click com.ibm.ws.security.web.saml.ACSTrustAssociationInterceptor
8. Add the below additional parameters
a. sso_1.sp.targetUrl= https://<loadbalancer_icnserver> /navigator/?desktop=icm
Default target URL after successful validation of the SAMLResponse when there is no RelayState
SAML attribute received from the IdP.
b. sso_1.sp.useRelayStateForTarget = false
The above attribute will force WebSphere not to use the SAML Attribute RelayState. The target URL
will be the original user URL that is stored in the WasSamlSpReqURL cookie. If the cookie does not
exist it will use sso_1.sp.targetUrl.

Note: This will allow the end user to access any desktop URL and after SAML authentication will be
redirected back to that initial desktop URL
c. sso_1.sp.trustStore

Page 8 of 14
 This property specifies the truststore for validating the SAML signature. It specifies the name of a
managed keystore.
Example: NodeDefaultTrustStore
d. sso_1.sp.keyStore
This property specifies the keystore that contains the private key for decrypting the encrypted SAML
assertion.
Example: NodeDefaultKeyStore
e. sso_1.sp.keyName
This property specifies the key name for decrypting the SAML assertion.
This is the cert that will be presented to Idp
Example: default
f. sso_1.sp.keyPassword
Keystore password: Default for NodeKeyStore is WebAS. This property specifies the key password
for decrypting the SAML assertion.
Example: changeit
g. sso_1.sp.keyAlias
This property specifies the key alias for decrypting the SAML assertion.
This is the cert that will be presented to Idp
Example: default
h. sso_1.sp.login.error.page
This property specifies the error page, IdP login page, or custom mapping class to which an
unauthenticated client request is redirected.
Example:
https://<IDP_Host>/<URL>?PartnerSpId=https://<loadbalancer_icnserver>
/samlsps/WASSSO&RelayState=https://<loadbalancer_icnserver>/navigator/?dekstop=icm
i. sso_1.sp.filter= request-url%=navigator
This property will redirect user to the login error page only when the URL contains navigator.
------------Below are optional ----------------
j. sso_1.sp.uniqueId
Example: uid
By default the NameID field in the SAML Response is set as the userid in the JAAS Subject. If this
needs to be changed, update the uniqueId and principlName
k. sso_1.sp.principalName
Example: uid

9. Save and Logout

Page 9 of 14
4.6 Export WAS SP Metadata file:
Each identity provider that is used with your WebSphere Application Server service provider needs to be
configured to add the service provider as an SSO partner. The procedure for adding the service provider
partner to an identity provider depends on the specific identity provider. You can either export the WebSphere
Application Server service provider metadata, and import it to the identity provider, or manually configure the
identity provider to add the service provider.

1. Open command prompt and go to appserver profile bin directory

> cd c:\IBM\WebSphere\AppServer\profiles\Dmgr01\bin
2. Go to wsadmin prompt
> wsadmin –lang jython
Enter user id and password
3. Export SP SAML Metadata from wsadmin prompt
wsadmin> AdminTask.exportSAMLSpMetadata('-spMetadataFileName c:/tmp/spdata.xml -ssoId 1')
wsadmin> quit

If the SAML token is encrypted, you must provide the public key certificate that you want the identity
provider to use for encrypting the SAML token, and the certificate must exist in the WebSphere
Application Server default KeyStore before performing an export.

Page 10 of 14
5. Redeploy ICN

ICN application needs to be reconfigured for Content Navigator authentication to either Application server
authentication or Application server Form-based authentication.
• Open the BM Content Navigator Configuration and Deployment Tool
• Configure the IBM Content Navigator Web Application task
o Select Application server authentication for the IBM Content Navigator authentication
option. This option configures IBM Content Navigator for federated SSO by using SAML.

• Run the ‘Build the web application’ task

• Run the ‘Deploy the web application on WAS’ task
• Restart the cluster/application servers where IBM Content Navigator is deployed.

Page 11 of 14
6. UnRestricted JCE Policy Files
By default, the Java Cryptography Extension (JCE) is shipped with restricted or limited strength
ciphers. To use 192-bit and 256-bit Advanced Encryption Standard (AES) encryption algorithms,
you must apply unlimited jurisdiction policy files.

If the Identity Provider uses strong encryption of AES 192 or 256, download the unrestricted JCE policy files
for WebSphere JRE from https://www14.software.ibm.com/webapp/iwm/web/preLogin.do?source=jcesdk

Note: Verify the WebSphere java version and download the correct policy files.

Refer
http://www-01.ibm.com/support/docview.wss?uid=swg21245273
http://www.ibm.com/developerworks/java/jdk/security/index.html
https://www14.software.ibm.com/webapp/iwm/web/preLogin.do?source=jcesdk

Download the Unrestricted SDK JCE Policy files for older versions of the SDK
• Replace the below files in /opt/IBM/WebSphere/AppServer/java/jre/lib/security with permissions 755
o local_policy.jar
o US_export_policy.jar

If the above is not performed then we might encounter the below error
[4/8/14 10:32:24:661 GMT-07:00] 00000094 EncryptedData E CWWSS5601E: The following exception
occured while decrypting the message: java.lang.RuntimeException: java.security.InvalidKeyException:
Illegal key size
at
com.ibm.ws.wssecurity.xml.xss4j.enc.EncryptionEngineImpl$AESCBC.removeIv(EncryptionEngineImpl.java:
1463)

Page 12 of 14
7. Tracing

• Enable trace specifications:

o com.ibm.ws.security.*
o com.ibm.ws.security.web.saml.*

Note:

*=info:com.ibm.ws.security.*=all:com.ibm.websphere.security.*=all:com.ibm.websphere.wim.*=all
:com.ibm.wsspi.wim.*=all:com.ibm.ws.wim.*=all:com.ibm.wsspi.wssecurity.*=all:com.ibm.ws.wssecurity.*=all

• Use HTTPS Web Debugging to verify the SAML request/response flow. (e.g. Fiddler tool)

• For Java issues

o Javax.net.debug = true
o Application servers > > Java and Process Management > Process Definition > Java
Virtual Machine > Custom Properties
and create a new property with name "javax.net.debug" and set value "true"
o Log Files SystemOut.log and trace:
/opt/IBM/WebSphere/AppServer/profiles/AppSrv01/logs/server1

Page 13 of 14
8. References
• Configuring Single sign-on for ICN
• Enabling your system to use the SAML web single sign-on (SSO) feature
http://pic.dhe.ibm.com/infocenter/wasinfo/v8r5/index.jsp?topic=%2Fcom.ibm.websphere.nd.multiplatform.doc
%2Fae%2Ftwbs_enablesamlsso.html
• Configuring single sign-on (SSO) partners
http://pic.dhe.ibm.com/infocenter/wasinfo/v8r5/topic/com.ibm.websphere.nd.multiplatform.doc/ae/twbs_config
uresamlssopartners.html
• Adding SAML web single sign-on (SSO) trust association interceptor (TAI) using the wsadmin
command-line utility
http://pic.dhe.ibm.com/infocenter/wasinfo/v8r5/topic/com.ibm.websphere.nd.multiplatform.doc/ae/twbs_addsa
mltaisso.html
• Understanding the WebSphere Application Server SAML Trust Association Interceptor
http://www.ibm.com/developerworks/websphere/techjournal/1307_lansche/1307_lansche.html
• SAML web single sign-on (SSO) trust association interceptor (TAI) custom properties
http://pic.dhe.ibm.com/infocenter/wasinfo/v8r5/topic/com.ibm.websphere.nd.multiplatform.doc/ae/rwbs_samlt
aiproperties.html

• SAML single sign-on scenarios, features, and limitations

http://pic.dhe.ibm.com/infocenter/wasinfo/v8r5/index.jsp?topic=%2Fcom.ibm.websphere.nd.doc%2Fae%2Fc
wbs_samlssosummary.html

• Use SAML assertions from an application server acting as an identity provider

http://www.ibm.com/developerworks/library/se-sso/

• OASIS Interoperable SAML 2.0 Web Browser SSO Profile

http://saml2int.org/profile/current

• Security Assertion Markup Language (SAML) V2.0 Technical Overview

https://www.oasis-open.org/committees/download.php/27819/

Page 14 of 14