Chapter 7. Integrating Red Hat Decision Manager with Red Hat Single Sign-On

Red Hat Single Sign-On (RH-SSO) is a single sign-on solution that you can use to secure your browser applications with your REST web services and Git access. This chapter describes how you can integrate RH-SSO with Red Hat Decision Manager and leverage its features.

Integrating with RH-SSO brings an integrated SSO and identity management (IDM) environment for Red Hat Decision Manager. The session management feature of RH-SSO enables you to use different Red Hat Decision Manager environments on the web by authenticating only once.

For more information on RH-SSO, see the RH-SSO documentation.

RH-SSO integration points

You can integrate RH-SSO with Decision Servers using the following integration points:

  • Red Hat Decision Manager authentication through an RH-SSO server

    Authenticating Red Hat Decision Manager Red Hat Decision Manager through RH-SSO involves securing both Red Hat Decision Manager web client and remote services through RH-SSO. This integration enables you to connect to Red Hat Decision Manager using either the web interface or a remote service consumer through RH-SSO.

  • Decision Server authentication through an RH-SSO server

    Authenticating Red Hat Decision Manager Decision Server through RH-SSO involves securing the remote services provided by Decision Server because it does not provide a web interface for server authentication. This enables any remote Red Hat Decision Manager service consumer (user or a service) to authenticate through RH-SSO.

  • Third-party client authentication through an RH-SSO server

    Authenticating a third-party client through an RH-SSO server requires third-party clients to authenticate themselves using RH-SSO to consume the remote service endpoints provided by Red Hat Decision Manager and Decision Server, such as the REST API or remote file system services.

The following sections describe how to achieve RH-SSO integration through these integration points:

7.1. Red Hat Decision Manager authentication through RH-SSO

To authenticate Red Hat Decision Manager through RH-SSO:

  1. Set up and run an RH-SSO server with a realm client for Red Hat Decision Manager.
  2. Install and set up the RH-SSO client adapter for Red Hat JBoss EAP.
  3. Secure Red Hat Decision Manager remote service using RH-SSO.

7.1.1. Setting up RH-SSO with the realm client for Red Hat Decision Manager

Security realms are used to restrict access for different application resources. You should create a new realm whether your RH-SSO instance is private or shared with other products. You can keep the master realm as a place for super administrators to create and manage the realms in your system. If you are integrating with an RH-SSO instance that is shared with other product installations to achieve single sign-on with those applications, all of those applications must use the same realm.

Procedure

  1. Download RH-SSO from the Downloads section of the Red Hat Customer Portal.
  2. Install and configure a basic RH-SSO standalone server. To do this, follow the instructions in the "Install and Boot" chapter of the Red Hat Single Sign On Getting Started Guide. For production environment settings, consult the Red Hat Single Sign On Server Administration Guide.

    Note

    If you want to run both RH-SSO and Red Hat Decision Manager servers on the same system, ensure that you avoid port conflicts. by doing 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}">
    • Use an environment variable to run the server:

      bin/standalone.sh -Djboss.socket.binding.port-offset=100
  3. Start the RH-SSO server to configure RH-SSO from RHSSO_HOME/bin:

    ./standalone.sh

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

  4. In the RH-SSO Admin Console, click the Realm Settings menu item.
  5. On the Realm Settings page, click Add Realm.

    The Add realm page opens.

  6. On the Add realm page, provide a name for the realm and click Create.
  7. Click the Clients menu item and click Create.

    The Add Client page opens.

  8. 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/decision-central
  9. Click Save to save your changes.

    After you create a new client, its Access Type is set to public by default. Change it to confidential.

    At this point, the RH-SSO server is configured with a realm with a client for Red Hat Decision Manager applications and running and listening for HTTP connections at localhost:8180. This realm provides different users, roles, and sessions for Red Hat Decision Manager applications.

7.1.2. Setting up the RH-SSO client adapter for Red Hat JBoss EAP

To set up the RH-SSO client adapter for Red Hat JBoss EAP, install the RH-SSO adapter for Red Hat JBoss EAP then configure Red Hat Decision Manager application and the RH-SSO client adapter.

Procedure

  1. Install Red Hat JBoss EAP 6.4.X or 7.0.

    For version 6, see chapter Installation Instructions from the Red Hat JBoss Enterprise Application Platform Installation Guide.

    For version 7, see chapter Installing Red Hat JBoss EAP from the Red Hat JBoss Enterprise Application Platform Installation Guide.

  2. Install Red Hat Decision Manager in the freshly installed Red Hat JBoss EAP home.

    If you configure the RH-SSO adapter by making changes to the standalone.xml file, and then unzip Red Hat Decision Manager, you may overwrite and lose the RH-SSO adapter configuration.

  3. Download the Red Hat JBoss EAP adapter from the Red Hat Customer Portal.
  4. Unzip and install the adapter. For installation instructions, see the JBoss EAP Adapter section of the Red Hat Single Sign On Securing Applications and Services Guide.
  5. For version 7, go to EAP_HOME/standalone/configuration and open the standalone.xml and standalone-full.xml files. Delete the <single-sign-on/> element from both of the files.

    You do not need to perform this step for Red Hat JBoss EAP 6.

