Configuring WebSphere Application Server for OAuth/OIDC

You perform configuration steps to prepare your WebSphere Application Server for an OAuth/OIDC integration. These steps must be performed on both the instance of WebSphere Application Server for Content Platform Engine and on the instance for IBM® Content Navigator.

Before you begin

The OAuth/OIDC configuration requires that your WebSphere Application Server 9.0.5 includes Interim Fix 3 (or later). See the Software Product Compatibility Report for more information.

Procedure

To configure WebSphere Application Server for OAuth/OIDC:

Configure the JVM options:
1. In the WebSphere Administration Console, navigate to your server, and expand Java and Process Management.
2. Under Additional Properties, click Java Virtual Machine.
3. Scroll down to locate the text box for Generic JVM arguments.
4. Make the following updates for your instances:
- On the Content Platform Engine instance, add the following option if it is not already included:
```
-Dcom.filenet.authentication.wsi.AutoDetectAuthToken=true
```
  Remove the following options:
```
-Dcom.filenet.authentication.token.userid=sso:ltpa 
-DFileNet.WSI.custom.credential.class=com.filenet.apiimpl.wsi.WSICredential 
```
- On the IBM Content Navigator instance, remove the following arguments:
```
-Dcom.filenet.authentication.token.userid=sso:ltpa 
-DFileNet.WSI.AutoDetectLTPAToken=true
```
  Add the following arguments if not already included:
```
-Djaxws.payload.highFidelity=true
-Dcom.filenet.authentication.wsi.AutoDetectAuthToken=true 
-Dcom.filenet.repositoryconfig.allowWSIOnWAS=true
-Dcom.filenet.authentication.displayLdapLoginControls=true
```
  Note: com.filenet.authentication.wsi.AuthTokenOrder specifies which authentication token to send to the Content Platform Engine server if multiple tokens are available. An LTPA token is always created by WebSphere Application Server, so it is specified last. For a given Identity Provider, either OAuth or OIDC can be configured; specify the desired authentication token type to use first. OAuth is preferable in most cases, since it has a smaller token size.
  If you are using more than one identity provider, specify these additional JVM arguments:
```
-Dcom.filenet.authentication.providers=ExShareUms,ExShareGID,ExShareIbmId 
-Dcom.filenet.authentication.ExShareUms.displayname=UMS-External 
-Dcom.filenet.authentication.ExShareGID.displayname=Google-Sign-In 
-Dcom.filenet.authentication.ExShareIbmId.displayname=IBM-Id
-Dcom.filenet.authentication.ExShareGID.AuthTokenOrder=oidc,ltpa
```
  Note:
  - The displayname values cannot contain any spaces.
  - Because Google Sign-in must use OIDC rather than OAuth, setting a JVM argument using its providerId overrides the default com.filenet.authentication.wsi.AuthTokenOrder.
Install the OIDC TAI application on your WebSphere Application Server.
Check the list at Applications > Application Types > WebSphere Enterprise Applications for WebSphereOIDCRP.ear. If you do not see the EAR file in the application list, continue with the installation steps.
1. Navigate to the app_server_root/bin directory, for example, /opt/IBM/WebSphere/AppServer/bin.
2. Run the installOIDCRP.py script for each profile where you want install the OpenID Connect RP.
  For example:
```
cd <install_root>/bin ./wsadmin.sh -profileName AppSrv01 -f installOIDCRP.py install nodeName serverName
```
  For a cluster environment, use a command like the following example:
```
./wsadmin.sh -f installOIDCRP.py install clusterName
```
  where:
  - profileName is the profile name of the target application server.
  - nodeName is the node name of the target application server.
  - serverName is the server name of the target application server.
  - clusterName is the name of the cluster where you want to install OpenID Connect RP.
Configure the OIDC TAI for the Identity Provider.
1. Navigate to Security > Global security.
2. Under Authentication, go to Web and SIP security > Trust assocation.
3. If it is unchecked, click to check Enable trust association, and click Apply.
Confirm the Interceptor class name:
1. Click Interceptors.
2. If com.ibm.ws.security.oidc.client.RelyingParty is not listed, click New and enter the following value for the Interceptor class name:
  com.ibm.ws.security.oidc.client.RelyingParty
