On-Premises SSO Module 2.0.0.0

Redwood applications can be configured to authenticate against an external security provider which supports the Security Assertion Markup Language (SAML) standard, as defined by RFC 7522. SAML can be used to directly integrate with, for example, your Active Directory domain controller using Active Directory Federation Services, or through online middleware providers such as OneLogin and PingIdentity. When using SAML Authentication, Single Sign-On (SSO) will be enabled, which means that computers that are part of the domain can transparently login to Redwood.

This document describes how to enable Redwood applications to use SAML authentication.

SSO Authentication via SAML

SAML is an XML and HTTP based secure, industry-standard way to perform SSO between online applications.

SAML protocol high level description

Identity Providers (IdP)

Redwood SSO allows integration with any authentication provider that supports SAML. The IdP is part of the customer's network and their responsibility. You will need to provide a file with the IdP’s metadata, and then upload Redwood SSO metadata to the IdP, completing a secure handshake between the two.

Service Provider (SP)

Redwood SSO is the service provider. Once configured, it will redirect users to the IdP to authenticate them, then pass them to the Redwood product already logged-in.

SSO Installation

This section describes how to install the Redwood SSO capabilities.

Prerequisites

RunMyJobs 9.2.8 or later.
Requested, downloaded, and extracted redwood-sso.zip file.
Redwood product configured to run in https mode.
Users base (LDAP, database, application authentication) has been configured for the Redwood product with a matching ID field (preferred: email address) that will be used from the Identity Provider. Users are not automatically created, but can be imported automatically from the user base on first login (RunMyJobs).
On Windows systems, the 32-bit version of the Visual C++ Redistributable for VS 2012 (vcredist_x86.exe) must be installed. This can be downloaded from the following location:
Visual C++ Redistributable for Visual Studio

Installation

Move or copy the redwood-sso.war file into one of the following directories:

Product	Path
RunMyJobs	`${INSTALL_DIR}/j2ee/cluster/server1/webapps`
Report2Web	`${TOMCAT_DIR}/webapps`

For Report2Web, Redwood recommends that you stop Tomcat, copy the redwood-sso.war file, and then restart Tomcat to deploy the war file.

Layout of the webapps directory

SSO Configuration

The example setup below assumes your Redwood product is running on ip-address 10.44.0.184 and port 8443.

1. Upload IdP Metadata

Request the metadata for your IdP in XML format.

Once obtained, navigate to https://10.44.0.184:8443/redwood-sso/ (you will be redirected to https://10.44.0.184:8443/redwood-sso/?action=configurations/upload/).

Click Choose file, navigate to your metadata file, and then click Upload Metadata.

Upload Metadata dialog capture

2. Download Redwood’s Metadata File

Click Download Metadata to download the Redwood metadata file.

Provide the downloaded metadata file to the IdP administrators. You cannot continue to the next step until they have confirmed they have uploaded the metadata and have everything configured.

Download Metadata dialog capture

3. Set Up an IdP Claim Rule

In your Identity Provider, the Claim rules/transformation rules that must be set with the name "NameID" are:

Email: This will be used as your username.
DisplayName: Used for first name last name.
Groups: Used to filter access groups to set correct access.

Other rules can be sent over and will be ignored.

Example: ADFS setup

Edit Active Directory claims rule capture

4. Verify SSO

Once the IdP administrators have confirmed that the Redwood SSO metadata file is loaded and registered, click Next Step: Verify. This should redirect you to your IdP and shown a domain login screen or custom login provider. This part will look different for every customer, because each will be using their own IdP. For this document, we are using the Redwood IdP. To get to the Verify page without the previous steps you can use following URL: http://<host>:<port>/redwood-sso/?action=configurations/verify/.

Verify SSO configuration

Once logged in to the IdP, you will be redirected back to the final step: configuring SSO. You will be shown a drop down with a list of attributes. Yours will look different to below depending on the attributes passed back by the IdP. Select which attribute should be used to identify users within the Redwood product. We recommend you use an email address.

Next step of the SSO configuration

Last step of the SSO configuration

Before being able to enter all of this information, you will need the SSO secret. See the next section for details.

5. Force SSO in the Redwood product

SSO Setup in RunMyJobs

A. Import the saml.car File

For RunMyJobs installations, import the saml.car file.

B. Run SAML_GetPhpToken

