How To
Summary
You can configure the IBM Process Federation Server that is deployed as part of IBM Cloud Pak for Business Automation with Platform UI service enabled to federate on-premise IBM Business Automation Workflow or IBM Business Process Manager systems, providing those systems support Platform UI Zen tokens for authentication.
Steps
To configure each on-premise system, follow these steps:
- Enable indexing on the on-premise IBM Business Automation Workflow system.
- Configure the on-premise IBM Business Automation Workflow system to authenticate incoming requests with Portal UI JSON Web Tokens.
- Provide self-signed certificates of the on-premise topology for the Process Federation Server truststore to include them.
- Provide the Process Federation Server config-dropin, which declares the on-premise IBM Business Automation Workflow system to federate.
- Configure Workplace to work on tasks and processes from the on-premise IBM Business Automation Workflow.
Step 1: Enable indexing on the on-premise IBM Business Automation Workflow system
When a Workplace user is successfully authenticated on Red Hat OpenShift, all queries from Workplace to Process Federation Server or a federated system and all queries from Process Federation Server to a federated system include a JSON Web Token that authenticates the user. In order to establish Single Sign-On (SSO) between Workplace, Process Federation Server, and the on-premise Business Automation Workflow system to federate, the WebSphere Application Server running on-premise Business Automation Workflow must be configured to perform authentication thaty uses JSON Web Tokens:
- Retrieve the cpd route information from your Red Hat OpenShift deployment.
The location of this route (host, and port) is needed in the remaining procedure. In the following example, the host for the cpd route is cpd-pfs-demo.apps.amply.cp.fyre.ibm.com and the port is 443 (default https port):
- Add the signer certificate of the Portal UI entry point to the truststore of the on-premise Business Automation Workflow server that uses the following procedure:
- Log in to the administrative console of the WebSphere server running on-premise Business Automation Workflow.
- Expand Security and click SSL certificate and key management.
- Under Configuration settings, click Manage endpoint security configurations.
- Select the appropriate outbound configuration to get to the cell management scope.
- Under Related Items, click Key stores and certificates and then click CellDefaultTrustStore key store.
- Under Additional Properties, click Signer certificates and Retrieve From Port.
- In the Hos enter the host of the cpd route, in Port enter the port of the cpd route (443 by default), and in Alias enter a unique name.
- Click Retrieve Signer Information.
- Verify that the certificate information is for a certificate that you can trust.
- Click Apply and Save.
- Once the signer certificate of the Portal UI entrypoint is trusted, configure the on-premise Business Automation Workflow server to authenticate incoming queries that uses their JSON Web Token:
- Log in to the administrative console of the WebSphere server running on-premise Business Automation Workflow.
- Expand Security and click Global Security
- In User account repository, make sure that your server is set up to use the same user repository as your deployment on Red Hat OpenShif, which is a prerequisite to enable federation of the system by the Process Federation Server that is deployed on Red Hat OpenShift.
- In Authentication, click Web and SIP security and then click Trust association
- Under Additional Properties, click Interceptors.
- Click New to add a com.ibm.ws.security.oidc.client.RelyingParty interceptor, or edit the existing com.ibm.ws.security.oidc.client.RelyingParty interceptor with the following custom properties in order to intercept all incoming queries with an Authorization Bearer header and to map the corresponding identity to the user with the same name in the user repository:
- provider_1.useJwtFromRequest: required
- provider_1.identifier: enter a unique identifier
- provider_1.issuerIdentifier: KNOXSSO
- provider_1.jwkEndpointUrl: location of the cpd route, followed by /auth/jwks
- provider_1.filter: Authorization%=Bearer
- provider_1.audiences:DSX
- provider_1.mapIdentityToRegistryUser: true
- zenJWT and cpd route https://cpd-pfs-demo.apps.amply.cp.fyre.ibm.com: See this screen capture for an example of custom properties with identifier
- Once the interceptor configuration is applied and saved, restart the Business Automation Workflow server in order for the interceptor to be activated.
*=info:com.ibm.ws.security.oidc.*=all:com.ibm.ws.security.openidconnect.*=all:com.ibm.ws.security.openid20.*=all:com.ibm.ws.security.web.*=all
Step 3: Provide self-signed certificates of the on-premise topology so the Process Federation Server truststore can include them
If the on-premise IBM Business Automation Workflow system and/or its database exposes self-signed certificates, add these certificates to the Process Federation Server truststore. For each of these certificates, create a secret resource with an entry named tls.crt
, which contains the public key of the certificate in PEM format.
Once all the self-signed certificates are packaged into secrets, declare them under the pfs_configuration.tls.tls_trust_list
CR value.
Step 4: Provide the Process Federation Server config-dropin, which declares the on-premise IBM Business Automation Workflow system to federate
Once the on-premise IBM Business Automation Workflow system is properly configured to perform indexing and to use Portal UI JSON Web Tokens for user authentication, provide the proper XML config-dropin to Process Federation Server.
In the CR values that are used to install IBM Cloud Pak for Business Automation, reference a secret that contains XML configuration dropins as the pfs_configuration.config_dropins_overrides_secret
CR value. The entries from this secret are mapped as files in the /config/configDropins/overrides
directory of each pod that runs the Process Federation Server.
To federate the on-premise IBM Business Automation Workflow system, create a new entry in this secret. This entry contains the following configuration elements:
- The declaration of the
<ibmPfs_federatedSystem>
element, with attribute authenticationMechanism set to the value "PFS_ACCESS_TOKEN" - The datasource of the on-premise IBM Business Automation Workflow system (
<datasource>
element) - he
<ibmPfs_bpdIndexer>
element - The
<ibmPfs_bpdRetriever>
element
For more information on the configuration elements, see Configuration properties for federated systems.
Important:
- If the on-premise IBM Business Automation Workflow system uses an IBM® Db2 database, reference the "DB2JCC4Lib" pre-defined library when you declare the jdbcDriver used by your datasource as follows:
<jdbcDriver libraryRef="DB2JCC4Lib"/>
- If the on-premise IBM Business Automation Workflow system uses an Oracle database and Process Federation Server already federates an IBM Business Automation Workflow Container that also uses an Oracle database, reference the "OracleLib" pre-defined library when you declare the jdbcDriver used by your datasource as follows:
<jdbcDriver libraryRef="OracleLib"/>
- In the other cases where the on-premise IBM Business Automation Workflow system uses an Oracle or Microsoft SQL Server database:
- Package the corresponding JDBC drivers in a persistent volume (PV)
- Create a persistent volume claim, which binds this PV and references it in the
pfs_configuration.custom_libs_pvc
CR value.
Note: Instead of creating a new PVC, you can also reuse the IBM Cloud Pak for Business Automation operator shared PVC if it already contains the libraries that you need. The PVC is mounted in the/config/resources/libs
directory on each pod that runs Process Federation Server. You can then use a<library>
configuration element in the configuration dropins that you create, and reference this library when you declare the IBM Business Automation Workflow datasource.
<server>
<ibmPfs_federatedSystem
authenticationMechanism="PFS_ACCESS_TOKEN"
indexProcessInstances="true"
allowedOrigins="*"
displayName="GAITS1"
id="gaits1"
index.number_of_replicas="1"
index.number_of_shards="3"
indexName="gaits1-bpd"
launchListPriority="1"
portalSupportUrlPrefix="https://gaits1.fyre.ibm.com:9443/portal"
restUrlPrefix="https://gaits1.fyre.ibm.com:9443/rest/bpm/wle"
taskCompletionUrlPrefix="https://gaits1.fyre.ibm.com:9443/teamworks"/>
<dataSource commitOrRollbackOnCleanup="commit" id="gaits1_bpd_db2" isolationLevel="TRANSACTION_READ_COMMITTED" jndiName="jdbc/gaits1bpd" type="javax.sql.DataSource">
<jdbcDriver libraryRef="DB2JCC4Lib"/>
<properties.db2.jcc databaseName="BPMDB" password="xxxxxx" portNumber="50000" serverName="gaits1.fyre.ibm.com" user="db2admin"/>
</dataSource>
<ibmPfs_bpdIndexer
dataSourceRef="gaits1_bpd_db2"
federatedSystemRef="gaits1"
schemaName="DB2ADMIN" />
<ibmPfs_bpdRetriever
connectTimeout="10s"
federatedSystemRef="gaits1"
internalRestUrlPrefix="https://gaits1.fyre.ibm.com:9443/rest/bpm/wle"
readTimeout="10s"/>
<ibmPfs_restConfig systemStatusCheckInterval="1s"/>
</server>
Step 5: Configure Workplace
- Locate your RR writer username and password. The writer username and password are under the secret referenced in the
resource_registry_configuration.admin_secret_name
CR value. See the detailed description in the Resource Registry table in IBM Business Automation Application Engine parameters. The writer's username and password are set in this secret aswriteUser
andwritePassword
keys. - Open a terminal on one of the RR pods. RR pod name must have the following format
<icp4acluster-instance-name>-dba-rr-<alphanumeric-id>
. - Devise the RR key value that uses the
etcdctl
CLI. If the on-premise IBM Business Automation Workflow endpoint is https://onprem.baw.com:9443:- The key is the system ID. The system ID can be retrieved by invoking the https://onprem.baw.com:9443/rest/bpm/wle/v1/systems API (
<systemID>
XML tag); - The value is the following JSON:
{"hostname":"onprem.baw.com", "port": "9443", "protocol": "https", "ctxRoot": "/rest/bpm/wle"}
restUrlPrefix
property of theibmPfs_federatedSystem
configuration element
- The key is the system ID. The system ID can be retrieved by invoking the https://onprem.baw.com:9443/rest/bpm/wle/v1/systems API (
- Create the RR key by executing the following command in the terminal. The example here is with a system ID of
feded754-790d-4214-a326-865812d4357a
:etcdctl --cacert="$ETCD_PEER_TRUSTED_CA_FILE" --user="writer:writerpwd" --endpoints="https://<icp4acluster-instance-name>-dba-rr-client:2379" put /dba/appresources/IBM_WORKFLOW/WORKFLOW_SYSTEM/feded754-790d-4214-a326-865812d4357a '{"hostname":"onprem.baw.com", "port": "9443", "protocol": "https", "ctxRoot": "/rest/bpm/wle"}'
Note: Enabling persistence of the Resource Registry is highly recommended in production to avoid having the key disappearing upon restarts of cluster or pods. For more details, see the description of theresource_registry_configuration.auto_backup.*
CR values in the Resource Registry table in IBM Business Automation Application Engine parameters. - If you want to list all the RR keys related to federated systems, issue the following command:
etcdctl --cacert="$ETCD_PEER_TRUSTED_CA_FILE" --user="writer:writerpwd" --endpoints="https://<icp4acluster-instance-name>-dba-rr-client:2379" get /dba/appresources/IBM_WORKFLOW/WORKFLOW_SYSTEM/ --prefix
Document Location
Worldwide
Was this topic helpful?
Document Information
Modified date:
11 February 2022
UID
ibm16514469