DX Docs

isw-kudos · Feb 26, 2024 · ea789ef · ea789ef
1 parent 2069076
commit ea789ef
Show file tree

Hide file tree

Showing 4 changed files with 279 additions and 0 deletions.
diff --git a/docs/boards/dx/OAuthConfig.xml b/docs/boards/dx/OAuthConfig.xml
@@ -0,0 +1,137 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<OAuthServiceConfiguration>
+
+  <!-- Active parameters for in-memory client and token store -->
+	  <parameter name="oauth20.client.provider.classname" type="cc" customizable="false">
+	    <value>com.ibm.ws.security.oauth20.plugins.BaseClientProvider</value>
+	  </parameter>
+	  <parameter name="oauth20.token.cache.classname" type="cc" customizable="false">
+	    <value>com.ibm.ws.security.oauth20.plugins.BaseCache</value>
+	  </parameter>
+	  <parameter name="oauth20.token.cache.jndi.tokens" type="ws" customizable="false">
+	    <value>services/cache/OAuth20MemTokenCache</value>
+	  </parameter>
+	  <parameter name="oauth20.token.cache.jndi.users" type="ws" customizable="false">
+	    <value>services/cache/OAuth20MemTokenOwnerCache</value>
+	  </parameter>
+  <!-- End parameters for in-memory stores -->
+
+  <!-- Example parameters for JDBC database stores
+	  <parameter name="oauth20.client.provider.classname" type="cc" customizable="false">
+	    <value>com.ibm.ws.security.oauth20.plugins.db.CachedDBClientProvider</value>
+	  </parameter>
+	  <parameter name="oauth20.token.cache.classname" type="cc" customizable="false">
+	    <value>com.ibm.ws.security.oauth20.plugins.db.CachedDBTokenStore</value>
+	  </parameter>
+      <parameter name="oauth20.client.cache.seconds" type="cc" customizable="true">
+	    <value>600</value>
+	  </parameter>
+	  <parameter name="oauthjdbc.JDBCProvider" type="ws" customizable="false">
+	    <value>jdbc/oauthProvider</value>
+	  </parameter>
+	  <parameter name="oauthjdbc.client.table" type="ws" customizable="false">
+	    <value>OAuthDBSchema.OAUTH20CLIENTCONFIG</value>
+	  </parameter>
+	  <parameter name="oauthjdbc.token.table" type="ws" customizable="false">
+	    <value>OAuthDBSchema.OAUTH20CACHE</value>
+	  </parameter>
+	  <parameter name="oauthjdbc.CleanupInterval" type="ws" customizable="true">
+	    <value>3600</value>
+	  </parameter>
+	  <parameter name="oauthjdbc.CleanupBatchSize" type="ws" customizable="true">
+	    <value>250</value>
+	  </parameter>
+      <parameter name="oauthjdbc.AlternateSelectCountQuery" type="ws" customizable="false">                                           
+        <value>false</value>                                         
+      </parameter>                                                  
+	  <parameter name="oauth20.db.token.cache.jndi.tokens" type="ws" customizable="false">
+	    <value>services/cache/OAuth20DBTokenCache</value>
+	  </parameter>
+	  <parameter name="oauth20.db.token.cache.jndi.clients" type="ws" customizable="false">
+	    <value>services/cache/OAuth20DBClientCache</value>
+	  </parameter>
+  -->  
+
+  <parameter name="oauth20.max.authorization.grant.lifetime.seconds" type="cc" customizable="true">
+    <value>604800</value>
+  </parameter>
+  <parameter name="oauth20.code.lifetime.seconds" type="cc" customizable="true">
+    <value>60</value>
+  </parameter>
+  <parameter name="oauth20.code.length" type="cc" customizable="true">
+    <value>30</value>
+  </parameter>
+  <parameter name="oauth20.token.lifetime.seconds" type="cc" customizable="true">
+    <value>3600</value>
+  </parameter>
+  <parameter name="oauth20.access.token.length" type="cc" customizable="true">
+    <value>40</value>
+  </parameter>
+  <parameter name="oauth20.issue.refresh.token" type="cc" customizable="true">
+    <value>true</value>
+  </parameter>
+  <parameter name="oauth20.refresh.token.length" type="cc" customizable="true">
+    <value>50</value>
+  </parameter>
+  <parameter name="oauth20.access.tokentypehandler.classname" type="cc" customizable="false">
+    <value>com.ibm.ws.security.oauth20.plugins.BaseTokenHandler</value>
+  </parameter>
+  <parameter name="oauth20.mediator.classnames" type="cc" customizable="false">
+  </parameter>
+  <parameter name="oauth20.allow.public.clients" type="cc" customizable="true">
+    <value>false</value>
+  </parameter>
+  <parameter name="oauth20.grant.types.allowed" type="cc" customizable="false">
+    <value>authorization_code</value>
+    <value>password</value>
+    <value>refresh_token</value>
+    <value>client_credentials</value>
+    <value>implicit</value>
+  </parameter>
+  <parameter name="oauth20.authorization.form.template" type="cc" customizable="true">
+    <value>template.html</value>
+  </parameter>
+  <parameter name="oauth20.authorization.error.template" type="cc" customizable="true">
+    <value></value>
+  </parameter>
+  <parameter name="oauth20.authorization.loginURL" type="cc" customizable="true">
+    <value>login.jsp</value>
+  </parameter>
+  <!-- Optional audit handler, uncomment or add a plugin to enable
+	  <parameter name="oauth20.audithandler.classname" type="cc" customizable="true">
+	  	<value>com.ibm.oauth.core.api.audit.XMLFileOAuthAuditHandler</value>
+	  </parameter>
+	  <parameter name="xmlFileAuditHandler.filename" type="cc" customizable="true">
+	  	<value>D:\oauth20Audit.xml</value>
+	  </parameter>
+  -->
+
+  <!-- Parameters for TAI configuration. These can optionally be added as TAI Custom properties instead, which gives more flexibility. 
+                  Additional custom TAI properties can be added as parameters by specifying type="tai"
+	  <parameter name="filter" type="tai" customizable="true">
+	    <value>request-url%=snoop</value>
+	  </parameter>
+	  <parameter name="oauthOnly" type="tai" customizable="true">
+	    <value>false</value>
+	  </parameter>
+  -->
+
+  <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>
+
+  <!-- mediator for resource owner credential: optional mediator to validate resource owner credential against current active user registry>
+      <parameter name="oauth20.mediator.classnames" type="cc" customizable="true">
+	    <value>com.ibm.ws.security.oauth20.mediator.ResourceOwnerValidationMedidator</value>
+      </parameter>  
+   -->
+
+   <!-- optional limit for the number of tokens a user/client/provider combination can be issued
+       <parameter name="oauth20.token.userClientTokenLimit" type="ws" customizable="true">
+	    <value>100</value>
+      </parameter>  
+   --> 
+</OAuthServiceConfiguration>
diff --git a/docs/boards/dx/haproxy.png b/docs/boards/dx/haproxy.png
diff --git a/docs/boards/dx/index.md b/docs/boards/dx/index.md
@@ -0,0 +1,41 @@
+# Boards for HCL DX
+
+## Prerequisites
+
+1.  HCL DX environment
+1.  Kubernetes environment
+1.  kubectl installed & authenticated
+
+## WebSphere OAuth Config
+
+Please follow the instructions in [WebSphere OAuth Config](./websphere-oauth.md)
+
+## Install Boards portlet
+
+See the [Boards Portlet repository](https://github.com/isw-kudos/boards-portlets/)
+
+### Allow SSO inside Boards frame
+
+Edit the config to include the following,
+
+1.  haproxy.cfg
+
+    Edit the config using the following command
+
+    `kubectl edit configmap <DX_DEPLOYMENT>-haproxy -n <DX_NAMESPACE> -o yaml`
+
+    For example:
+
+    `kubectl edit configmap hcl-dx-dev1-haproxy -n hcl-dx-dev1 -o yaml`
+
+    Add the following line
+
+        http-response replace-header Set-Cookie ^(.*) \1;\ SameSite=None;\ Secure
+
+    For example:
+
+    ![outcome](./haproxy.png)
+
+1.  httpd.conf
+
+        Header edit Set-Cookie ^(.*)$ "$1; Secure; SameSite=None"
diff --git a/docs/boards/dx/websphere-oauth.md b/docs/boards/dx/websphere-oauth.md
@@ -0,0 +1,101 @@
+# 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
+
+## Setup 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 OAuthConfig -fileName /opt/HCL/AppServer/properties/OAuthConfigSample.xml]')
+        AdminConfig.save()
+        quit
+
+1.  Enable Auto Authorize
+
+    Edit the OAuthConfig.xml file which was just created
+
+    `vi /opt/HCL/wp_profile/config/cells/dockerCell/oauth20/OAuthConfig.xml`
+
+        <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>
+
+1.  Restart the WebSphere Application Server
+
+        cd /opt/HCL/AppServer/bin
+        ./stopServer.sh WebSphere_Portal -profileName wp_profile -username wpsadmin -password wpsadmin
+        ./startServer.sh WebSphere_Portal -profileName wp_profile
+
+1.  Check TAI Interceptor properties set
+
+    Global security > Trust association > Interceptors > com.ibm.ws.security.oauth20.tai.OAuthTAI
+
+        provider_1.name=OAuthConfig
+        provider_1.filter=Authorization%=Bearer
+
+## Register OAuth Clients
+
+1.  copy default client definitions
+
+        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](https://www.uuidgenerator.net/). 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/ZHhkZXYxLmlzd2xhYi5uZXQ=/callback" enabled="true">
+        </client>
+
+## 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>
+
+## Enable TAI
+
+1.  Enable OAuth 2.0 TAI
+
+        cd /opt/HCL/AppServer/bin
+        ./wsadmin.sh -lang jython -username <username> -password <password>
+        AdminTask.enableOAuthTAI()
+        AdminConfig.save()
+        quit
+
+1.  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