Adding IBM Business Automation Workflow and IBM Federated Process Portal to use the User Management Service

Add IBM® Business Automation Workflow and IBM Federated Process Portal to use the User Management Service (UMS) for single sign-on (SSO) in either a production environment or a quick start environment with a single server that uses a Derby database.

Important:

If you are using UMS version 1.0.0 that shipped with IBM Business Automation Workflow V18.0.0.1, you must manually update configuration properties in the wlp/ibmUserManagement/extension/configTemplates/workflow/connectToUms.jy script file.
For UMS version 1.0.1 and later, the configuration properties are in a dedicated file and all required files are provided in a single .zip package.

To add an IBM Business Automation Workflow server to use User Management Service for single sign-on, perform the following actions:

Copy the file wlp/ibmUserManagement/extension/configTemplates/workflow/connectToUms-workflow.zip to the IBM Business Automation Workflow environment (on the dmgr machine), and extract it to a separate directory for each IBM Business Automation Workflow system. You will need the contents of this directory if you want to modify or delete your SSO configuration.
Apply a matching configuration to the IBM Business Automation Workflow system by performing the following actions:
1. Edit the provided properties file connectToUms-workflow.properties and set appropriate values for the variables:
  
  ums_host
  
  The host name of your User Management Service.
  
  ums_port
  
  The HTTPS port of your User Management Service.
  
  oidcop_url_prefix
  
  The full URL prefix of your User Management Service. This value can usually be calculate from ums_host and ums_port, but if you are using port 443, you can omit the port number. If this parameter is empty, the value used defaults to https://ums_host:ums_port/oidc/endpoint/ums.
  
  oidc_client_id
  
  The client identifier that is being registered with the User Management Service.
  
  oidc_client_name
  
  A description of the client that is being registered with the User Management Service. The default value for this parameter is set to the value of the client_id parameter.
  
  oidc_client_secret
  
  The secret for the client that is being registered with the User Management Service.
  
  baw_cellname
  
  WebSphere cell name of this environment:
  
  baw_de
  
  The name of the IBM Business Automation Workflow deployment environment:
  
  baw_clustername
  
  Cluster where to install the OpenID Connect Relying Party application (typically AppTarget). For a standalone environment leave this blank "" .
  
  baw_nodename and baw_servername
  
  Server where to install the OpenID Connect Relying Party application. In a standalone (non-clustered) environment. Values will be ignored, if baw_clustername is provided.
  
  redirect_uris: (uri_1, uri_2,.. uri_n)
  
  This parameter specifies the full URLs in the OpenID Connect Relying Party to which the user can be redirected after successful authentication. For example, redirect_uris = https://baw_host:baw_port/oidcclient/ums. The port number must be defined explicitly, even if you are using port 443.
  
  For UMS versions 1.0.0 to 1.0.3, this parameter applies if you set registerProductionConfiguration is set to true.
  
  From UMS version 1.1.0, this parameter must always be specified.
  
  BAW_federated_portal = (true | false)
  
  To set configuration and Oauth settings for Process Portal and register it set this value to true.
  
  For UMS versions 1.0.0 to 1.0.3, this parameter only applies if you set registerProductionConfiguration is set to true.
  
  From UMS version 1.1.0, this parameter does not depend on the value of registerProductionConfiguration.
  
  portal_redirect_uri
  
  The full URL in the OpenID Connect Relying Party to which the user can be redirected after successful authentication. For example,https://baw_host:baw_port/ProcessPortal/tokenReceiver.html. The port number must be defined explicitly, even if you are using port 443.
  
  For UMS versions 1.0.0 to 1.0.3, this parameter only applies if you set registerProductionConfiguration is set to true.
  
  From UMS version 1.1.0, this parameter does not depend on the value of registerProductionConfiguration.
  
  oidc_portal_client_id
  
  The client identifier that is being registered with the Offering Party. Unless specified, this parameter value is generated from oidc_client_name + "-ProcessPortal".
  
  oidc_portal_client_name
  
  A description for the client that is being registered with the OP. Unless specified, this parameter is set to the client_id parameter value by default.
  
  reauthAllowed
  
  Set to true if clients are allowed to reauthorize. The default value is false.
  
  logoutTimeoutInSeconds
  
  Timeout before user is logged out after they see reauthorization modal. The default value is 60 seconds.
  
  logoutTimeoutInSecondsWhileReauth
  
  Timeout before user is logged out after they started the re-authorization process. The default value is 120 seconds.
  
  registerProductionConfiguration
  
  For UMS versions 1.0.0 to 1.0.3 only, this can be set to the value true or false. If it is set to true then the following properties apply.
  
  autoAcceptCertificate
  
  Set to true to automatically accept the certificates of the User Management Service server.
  
  certificateFingerprint
  
  If you specify this optional parameter, the User Management Service fingerprint must match the value specified.
  
  ums_username
  
  Optionally specifies the user management admin user. This value must match your User Management Service configuration. If the user name is passed as a command line parameter, this parameter is ignored.
  
  ums_password
  
  Optionally specifies the user management admin user password. This value must match your User Management Service configuration. If the password is passed as a command line parameter, this parameter is ignored
  Important: For a production environment, set oidcop_url_prefix for all clones to the URL of your web server. Set the same value for the attribute issuerIdentifier on the openidConnectProvider configuration element in each clone's wlp/usr/servers/serverName/server.xml file. For example:
