WebSphere OAuth Config

OAuth must be configured in IBM WebSphere for Boards to authenticate with HCL DX.

Tip

Remember to replace <username> & <password> with valid credentials

Connect to the core server, e.g on Kubernetes:

kubectl exec -it hcl-dx-dev1-core-0 core -n hcl-dx-dev1 -- sh

Create Service Provider

Note

This step is based on the IBM WebSphere documentation - Creating an OAuth service provider.

1. Create the OAuth provider by using the wsadmin utility

   cd /opt/HCL/AppServer/bin
   ./wsadmin.sh -lang jython -username <username> -password <password>
   
   AdminTask.createOAuthProvider('[-providerName <OAuthProviderName> -fileName <ProviderConfigFile>]')
   

   Where:

   • <OAuthProviderName> is the OAuth provider name (typically OAuthConfig)
   • <ProviderConfigFile> is the full path to the OAuth provider configuration file. Please download and use this DXProvider.xml configuration file which includes Auto Authorize setup for the huddoboards client.

   Tip

   The supplied DXProvider.xml file uses an in-memory store for token storage. You may choose to enable a JDBC database store instead.

   For example:

   AdminTask.createOAuthProvider('[-providerName OAuthConfig -fileName /opt/HCL/AppServer/properties/DXProvider.xml]')
   AdminConfig.save()
   quit
   

   This should copy the configuration file to <was_profile_root>/config/cells/<cell_name>/oauth20

   Please confirm this file exists, e.g. /opt/HCL/wp_profile/config/cells/dockerCell/oauth20/OAuthConfig.xml

2. Restart the WebSphere Application Server

   cd /opt/HCL/AppServer/bin
   ./stopServer.sh WebSphere_Portal -profileName wp_profile -username <username> -password <password>
   ./startServer.sh WebSphere_Portal -profileName wp_profile
   

Configure TAI properties

1. Open the ISC

   Click Global security, expand Web and SIP security, click Trust association

   

2. Click Interceptors

   

3. Ensure that com.ibm.ws.security.oauth20.tai.OAuthTAI exists

   

   If not, click New enter the Interceptor class name com.ibm.ws.security.oauth20.tai.OAuthTAI, and click OK

4. Update the custom properties to match:

   provider_1.name=OAuthConfig
   provider_1.filter=Authorization%=Bearer
   

   For example:

   

Register OAuth Client

Note

This step is based on the IBM WebSphere documentation - Creating an OAuth service provider.

1. Copy default client definitions

   cp <app_server_root>/properties/base.clients.xml <was_profile_root>/config/cells/<cell_name>/oauth20oauth20/
   

   For example:

   cp /opt/HCL/AppServer/properties/base.clients.xml /opt/HCL/wp_profile/config/cells/dockerCell/oauth20/
   

2. Edit file to include Huddo Boards client

   vi /opt/HCL/wp_profile/config/cells/dockerCell/oauth20/base.clients.xml

   <client id="huddoboards" component="<OAUTH_PROVIDER_NAME>" secret="<OAUTH_SECRET>" displayname="Huddo Boards" redirect="https://<BOARDS_URL>/auth/dx/<BASE_64_ENCODED_DX_HOSTNAME>/callback" enabled="true">
   </client>
   

   Where:

   • <OAUTH_PROVIDER_NAME> is the name of the Provider specified above, typically OAuthConfig
   • <OAUTH_SECRET> is a complex, random secret, e.g. a UUID. This will be required later.
   • <BOARDS_URL> is the URL of the Boards deployment, e.g. company.example.com/boards or boards.company.com
   • <BASE_64_ENCODED_DX_HOSTNAME> is a base64(dx-hostname) encoded string

   For example:

   <client id="huddoboards" component="OAuthConfig" secret="a2e3d8c3-7875-4512-a0da-8b5fd61f2245" displayname="Huddo Boards" redirect="https://boards.huddo.com/auth/dx/ZHguY29tcGFueS5jb20=/callback" enabled="true">
   </client>
   

Install OAuth Application

Note

This step is based on the IBM documentation - Enabling your system to use the OAuth 2.0 feature.

1. Install the OAuth 2.0 service provider application

   cd /opt/HCL/AppServer/bin
   ./wsadmin.sh -f ./installOAuth2Service.py install dockerNode WebSphere_Portal -profileName wp_profile -username <username> -password <password>
   

2. Enable OAuth 2.0 TAI

   cd /opt/HCL/AppServer/bin
   ./wsadmin.sh -lang jython -username <username> -password <password>
   AdminTask.enableOAuthTAI()
   AdminConfig.save()
   quit
   

3. Restart the WebSphere Application Server

   cd /opt/HCL/AppServer/bin
   ./stopServer.sh WebSphere_Portal -profileName wp_profile -username <username> -password <password>
   ./startServer.sh WebSphere_Portal -profileName wp_profile
   

---

Troubleshooting

Issue: SSL Error

ServletWrapper service CWSRV0014E: Uncaught service() exception root cause OAuth20EndpointServlet: javax.net.ssl.SSLHandshakeException: com.ibm.jsse2.util.j: PKIX path building failed: com.ibm.security.cert.IBMCertPathBuilderException: unable to find valid certification path to requested target

Resolution: Import the self-signed certificate into the WebSphere ISC