3. Click Apply.
4. Provide the appropriate values for the com.ibm.ws.security.oidc.client.RelyingParty Interceptor class:
  For the class values to set on the Content Platform Engine WebSphere instance, see Content Platform Engine RelyingParty Interceptor settings.
  For the class values to set on the IBM Content Navigator WebSphere instance, see IBM Content Navigator RelyingParty Interceptor settings.
Add Global Security custom properties for TAI:
1. Click Security > Global security and then click Custom properties.
2. Click New and define the following custom property information under General properties:
  - Name: com.ibm.websphere.security.InvokeTAIbeforeSSO
  - Value: com.ibm.ws.security.oidc.client.RelyingParty
    If this property is already defined, then add com.ibm.ws.security.oidc.client.RelyingParty to the existing value, separated by a comma to create a list.
3. Click New and define the following custom property information under General properties:
  - Name: com.ibm.websphere.security.performTAIForUnprotectedURI
  - Value: true
(Required if you have more than one Identity Provider) Add the Identity Provider realm as a WebSphere Application Server trusted realm:
1. Navigate to Security > Global security.
2. Under User account repository, click Configure.
3. Under Related items, click Trusted Authentication Realms - Inbound.
4. Click Add External Realm and enter one of the following choices:
  - For Google, use: ExShareGID
  - For IBM Id, use: ExShareIbmId
  - For UMS, value is dependent on the LDAP realm that is configured on UMS, for example: ExShareUms
(On the Content Platform Engine instance only) Change the mapping settings for the AllAuthenticated special subject:
1. In the WebSphere Application Server Administration Console, go to Enterprise applications > FileNetEngine > Security role to user/group mapping.
2. In the list, select the All Authenticated role.
3. In the Map Special Subjects drop down menu, change the setting as follows:
  - For a single IDP with a single realm, change the setting to All Authenticated in Application's Realm.
  - For multiple IDPs, change the setting to All Authenticated in Trusted Realms.
4. Save your changes, then stop and restart the FileNetEngine application.
Obtain the SSL certificate from your identity provider.

On both the IBM Content Navigator server and the Content Platform Engine server, use the following commands to import the identity provider certificates into the trust store:

Change to the directory that contains the trust store:

Content Platform Engine:

cd /opt/IBM/WebSphere/AppServer/profiles/AppSrv01/config/cells/ESCPE1Node01Cell/nodes/ESCPE1Node01

IBM Content Navigator:

cd /opt/IBM/WebSphere/AppServer/profiles/AppSrv01/config/cells/ESICN1Node01Cell/nodes/ESICN1Node01

Import the identity provider certificate:

UMS:

/opt/IBM/WebSphere/AppServer/java/8.0/bin/keytool -importcert -keystore trust.p12 -storetype pkcs12 -storepass pword -alias ums -file umscert.pem

Google Sign-in:

/opt/IBM/WebSphere/AppServer/java/8.0/bin/keytool -importcert -keystore trust.p12 -storetype pkcs12 -storepass pword -alias globalsignrootca -file globalsignrootca.crt

IBM ID:

/opt/IBM/WebSphere/AppServer/java/8.0/bin/keytool -importcert -keystore trust.p12 -storetype pkcs12 -storepass pword -alias digicert-root -file digicert-root.pem
/opt/IBM/WebSphere/AppServer/java/8.0/bin/keytool -importcert -keystore trust.p12 -storetype pkcs12 -storepass pword -alias digicert-subca -file digicert-subca.pem
/opt/IBM/WebSphere/AppServer/java/8.0/bin/keytool -importcert -keystore trust.p12 -storetype pkcs12 -storepass pword -alias prepiam_toronto_ca_ibm_com -file prepiam_toronto_ca_ibm_com.crt

Verify that the certificates exist in the trust store:

/opt/IBM/WebSphere/AppServer/java/8.0/bin/keytool -list -keystore trust.p12 -storetype pkcs12 -storepass pword