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. There should be a default file called OAuthConfigSample.xml in the <app_server_root>/properties directory. Please confirm the location of this file on your system.

   For example:

   AdminTask.createOAuthProvider('[-providerName OAuthConfig -fileName /opt/HCL/AppServer/properties/OAuthConfigSample.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. Enable Auto Authorize

   Edit the OAuthConfig.xml file which was just created. For a full list of supported options see the IBM WebSphere documentation.

   vi <was_profile_root>/config/cells/<cell_name>/oauth20

   For example:

   vi /opt/HCL/wp_profile/config/cells/dockerCell/oauth20/OAuthConfig.xml

   Add/update the following parameters:

   <parameter name="oauth20.autoauthorize.param" type="ws" customizable="false">
       <value>autoauthz</value>
   </parameter>
   <parameter name="oauth20.autoauthorize.clients" type="ws" customizable="true">
       <value>huddoboards</value>
   </parameter>
   

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
   

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