This article is a follow-on to my previous blog post on configuring SSO on a WebSphere Traditional Application server.
I will now describes how to configure Single Sign On (SSO) with IBM Content Navigator (ICN), Content Services GraphQL (GQL), and Content Platform Engine (CPE) on WebSphere Network Deployment (WAS ND) application server using LTPA, OAuth, or OpenID Connect (OIDC) authentication token mechanisms.
Prior to configuring these SSO solutions, it is assumed that you have already installed the following products with the indicated minimum version:
- WebSphere Network Deployment 9.0.5
- IBM HTTP Server
- IBM FileNet Content Platform Engine 5.5.5
- 5.5.7 required if using IBM Content Services GraphQL
- 5.5.7 IF001 required if using Managed User self-provisioning
- IBM Content Navigator 3.0.8
- IBM Content Services GraphQL 5.5.7
The WebSphere ND deployment topology used in this example is shown in the image below:
The deployment spans 3 machines: IDPMA1
, and IDPMC1
, each hosting a cluster of 2 server instances for the respective application. All requests, both external and internal go through a single webserver
which load-balances the traffic among the servers instances for each application.
In the WAS Admin Console, create the 3 clusters and assign the CE, GQL, and ICN nodes to the respective clusters.
List of servers
To configure ICN and GQL to use LTPA SSO over the WSI transport to the CPE server, perform the following steps.
Enable LTPA on WAS ND Admin Console
- Navigate to: Security > Global security > Single sign-on
- Select all options shown below and fill in the DNS domain name for your servers
Set JVM Options for LTPA
Set the following JVM options on the CPE , ICN, and GQL servers
1. CPE JVM Options
2. ICN JVM Options
3. GQL JVM Options
OAuth / OIDC SSO
Configuration of OAuth 2.0 or OpenID Connect with ICN, GQL, and CPE is basically the same. Any differences are pointed out explicitly in the descriptions in this section.
1. Register CPE, ICN, and GQL servers with OAuth/OIDC Identity Provider
The registration mechanism is dependent on the Identity Provider, but you will need to provide a redirect URL for CPE, ICN, and GQL servers of the form:
- <host> The hostname/IP address of your ICN/External Share/CPE instance
- <port> The port number for the <host>
- <IdpID> The identifier used in the RelyingParty Interceptor settings for your ICN/GQL/CPE instances. For example: provider_1.identifier = ExShareUms
Obtain clientId, clientSecret, and IdP SSL certs as part of this registration process
2. Deploy ICN with Options for SSO support
During deployment of ICN, update the step for Configure the IBM Content Navigator Web Application to use form-based authentication.
Select the Enable OAuth/OIDC Identity Provider support checkbox if an OAuth/OIDC Identity Provider will be used to authenticate users to ICN.
Select the Enable OAuth/OIDC SSO to Content Platform Engine checkbox if CPE will also be configured with OAuth/OIDC support. When this option is selected, OAuth/OIDC SSO will be used between ICN and CPE. Otherwise, LTPA SSO will be used between ICN and CPE.
Set the following Login page URL and Login error page URLs to allow the user to be presented with a login dialog that allows them to select which IdP they want to authenticate with, if multiple are configured.
- Login page URL: /idplogin.jsp
- Login error page URL: /loginError.jsp
3. Install WebSphere OpenID Connect Application
- On WAS ND Admin Console, navigate to Applications > Application Types > WebSphere enterprise applications
- If you don't see the WebSphereOIDCRP application then add it by clicking on the Add... button
- Click Browse
- Enter the path to (WAS_HOME)/installableApps. For example, c:\was90\WebSphere\AppServer\installableApps
- Select WebSphereOIDCRP.ear, then click Open
- Click Next through the subsequent panels, taking all defaults, then click Finish
- Click Save
- Your list of applications should now look like
4. Configure SSL Certificates
- Import the Identity Provider SSL certificates you obtained when registering into the Cell and Node truststores
5. Configure OIDC Trust Association Interceptor on both CPE and ICN tWAS servers
- Navigate to Security > Global security > Authentication > Web and SIP security > Trust association
- Select Enable trust association
- Click on Interceptors link, then click New … and enter Interceptor Class Name: com.ibm.ws.security.oidc.client.RelyingParty
- Navigate to Security > Global security > Custom Properties
- Click New … and define the following custom properties
- Name: com.ibm.websphere.security.InvokeTAIbeforeSSO
- Value: com.ibm.ws.security.oidc.client.RelyingParty
Note: if property exists, add this to existing value, separated by a comma to create a list
- Name: com.ibm.websphere.security.performTAIForUnprotectedURI
- Value: true
6. Add Inbound Trusted Reams for Identity Provider(s)
Navigate to Security > Global security > User account repository > Configure
- Under the Related Items section, click Trusted Authentication Realms - Inbound
- Select Trust realms as indicated below option
- Click Add External Realm… button, and enter realm identifier for each Identity Provider
- The realm identifier name should match the <IdpID> you used when you registered your CPE/ICN instances with the Identity Provider.
7. Update Security Role to Group mapping for CPE, ICN, and GQL applications
- Navigate to Applications > WebSphere enterprise applications > FileNetEngine
- Select the Security role to user/group mappings option
- Change the AllAuthenticated special subject to "All Authenticated in Trusted Realms”
- If you only have a single IdP with a single realm, then change the AllAuthenticated special subject to "All Authenticated in Application's Realm”
- Do the same for the content-graphql-api_war and navigator applications.
8. Update Module mappings for CPE, ICN, GQL, and WebSphereOIDCRP applications
- Navigate to Applications > WebSphere enterprise applications > FileNetEngine
- Select the Manage Modules option
- Select CPECluster and webserver1 for all modules
- Do the same for the content-graphql-api_war application, but choose the GQLCluster and webserver1 for all modules.
- Likewise, for the navigator application, choose the ICNCluster and webserver1 for all modules.
- For the WebSphereOIDCRP application, select all clusters. Don't select webserver1.
9. Enable OIDC across multiple clusters in a cell
When running in a cluster environment, the load balancer needs to use an algorithm that sends requests from the same client to the same cluster member during the initial logon sequence with an identity provider. With IHS, you do this using the Inteligent Management for WebServer Plugin.
- Before enabling Intelligent Management for a web server, disable the dynamic generation of the plugin-cfg.xml file for that web server (e.g. webserver1) by navigating to webserver1 > Plugin properties and un-checking the Automatically generate the plugin-in configuration file option.
- Next navigate to webserver1 > Intellegent Management and Enable it.
. Select your web server and click Generate plug-in.
- Generate the plugin-configuration file
. Select your web server and click Propagate plug-in.
, select your web server, and click Stop, then click Start to start your server again.
See Configuring Intelligent Management for web servers for additional details on setting up Intelligent Management.
10. Configure JVM Options for LTPA/OAuth/OIDC
JVM Options are used to control how users login when there are multiple identity providers available. They are also used to control how authentication tokens (LTPA/OAuth/OIDC) are propagated to the CPE server.
10.1 General JVM Options for ICN/GQL/CPE Servers
- Remove JVM Options (if present for ICN, GQL, and CPE)
- Add JVM Options (for ICN, GQL, and CPE)
10.2 ICN JVM Options for Single Identity Provider Configuration using IdP login page
For a Single IdP, where the IdP contains the same set of users as the LDAP server used by CPE, no additional JVM options are required. Users will automatically be directed to IdP’s login dialog upon accessing ICN for the first time. The image below shows the UMS Identity Provider login dialog.
10.3 ICN JVM Options for Multiple Identity Provider Configuration
For Multiple IdPs, use JVM options to create buttons on ICN login dialog for user to authenticate.
NOTE: JVM values cannot contain spaces
JVM option is populated with a list of the realm names of each identity provider
The com.filenet.authentication.<identity provider>.displayname
JVM option is populated with the name as it appears on the ICN login dialog
The following example shows JVM options for 4 different types of identity providers
- defaultWIMFileBasedRealm - Internal corporate users that also exist in the LDAP server used by CPE.
- UmsManagedUsers - Internal corporate users that do not exist in the LDAP server used by CPE
- ExShareUms - External Share Users using a UMS identity provider
- ExShareGID - External Share users using Google sign-in as the identity provider
These JVM options will cause the ICN login dialog to appear as shown below:
If you want internal corporate users to authenticate using ICN's local LDAP configuration, you can display the direct login fields on the ICN dialog using this JVM option
This will cause the ICN login dialog to appear as shown below:
10.4 Configure JVM options used to control the authentication token propagated to CPE
Applications that use the CE API such as ICN and GQL can control which authentication token gets propagated to CPE if more than one is available after logging into an identity provider. This is done using the com.filenet.authentication.wsi.AuthTokenOrder
An LTPA token is always created by WebSphere, so it is always listed. Either an OAuth or an OIDC token may also be present, depending on the Relying Party Interceptor settings you specify (see later section). If this JVM option is not specified, then the OIDC token is propagated by default.
You might want to change this for one of the following reasons:
- If you are not using the External Share or Managed User features, then LTPA is the simplest. If LTPA is used, then you do not require any of the OAuth/OIDC Relying Party Interception configuration for CPE. However, if you are using the External Share and/or Managed User feature, then you must propagate either the OAuth token or OIDC token since LTPA requires that the user also exist in the WebSphere LDAP server, which would not be the case for these types of users.
- If your IdP only supports either an OAuth or OIDC token, then you must choose between one of these if you are not using LTPA.
- OAuth tokens are smaller in size, so there is less data to transmit. However, OAuth tokens require a round trip to the IdP to validate it for each unique user
- OIDC tokens are signed. Signing key can be retrieved once from IdP and used to validate all OIDC tokens generated by that IdP w/o a separate round-trip for all users
- Remember that some of the Relying Party interceptor configuration settings depend on whether an OAuth or OIDC token is propagated. So if you change it here, remember to change it there as well.
To specify which authentication token is propagated to CPE, set these JVM options on your CPE client application (e.g. ICN or GQL)
- Propagate LTPA token for all IdPs
- -Dcom.filenet.authentication.wsi.AuthTokenOrder=ltpa,oauth or
- Propagate OIDC token for all IdPs
- Explicitly set the Propagation Token for each IdP by using the IdP Identifier as part of the JVM option
11. Relying Party Interceptor Settings
The Relying Party Interceptor settings are used to configure the connection to a given identity provider. This is the most complicated part of OAuth/OIDC configuration in WebSphere since each identity provider may require different configuration values. A full list of these properties can be found in https://www.ibm.com/support/knowledgecenter/en/SSEQTP_9.0.5/com.ibm.websphere.base.doc/ae/csec_oidprop.html.
To get to these settings in the WebSphere admin console, navigate to: Security > Global security > Trust association > Interceptors > com.ibm.ws.security.oidc.client.RelyingParty
- Each distinct identity provider must follow the naming pattern of:
- provider_<n>, where <n> is a number starting at 1 and increments for each additional identity provider.
- All the properties specific to a given identity provider use the same provider_<n> prefix
- Obtain the set of OAuth/OIDC endpoints from IdP
- Note: Discovery endpoint not supported
- The <IdpID> used in the redirect URL registered with the IdP (e.g. https://cpe-host:9443/oidcclient/ExShareUms) corresponds to the identifier in IdP configuration
- provider_1.identifier = ExShareUms
- Use the clientId/clientSecret values obtained during registration with IdP
- If only a single IdP is going to be used, set these properties
- provider_1.useRealm (set for CPE, ICN, and GQL)
- Set to the Realm name under Security > Global security > User account repository
- e.g. provider_1.useRealm =
- provider_1.filter (set for CPE and GQL)
- Set a filter so that all requests with Bearer token will be authenticated using this OAuth/OIDC configuration
- e.g. provider_1.filter = Authorization%=Bearer
- Set a filter to match client requests from a specific authentication realm
- e.g. provider_1.filter = auth-token-realm%=
- provider_1.interceptedPathFilter (set only for ICN)
- Set path filter to navigator application
- e.g. provider_1.interceptedPathFilter = /navigator.*
- If multiple IdPs are going to be used, set these properties
- provider_1.useRealm (set for CPE, ICN, and GQL)
- Set to the same value as identifier
- e.g. provider_1.useRealm = ExShareUms
- For ICN, set filter to match a Cookie with IdP identifier name
- e.g. provider_1.filter = Cookie%=ExShareUms
- For CPE and GQL, set filter to match a http header with IdP identifier name
- e.g. provider_1.filter = auth-token-realm%=ExShareUms
- Set the following properties depending on the type of authentication token being accepted or propagated
- provider_1.useJwtFromRequest (set for CPE, ICN, and GQL)
- For OAuth, set to no
- e.g. provider_1.useJwtFromRequest = no
- For OIDC, set to ifPresent
- e.g. provider_1.useJwtFromRequest = ifPresent
- provider_1.mapIdentityToRegistryUser (ICN only)
- If using LTPA SSO from ICN to CPE, set this property to true
- e.g. provider_1.mapIdentityToRegistryUser = true
- provider_1.verifyIssuerInIat (CPE only, if required by IdP e.g. IbmId)
- For OAuth, set to false
- e.g. provider_1.verifyIssuerInIat = false
- For OIDC, set to true
- e.g. provider_1.verifyIssuerInIat = true
- Set this property to enable OIDC across multiple clusters when authenticating to an identity provider. This should be set browser based clients such as ICN and CS GraphQL when using the interactive user interface.
12. Example Relying Party Interceptor Settings
The following sections demonstrate settings for different identity providers and different applications (i.e. CPE, ICN, or CS GraphQL).
The primary difference for each of these providers is the filter
. The filter is used to select which identity provider configuration to use for a given incoming request.
When the ICN IdP login dialog is used, a cookie
is set that contains the name of the authentication realm. Hence, each of the ICN provider settings use a filter based on a cookie value that identifies the authentication realm.
CPE and the CS GraphQL API expect a Bearer token to be propagated on the HTTP Authorization header along with a special header set by the CE API that specifies the authentication realm. Hence, these provider settings use a filter based on the auth-token-realm
HTTP header value.
The authentication realms in this example are:
- - Realm that corresponds to the ldap server defined in WebSphere that is used in CPE/ICN/GQL for users internal to the organization (e.g. employees)
- - Realm that does not use an ldap server for users internal to the organization (e.g. employees). Instead, as users log in, they are self-provisioned
- ExShareUMS - Realm for users outside the organization (e.g. non-employees) that are authenticated with a UMS identity provider. These are users to whom documents are shared with using the External Share feature.
- ExShareGID - Realm for users outside the organization (e.g. non-employees) that are authenticated with Google Sign In These are users to whom documents are shared with using the External Share feature.
Below is a summary of each of the provider examples along with its authentication realm and the OAuth/OIDC clientId registered with the Identity Provider. Note that the clientId might be specified by the Identity Provider (e.g. Google Sign-In) or you may specify your own value as part of registering the application with the identity provider.