Procedure

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

    <subsystem xmlns="urn:jboss:domain:keycloak:1.1">
     <secure-deployment name="decision-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>

    In this example:

    • secure-deployment name is the name of your application’s WAR file.
    • realm is the name of the realm that you created for the applications to use.
    • realm-public-key is the public key of the realm you created. You can find the key 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 is the URL for the RH-SSO authentication server.
    • enable-basic-auth is 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 is the name for the client that you created.
    • credential name is the secret key for the client you created. You can find the key in the Credentials tab on the Clients page of the RH-SSO Admin Console.
    • principal-attribute is 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 lowe rcase. Therefore, after integration with RH-SSO, your user name will appear in lowe rcase in Red Hat Decision Manager. If you have user names in upper case hard coded in business processes, the application may not be able to identify the upper case user.

  2. Navigate to EAP_HOME/bin/ and enter the following command to start the Red Hat JBoss EAP server:

    ./standalone.sh
Note

You can also configure the RH-SSO adapter for Red Hat JBoss EAP by updating your application’s WAR file to use the RH-SSO security subsystem. However, Red Hat recommends that you configure the adapter through the RH-SSO subsystem. Doing this updates the Red Hat JBoss EAP configuration instead of applying the configuration on each WAR file.

7.1.3. Adding a new user

To add new users and assign them a role to access Red Hat Decision Manager:

  1. Log in to the RH-SSO Admin Console and open the realm to which you wish to add a user.
  2. Click the Users menu item under the Manage section.

    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.

    The Add user page opens.

  4. Provide user information on the Add user page and click Save.
  5. Set a new password under the Credentials tab.
  6. Assign the new user one of the roles that allow access to Red Hat Decision Manager. For example, the admin or analyst role.

    Define the roles as realm roles in the Realm Roles tab under the Roles section.

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

You can now log in to Decision Central after you start Decision Server.

7.1.4. Securing Red Hat Decision Manager remote service using RH-SSO

Red Hat Decision Manager provides different remote service endpoints that can be consumed by third-party clients using remote API. To authenticate those services through RH-SSO, you must disable a security filter called BasicAuthSecurityFilter.

Procedure

  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>
    • 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>
  2. Save your changes.

7.1.5. Securing Red Hat Decision Manager file system services using RH-SSO

To consume other remote services, such as file systems (for example, a remote GIT service), you must specify a correct RH-SSO login module. First, generate a JSON configuration file.

Procedure

  1. Navigate to the RH-SSO Admin Console located at http://localhost:8080/auth/admin.
  2. Click Clients.
  3. Create a new client with the following settings:

    • Set Client ID as kie-git.
    • Set Access Type as confidential.
    • Disable the Standard Flow Enabled option.
    • Enable the Direct Access Grants Enabled option.
    kie git client settings
  4. Click Save.
  5. Click the Installation tab at the top of the client configuration screen and choose Keycloak OIDC JSON as a Format Option.
  6. Click Download.
  7. Move the downloaded JSON file to an accessible directory in the server’s file system or add it to the application class path.

    For more information, see the JAAS plugin chapter of the Keycloak Securing Applications and Services Guide.

After you successfully generate and download the JSON configuration file, specify the correct RH-SSO login module in the EAP_HOME/standalone/configuration/standalone.xml file. By default, the security domain in Red Hat Decision Manager is set to other. Replace the default values of the login-module in this security domain with the values in the following example:

<security-domain name="other" cache-type="default">
  <authentication>
    <login-module code="org.keycloak.adapters.jaas.DirectAccessGrantsLoginModule" flag="required">
      <module-option name="keycloak-config-file" value="$EAP_HOME/kie-git.json"/>
    </login-module>
  </authentication>
</security-domain>

The JSON file specified in the module-option element contains a client used for securing the remote services. Replace the $EAP_HOME/kie-git.json value of the module-option element with the absolute path or the class path (classpath:/EXAMPLE_PATH/kie-git.json) to this JSON configuration file.

At this point, all users authenticated through the RH-SSO server can clone internal GIT repositories. In the following command, change USER_NAME to a RH-SSO user, for example admin:

git clone ssh://USER_NAME@localhost:8001/system

7.1.6. Enabling user and group management for RH-SSO