In a separate window, log into RunMyJobs via the non-SSO login method (https://10.44.0.184:8443/scheduler/?rw_no_sso=1) and run the Process Definition named SAML_GetPhpToken. Once the Process Definiton has run, locate and click the file named secret in the Detail View.

Capture of the Submit Wizard of SAML_GetPhpToken

This file will contain a long string. Copy the entire string and store it before going back to the SSO Configuration screen.

C. Add the External Registry Entry

To redirect product logins to the SSO web application, add the registry entry /configuration/jcs/security/sso/external with value https://10.44.0.184:8443/redwood-sso/.

If you want to skip the redwood-sso login page, add ?action=authenticates/authenticate/ to the URL.

Capture of the registry editor

D. Add the nexturiparameter Registry Entry

If you want to make sure that end users end up at their originally requested URL, add the registry entry /configuration/jcs/security/sso/nexturiparameter and set its value to ssoUrl.

SSO Setup in Report2Web

Log into Report2Web as a user associated with the Super Administrator Role.

In the Environment menu, click the System Security icon. In the upper right corner of the System Security summary page, click Edit. Once in the System Security Wizard, click Next to advance to the Alternative URLs page.

Click Yes to enable the Alternative Sign-in Page.

Enter the Sign-in Page URL using the following syntax:

https://<yourServer>:<yourPort>/redwood-sso/?action=authenticate/authenticates

Provide a value for the Sign-in Error Page URL (https://<yourHelpDeskURL>) as applicable. This will redirect the user to the specified page in the event that the login attempt is unsuccessful for any reason.

The Sign-in Page Override is used by administrators to log in to Report2Web if the Alternative Sign-in page is not functioning properly, or if Report2Web application users that cannot be authenticated by SAML need to sign-in. The required value specified here will be used in conjunction with an override token (?altSignInPageOverride=) in a complete URL.

For example, given a value specified of secret as the Sign-in Page Override, the corresponding URL to gain entry to Report2Web without SAML authentication might be:

https://<yourServer>:<yourPort>/r2w/?altSignInPageOverride=secret

Provide a value for the Sign-out URL, which will redirect the user to the specified page after clicking the Log Out icon, or if the user has been automatically logged out by the system to a session timeout as configured by the administrator. If you would like the user to be redirected to the Redwood-SSO login page, use the URL syntax below. This will present the user with the Redwood-SSO login page, which will honor the user’s current credentials, and prompt the user to click Login to regain access to Report2Web.

https://<yourServer>:<yourPort>/redwood-sso/

If you would like to force the expiration of the user’s credentials upon logout, it is recommended that the following is appended to the Sign-out URL:

https://<yourServer>:<yourPort>/redwood-sso/?ssoUrl=

Capture of the Report2Web configuration System Security/> Alternative URL's

B. Retrieve the SAML Secret

Copy the saml-r2w.jar file extracted in an earlier step to the Tomcat lib directory on your Report2Web server. Open a command prompt and change to the Tomcat lib directory. From the command prompt, run the following:

java -jar saml-r2w.jar <control_DB_username> <password> <jdbc_connect_string> <output file name>

Where:

<control_DB_username> is the name of the user Report2Web uses to connect to the control database.
<password> is the password associated with the user above.
<jdbc_connect_string> specifies the connection to your Report2Web control database. This connection string will vary depending on whether you are running with a Microsoft SQL or Oracle database. See examples below for further details.
<output_file_name> specifies the text file created that will contain the SAML secret needed to complete the setup.

If you are running Report2Web with a Microsoft SQL database, the <jdbc_connection_string> is as follows:

jdbc:sqlserver://<DB_server_name>:<DB_server_port>;databaseName=<your_R2W_control_DB_name>

So, the complete execution might look like this:

java -jar saml-r2w.jar redwoodAgent password jdbc:sqlserver://r2w.example.local:1433;databaseName=r2w_control saml_secret.txt

If you are running Report2Web with an Oracle database environment, the <jdbc_connection_string> is as follows:

jdbc:oracle:thin:@<DB_server_name>:<DB_server_port>/<your_R2W_control_DB_name>

So, the complete execution might look like this:

java -jar saml-r2w.jar redwoodAgent password jdbc:oracle:thin:@r2w.example.local:1433/r2w_control saml_secret.txt

After executing the saml-r2w application, the generated secret file (written to the Tomcat lib directory) will contain a long string. Open that file and copy the entire string and save it before going back to the SSO configuration tab.

6. SSO Configuration

In the SSO Configuration screen (http://<host>:<port>/redwood-sso/?action=configurations/edit/), paste the secret string into the Product SSO secret field. Then enter the URL of the product, including the protocol (https://), domain name (10.44.0.184), and port (8443) and the product suffix (the RunMyJobs default is /redwood, and the Report2Web default is /r2w/signIn.do).

Capture of Redwood SSO configuration

Click Save Configuration to store the SSO configuration setup. You will be redirected to the confirmation page. Click Login Page to navigate to the product (you have already authenticated with the IdP during the verify step).

Capture of saved Redwood SSO configuration

7. Upgrade the SSO Web Application

The following steps are required to upgrade the SSO web application.

A. Secure and Remove the Old SSO Web Application

Remove the redwood-sso.war file from one of the following directories:

Product	Path
RunMyJobs	`${INSTALL_DIR}/j2ee/cluster/server1/webapps`
Report2Web	`${TOMCAT_DIR}/webapps`