```
<openidConnectProvider id="ums" oauthProviderRef="oidcOAuthProvider" 
     issuerIdentifier="https://umshost/oidc/endpoint/ums" />
```
  As part of the OpenID Connect protocol, the User Management Service issues ID tokens in JSON Web Token (JWT) format, as specified in RFC 7519. One of the claims in these tokens is issuer, which is used to identify the entity that issued the token. This step is required because by default, the User Management Service specifies the URL of the server as the issuer, which works for a quick start single server, but doesn't work for multiple servers. For more information, see openidConnectProvider - OpenID Connect Server Provider (openidConnectProvider).
2. Set up the environment variables that points to IBM Business Automation Workflow installation directory:
  1. Open a command prompt and navigate to the following directory:
    - Linux: /opt/IBM/WebSphere/AppServer/profiles/profile_name/bin
    - Windows: drive:\Program Files\IBM\WebSphere\AppServer\profiles\profile_name\bin
    Where profile_name is the profile name of the Deployment Manager (typically, this is Dmgr01) and drive: is the system drive on which the file directory is stored. For example: C: or D:.
  2. Execute the following script:
    - Linux: . setupCmdLine.sh
    - Windows: setupCmdLine.bat
3. Make sure that the Deployment Manager is running.
4. Make sure that the User Management Service is running.
  - To start the Liberty server named serverName, issue the following command from the wlp\bin directory:
```
server start serverName
```
  - To stop the Liberty server named serverName, issue the following command from the wlp\bin directory:
```
server stop serverName
```
5. Run connectToUms.bat or connectToUms.sh to execute the parameters of your customized properties file. For example:
```
connectToUms.[bat|sh][action][options...]
```
  For example, on Windows:
```
connectToUms.bat add -username <user name> -password <password> 
     -ums_username <User Management admin user>  -ums_password <User Management admin user password>
```
  Where action can be one of the following:
  
  add
  
  Add a client.
  
  remove
  
  Remove an existing client.
  
  modify
  
  Modify an existing client.
  
  Options can be the following:
  
  -? | -help
  
  This help message.
  
  u <username> | -username <username>
  
  The user name of the Administrator role on WebSphere® Application Server. This administrator must be configured at the cell level, not at the cluster, node, or server level.
  
  -p <password> | -password <password>
  
  The password of the WebSphere Application Server (unencrypted).
  
  -ums_username <UMS username>
  
  User name of User Management Server administrator.
  
  -ums_password <UMS password>
  
  The user password of User Management Server administrator (unencrypted).
  Note: The batch file performs the following actions:
  1. Register the WebSphere provided OpenID Connect Relying Party Trust Association Interceptor (TAI).
  2. Configure custom properties for the TAI to point to the User Management Service.
  3. Install the WebSphere provided OpenID Connect application.
  4. Import the SSL certificate of the User Management Service into IBM Business Automation Workflow default trust store.
  5. Configures a logout exit page so that users log out of the User Management Service after logging out of IBM Business Automation Workflow.
  6. Register IBM Business Automation Workflow as a client with the OpenID Connect Provider.
  7. Register Process Portal as a client with the OpenID Connect Provider.
  8. Configure OAuth for Process Portal.
  9. Configure Mashups Config Service for Process Portal.
  For more information, see Configuring an OpenID Connect Provider to accept client registration requests.
Save and synchronize the configuration and restart your environment. For information about synchronizing, see Synchronizing nodes using the wsadmin scripting tool.

Now the users of your IBM Business Automation Workflow system can enjoy the benefits of high-availability single sign-on.