This section describes how you can use Decision Central to manage users and groups stored in RH-SSO.

Procedure

  1. Ensure that the following libraries are in the WEB-INF/lib directory:

    uberfire-security-management-api-<latest_artifact_version>.jar
    uberfire-security-management-backend-<latest_artifact_version>.jar
    uberfire-security-management-keycloak-<latest_artifact_version>.jar
    keycloak-core-<latest_artifact_version>.jar
    keycloak-common-<latest_artifact_version>.jar
  2. Remove third-party security JAR files, for example:

    uberfire-security-management-wildfly-<latest_artifact_version>.jar
    uberfire-security-management-tomcat-<latest_artifact_version>.jar
  3. Replace the entire contents of the WEB-INF/classes/security-management.properties file with the following content:

    org.uberfire.ext.security.management.api.userManagementServices=KCCredentialsUserManagementService
    org.uberfire.ext.security.management.keycloak.authServer=http://localhost:8081/auth
    org.uberfire.ext.security.management.keycloak.realm=demo
    org.uberfire.ext.security.management.keycloak.user=admin
    org.uberfire.ext.security.management.keycloak.password=admin
    org.uberfire.ext.security.management.keycloak.clientId=kie
    org.uberfire.ext.security.management.keycloak.clientSecret=759514d0-dbb1-46ba-b7e7-ff76e63c6891
    Note

    If the WEB-INF/classes/security-management.properties file does not exist, create it.

  4. Edit the following dependencies and exclusions in the /META-INF/jboss-deployment-structure.xml file:

    <dependencies>
        <module name="org.jboss.resteasy.resteasy-jackson-provider" services="import"/>
    </dependencies>
    <exclusions>
        <module name="org.jboss.resteasy.resteasy-jackson2-provider"/>
    </exclusions>

7.2. Decision Server authentication through RH-SSO

The Red Hat Decision Manager Decision Server provides a REST API for third-party clients. You can integrate Decision Server with RH-SSO to delegate the third-party clients identity management to the RH-SSO server.

After you have created a realm client for Red Hat Decision Manager and set up the RH-SSO client adapter for Red Hat JBoss EAP, you can repeat the same steps to integrate Decision Server with RH-SSO.

7.2.1. Creating a client for Decision Server on RH-SSO

You can use the RH-SSO Admin Console to create a new client in an exiting realm.

Procedure

  1. In the RH-SSO Admin Console, open the security realm that you created.
  2. Click the Clients menu item and click Create.

    The Add Client page opens.

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

    • Client ID: kie-execution-server
    • Root URL: http://localhost:8080/kie-server
    • Client protocol: openid-connect
  4. Click Save to save your changes.

    The new client Access Type is set to public by default. Change it to confidential and click Save again.

  5. Navigate to the Credentials tab and copy the secret key. The secret key is necessary to configure the kie-execution-server client in the next section.

7.2.2. Installing and setting up Decision Server with the client adapter

To consume the Decision Server remote service endpoints, you must first create and assign the kie-server role in the RH-SSO Admin Console.

Note

If you deployed Decision Server to a different application server than Red Hat Decision Manager, install and configure RH-SSO on your second server as well.

Procedure

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

    <subsystem xmlns="urn:jboss:domain:keycloak:1.1">
      <secure-deployment name="kie-execution-server.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>kie-execution-server</resource>
         <enable-basic-auth>true</enable-basic-auth>
         <credential name="secret">03c2b267-7f64-4647-8566-572be673f5fa</credential>
         <principal-attribute>preferred_username</principal-attribute>
      </secure-deployment>
    </subsystem>
    
    <system-properties>
      <property name="org.kie.server.sync.deploy" value="false"/>
    </system-properties>

    In this example:

    • secure-deployment name is the name of your application WAR file.
    • realm is the name of the realm that you created for the applications to use.
    • realm-public-key is the public key of the realm you created. You can find the key 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 this public key, the server retrieves it automatically.
    • auth-server-url is the URL for the RH-SSO authentication server.
    • resource is the name for the server client that you created.
    • enable-basic-auth is 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 is the secret key of the server client you created. You can find the key in the Credentials tab on the Clients page of the RH-SSO Admin Console.
    • principal-attribute is 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.
  2. Save your configuration changes in the standalone.xml file.
  3. Use the following command to restart the Red Hat JBoss EAP server and run Decision Server.

    EXEC_SERVER_HOME/bin/standalone.sh -Dorg.kie.server.id=<ID> -Dorg.kie.server.user=<USER> -Dorg.kie.server.pwd=<PWD> -Dorg.kie.server.location=<LOCATION_URL> -Dorg.kie.server.controller=<CONTROLLER_URL> -Dorg.kie.server.controller.user=<CONTROLLER_USER> -Dorg.kie.server.controller.pwd=<CONTOLLER_PASSWORD>

    Here is an example:

    EXEC_SERVER_HOME/bin/standalone.sh -Dorg.kie.server.id=kieserver1 -Dorg.kie.server.user=kieserver -Dorg.kie.server.pwd=password -Dorg.kie.server.location=http://localhost:8080/kie-execution-server/services/rest/server -Dorg.kie.server.controller=http://localhost:8080/decision-central/rest/controller -Dorg.kie.server.controller.user=kiecontroller -Dorg.kie.server.controller.pwd=password
  4. After Decision Server is running, you can check the server status. In the following command, kieserver is a user name with the kie-server role and password password:

    curl http://kieserver:password@localhost:8080/kie-execution-server/services/rest/server/

