Chapter 12. Integrating Red Hat JBoss BPM Suite with Red Hat Single Sign-On

Procedure: Setting Up RH-SSO with Realm Client

1. Install and configure a basic RH-SSO standalone server. To do this, follow the instructions in the RH-SSO Installation Guide.

   Note

   If you want to run both RH-SSO and Red Hat JBoss BPM Suite servers on the same machine, ensure that you avoid port conflicts. To do so, do one of the following:

   • Update the RHSSO_HOME/standalone/configuration/standalone.xml file and set a port offset to 100. For example:

     <socket-binding-group name="standard-sockets" default-interface="public" port-offset="${jboss.socket.binding.port-offset:100}">

     Copy to Clipboard Toggle word wrap

   • Use an environment variable to run the server:

     bin/standalone.sh -Djboss.socket.binding.port-offset=100

     Copy to Clipboard Toggle word wrap

2. Start the RH-SSO server using the following command from RHSSO_HOME/bin:

   ./standalone.sh

   Copy to Clipboard Toggle word wrap

   Once the RH-SSO server starts, open http://localhost:8180/auth/admin in a web browser and log in using your admin credentials that you created while installing RH-SSO. When you login for the first time, you can set up the initial user using the new user registration form.

3. On the RH-SSO admin console, click Realm Settings tab.

4. On the Realm Settings page, click Add Realm.

   The Add realm page opens.

5. On the Add realm page, provide a name for the realm and click Create.

6. Click Client tab from the main admin console menu and click Create.

   The Add Client page opens.

7. On the Add Client page, provide the required information to create a new client for your realm. For example:

   • Client ID: kie
   • Client protocol: openid-connect
   • Root URL: http://localhost:8080/business-central

8. Click Save to save your changes.

   At this point, the RH-SSO server is configured with a realm with a client for Red Hat JBoss BPM Suite applications (Business Central, in this example) and running and listening for HTTP connections at localhost:8180. This realm provides different users, roles, and sessions for the Red Hat JBoss BPM Suite applications.

1. Install the RH-SSO adapter for EAP.
2. Configure the Red Hat JBoss BPM Suite application and the RH-SSO client adapter.

Procedure: Installing the RH-SSO Adapter for EAP

1. Install EAP 6.4.X. See Chapter 2. Installation Instructions from the Red Hat JBoss Enterprise Application Platform Installation Guide.
2. Install Red Hat JBoss BPM Suite in the freshly installed JBoss EAP. This step is important because if you configure RH-SSO adapter by making changes in standalone.xml, and then unzip Red Hat JBoss BPM Suite, you may overwrite and lose the RH-SSO adapter configuration.
3. Download the EAP adapter from the Red Hat Customer Portal.
4. Unzip and install the adapter. For installation instructions, see Installing Adapters for Red Hat Single Sign-On in the RH-SSO Installation Guide.

Procedure: Configuring the RH-SSO Adapter

1. Navigate to EAP_HOME/standalone/configuration in your EAP installation and edit standalone.xml to add the RH-SSO subsystem configuration. For example:

   <subsystem xmlns="urn:jboss:domain:keycloak:1.1">
    <secure-deployment name="business-central.war">
      <realm>demo</realm>
      <realm-public-key>MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCrVrCuTtArbgaZzL1hvh0xtL5mc7o0NqPVnYXkLvgcwiC3BjLGw1tGEGoJaXDuSaRllobm53JBhjx33UNv+5z/UMG4kytBWxheNVKnL6GgqlNabMaFfPLPCF8kAgKnsi79NMo+n6KnSY8YeUmec/p2vjO2NjsSAVcWEQMVhJ31LwIDAQAB</realm-public-key>
      <auth-server-url>http://localhost:8180/auth</auth-server-url>
      <ssl-required>external</ssl-required>
      <enable-basic-auth>true</enable-basic-auth>
      <resource>kie</resource>
      <credential name="secret">759514d0-dbb1-46ba-b7e7-ff76e63c6891</credential>
      <principal-attribute>preferred_username</principal-attribute>
    </secure-deployment>
   </subsystem>

   Copy to Clipboard Toggle word wrap

   Here,

   • secure-deployment name: Name of your application’s WAR file.
   • realm: Name of the realm that you created for the applications to use.
   • realm-public-key: The public key of the realm you created. You can find it in the Keys tab in the Realm settings page of the realm you created in the RH-SSO admin console. If you do not provide a value for realm-public-key, the server retrieves it automatically.
   • auth-server-url: The URL for the RH-SSO authentication server.
   • enable-basic-auth: The setting to enable basic authentication mechanism, so that the clients can use both token-based and basic authentication approaches to perform the requests.
   • resource: The name for the client that you created.
   • credential name: The secret key for the client you created. You can find it in the Credentials tab on the Clients page of the RH-SSO admin console.

   • principal-attribute: The login name of the user. If you do not provide this value, your User Id is displayed in the application instead of your user name.

     Note

     The RH-SSO server converts the user names to lowercase. Therefore, after integration with RH-SSO, your user name will appear in lowercase in Business Central. If you have user names in upper-case letters hard coded in business processes, the application may not be able to identify the upper-case user.