You can also use token-based authorization for communication between Red Hat Decision Manager and Decision Server. You can use the complete token as a system property of your application server, instead of the user name and password, for your applications. However, you must ensure that the token will not expire while the applications are interacting because the token is not automatically refreshed. To get the token, see Section 7.3.2, “Token-based authentication”.

Procedure

  1. To configure Red Hat Decision Manager to manage Decision Server using the tokens set the org.kie.server.token property.
  2. Make sure that the org.kie.server.user and org.kie.server.pwd properties are not set. Red Hat Decision Manager will then use the Authorization: Bearer $TOKEN authentication method.

Procedure

  1. If you want to use the REST API using the token-based authentication, set the org.kie.server.controller.token property.
  2. Make sure that the org.kie.server.controller.user and org.kie.server.controller.pwd properties are not set.
Note

Because Decision Server is unable to refresh the token, use a high-lifespan token. A token’s lifespan must not exceed January 19 2038. Check with your security best practices to see whether this is a suitable solution for your environment.

7.3. Third-party client authentication through RH-SSO

To use the different remote services provided by Red Hat Decision Manager or by Decision Server, your client, such as curl, wget, web browser, or a custom REST client, must authenticate through the RH-SSO server and have a valid token to perform the requests. To use the remote services, the authenticated user must have assigned the following roles:

  • rest-all for using Red Hat Decision Manager remote services.
  • kie-server for using the Decision Server remote services.

Use the RH-SSO Admin Console to create these roles and assign them to the users that will consume the remote services.

Your client can authenticate through RH-SSO using one of these options:

  • Basic authentication, if it is supported by the client.
  • Token-based authentication.

7.3.1. Basic authentication

If you have enabled the basic authentication in the RH-SSO client adapter configuration for both Red Hat Decision Manager and Decision Server, you can avoid the token grant/refresh calls and call the services as shown in the examples below:

  • For web based remote repositories endpoint:

     curl http://admin:password@localhost:8080/decision-central/rest/repositories
  • For Decision Server:

    curl http://admin:password@localhost:8080/kie-execution-server/services/rest/server/

7.3.2. Token-based authentication

If you want to opt for a more secure option of authentication, you can consume the remote services from both Red Hat Decision Manager and Decision Server using a granted token provided by RH-SSO.

Procedure

  1. In the RH-SSO Admin Console, click the Clients menu item and click Create to create a new client.

    The Add Client page opens.

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

    • Client ID: kie-remote
    • Client protocol: openid-connect
  3. Click Save to save your changes.
  4. Change the token settings in Realm Settings:

    1. In the RH-SSO Admin Console, click the Realm Settings menu item.
    2. Click the Tokens tab.
    3. Change the value for Access Token Lifespan to 15 minutes.

      This gives you enough time to get a token and invoke the service before it expires.

    4. Click Save to save your changes.
  5. After a public client for your remote clients is created, you can now obtain the token by making an HTTP request to the RH-SSO server’s token endpoint using:

    RESULT=`curl --data "grant_type=password&client_id=kie-remote&username=admin&password=password" http://localhost:8180/auth/realms/demo/protocol/openid-connect/token`

    The user used in the command above is an RH-SSO user. For further information, see Section 7.1.3, “Adding a new user”.

  6. To view the token obtained from the RH-SSO server, use the following command:

    TOKEN=`echo $RESULT | sed 's/.*access_token":"//g' | sed 's/".*//g'`

You can now use this token to authorize the remote calls. For example, if you want to check the internal Red Hat Decision Manager repositories, use the token as shown below:

curl -H "Authorization: bearer $TOKEN" http://localhost:8080/decision-central/rest/repositories

7.4. Integrating LDAP and SSL with Red Hat Decision Manager

With Red Hat Decision Manager you can integrate LDAP and SSL through RH-SSO. For information about configuring LDAP and SSL with RH-SSO, see the Red Hat Single Sign-On Server Administration Guide.