2. Add the following sub element under the <extensions> section of standalone.xml:

   <extension module="org.keycloak.keycloak-adapter-subsystem"/>

   Copy to Clipboard Toggle word wrap

   This secures the application using the urn:jboss:domain:keycloak subsystem in standalone.xml as opposed to securing it through web.xml file inside each WAR.

3. Navigate to EAP_HOME/bin/ and start the EAP server using the following command:

   ./standalone.sh

   Copy to Clipboard Toggle word wrap

   You can now login to your Red Hat JBoss BPM Suite application (in this example, Business Central) once the server is running using the RH-SSO admin user credentials.

1. Login to the RH-SSO Admin console and open the realm you wish to add a user to.

2. Click Users under Manage section in the left menu bar.

   An empty user list page called Users opens.

3. Click the Add User button on the empty user list to start creating your new user.

   An Add user page opens.

4. Provide user information on the Add user page and click Save.
5. Set new password under the Credentials tab.

6. Assign the new user one of the roles that allow access to Business Central (For example, admin or analyst role for Red Hat JBoss BRMS and admin or developer role for Red Hat JBoss BPM Suite).

   Define the roles as realm roles in the Roles page under the Configure section.

7. Click Role Mappings tab on the Users page to assign roles.

Procedure: Disabling BasicAuthSecurityFilter

1. Open your application deployment descriptor file (WEB-INF/web.xml) and apply the following changes to it:

   • Remove the following lines to remove the servlet filter and its mapping for class org.uberfire.ext.security.server.BasicAuthSecurityFilter:

     <filter>
       <filter-name>HTTP Basic Auth Filter</filter-name>
       <filter-class>org.uberfire.ext.security.server.BasicAuthSecurityFilter</filter-class>
       <init-param>
         <param-name>realmName</param-name>
         <param-value>KIE Workbench Realm</param-value>
       </init-param>
     </filter>
     
     <filter-mapping>
       <filter-name>HTTP Basic Auth Filter</filter-name>
       <url-pattern>/rest/*</url-pattern>
       <url-pattern>/maven2/*</url-pattern>
       <url-pattern>/ws/*</url-pattern>
     </filter-mapping>

     Copy to Clipboard Toggle word wrap

   • Add the following lines to add the security-constraint for the url-patterns that you have removed from the filter mapping:

     <security-constraint>
       <web-resource-collection>
         <web-resource-name>remote-services</web-resource-name>
         <url-pattern>/rest/*</url-pattern>
         <url-pattern>/maven2/*</url-pattern>
         <url-pattern>/ws/*</url-pattern>
       </web-resource-collection>
       <auth-constraint>
         <role-name>rest-all</role-name>
       </auth-constraint>
     </security-constraint>

     Copy to Clipboard Toggle word wrap
2. Save your changes.

Procedure: Integrating RH-SSO with BAM

1. On the RH-SSO admin console, open the security realm that you created.

2. Click Client tab from the main admin console menu and click Create.

   The Add Client page opens.

3. On the Add Client page, provide the required information to create a new BAM client for your realm. For example:

   • Client ID: dashbuilder
   • Root URL: http://localhost:8080/dashbuilder
   • Client protocol: openid-connect

4. Configure the RH-SSO client adapter for BAM. To do so, navigate to EAP_HOME/standalone/configuration in your EAP installation and edit standalone.xml to add the RH-SSO subsystem configuration. For example:

   <secure-deployment name="dashbuilder.war">
     <realm>demo</realm>
     <realm-public-key>MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCrVrCuTtArbgaZzL1hvh0xtL5mc7o0NqPVnYXkLvgcwiC3BjLGw1tGEGoJaXDuSaRllobm53JBhjx33UNv+5z/UMG4kytBWxheNVKnL6GgqlNabMaFfPLPCF8kAgKnsi79NMo+n6KnSY8YeUmec/p2vjO2NjsSAVcWEQMVhJ31LwIDAQAB</realm-public-key>
     <auth-server-url>http://localhost:8180/auth</auth-server-url>
     <ssl-required>external</ssl-required>
     <resource>dashbuilder</resource>
     <enable-basic-auth>true</enable-basic-auth>
     <credential name="secret">e92ec68d-6177-4239-be05-28ef2f3460ff</credential>
     <principal-attribute>preferred_username</principal-attribute>
   </secure-deployment>

   Copy to Clipboard Toggle word wrap

   Here,

   • secure-deployment name: The name of the BAM war file being deployed.
   • realm-public-key: The public key of the realm you created.
   • resource: The name of the client that you created for BAM (dashbuilder).
   • enable-basic-auth: The setting to enable basic authentication mechanism, so that the clients can use both token-based and basic authentication approaches to perform the requests.
   • credential name: The secret key for the client you created for BAM. You can find it in the Credentials tab on the Clients page of the RH-SSO admin console.
   • principal-attribute: The login name of the user. If you do not provide this value, your User Id is displayed in the application instead of your user name.

5. Restart the EAP server and open http://localhost:8080/dashbuilder in a web browser to access BAM. Login to BAM using your RH-SSO admin user credentials.

   You can now access both the applications (Business Central and BAM) without having to re-login.