On-Premises SSO Module · Redwood Documentation

Introduction

Centralized user access administration in large organizations becomes very important nowadays with new business applications being deployed all the time. For end users having to remember or store user credentials for all these systems can become a tedious task. Therefore, a lot of companies want to introduce single sign-on mechanisms to allow a single login or smart card authentication for the end users to access all their applications.

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 either directly integrate with, for example your Active Directory domain controller using Active Directory Federation Services, or through online middleware providers such as OneLogin, PingIdentity etc. When using SAML Authentication, Single Sign-On (SSO) will be enabled, which means that machines that are part of the domain can transparently login to Redwood.

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

Single Sign-On Authentication via SAML

SAML (Security Assertion Markup Language) is an XML and HTTP based secure, industry-standard way to perform Single Sign-On (SSO) between online applications.

SAML protocol high level description

Figure 1: 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. The customer 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.

Single Sign-On Installation

This section describes how to install the Redwood SSO capabilities.

Prerequisites

Version 9.2.8 or later.
Request, download, and extract the 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 non-Windows systems
- Requires the php-cgi package (as well as dependent packages date, dom, hash, libxml, openssl, pcre, SPL, zlib) to be installed. The minimum php version is 7.1.
- The php.ini file related to your installation must be configured with short_open_tag = "On"
- The Redwood os user must have write access to /var/lib/php/sessions
On Windows systems requires the 32-bit version of the Visual C++ Redistributable for VS 2012 to be installed (vcredist_x86.exe). This can be downloaded from the following location:
Visual C++ Redistributable for Visual Studio

Installation

The following steps are required to make the SSO capabilities available for your Redwood product:

Deploy SSO Web Application

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`

^*It is recommended that you stop Tomcat, copy the redwood-sso.war file and then restart Tomcat to deploy the war file.

Layout of the webapps directory

Figure 2: Layout of the webapps directory

Set correct path to php-cgi

Open the redwood-sso/WEB-INF/web.xml file, set the correct full path to the php-cgi executable and save your changes

    <init-param>
      <param-name>executable</param-name>
      OB<param-value>C:\<!--ENTER FULL PATH HERE-->\webapps\redwood-sso\library\php\php-cgi.exe</param-value>
    </init-param>

    <init-param>
      <param-name>executable</param-name>
      <param-value>D:\Redwood\j2ee\cluster\server1\webapps\redwood-sso\library\php\php-cgi.exe</param-value>
    </init-param>

Example 1: RunMyJobs installed in D:\Redwood

    <init-param>
      <param-name>executable</param-name>
      <param-value>C:\Program Files\Apache Software Foundation\Tomcat 7.0\webapps\redwood-sso\library\php\php-cgi.exe</param-value>
    </init-param>

Example 2: Report2Web installed in Tomcat in C:\Program Files\Apache Software Foundation\Tomcat 7.0

    <init-param>
      <param-name>executable</param-name>
      <param-value>/usr/bin/php-cgi</param-value>
    </init-param>

Example 3: Installed on Unix/Linux

Configure SSO

Now that the installation steps are done, everything can be configured to use Single Sign-On for your Redwood product.

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

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/).

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

Upload Metadata dialog capture

Figure 3: Upload Metadata dialog

Download Redwood’s metadata file

Choose Download Metadata to download the Redwood metadata file.

Provide the downloaded metadata file to the IdP administrators. Only once they have confirmed they have uploaded the metadata and have everything configured can you go to the next step.

Download Metadata dialog capture

Figure 4: Download Metadata dialog

Setup an IdP Claim rule

In your Identity Provider, the Claim rules/transformation rules that are required to 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

Figure 5: Setup for the NameID rule in ADFS.

Verify SSO

Once the IdP administrators have confirmed that the Redwood SSO metadata file is loaded and registered, choose 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 each customer as they are 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

Figure 6: Verify the SSO setup.

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. Please select which attribute should be used to identify users within the Redwood product. We recommend you use email address.

Next step of the SSO configuration

Figure 7: After choose `Next Step` you will be taken to the SSO Configuration screen.

Last step of the SSO configuration

Figure 8: Before being able to fill this in completely, you need the SSO secret. See Force SSO in the Redwood product for instructions, which depend on your Redwood product.

Force SSO in the Redwood product

SSO Setup in RunMyJobs

Import saml.car file

For RunMyJobs installations import the saml.car file using your preferred promotion mechanism. For example, navigate to Promotion -> Import -> New Import:

Importing saml.car screen capture

Figure 9: Importing saml.car

Run SAML_GetPhpToken

In a separate window log into RunMyJobs via non-sso login method (https://10.44.0.184:8443/scheduler/?rw_no_sso=1) and run the job SAML_GetPhpToken.

Capture of the submit wizard of SAML_GetPhpToken

Figure 10: Choose the correct definition in the Submit Wizard and hit Submit

Capture of the submit wizard of SAML_GetPhpToken

Figure 11: Once the job has run, choose on the job and choose on the file called secret.

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

Add external Registry Entry

Add a registry entry /configuration/security/sso/external to redirect product logins to the SSO web application 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

Figure 12: /configuration/security/sso/external registry entry

Add nexturiparameter Registry Entry

If you want to make sure that end users end up at their originally requested URL (for example a perma-link or extension point) add the registry entry /configuration/security/sso/nexturiparameter and set its value to ssoUrl.

SSO Setup in Report2Web

Setup Alternative Login Page

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

Within the Environment Menu and choose on the System Security icon. In the upper right corner of the System Security summary page, choose the Edit link. Once in the System Security Wizard, choose the Next button to advance to the Alternative URLs page.

Choose the Yes option to Enable Alternative Sign-in Page.

Fill in the Sign-in Page URL using the following construct:

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 when 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 choosing 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 construct 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 choose the Login button 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://:/redwood-sso/?ssoUrl=

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

Figure 13: Capture of the Report2Web configuration System Security > Alternative URL's"

Retrieve 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 running Report2Web with a Microsoft SQL database, the <jdbc_connection_string> is built as follows:

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

So, the complete execution might look as follows:

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

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

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

So, the complete execution might look as follows:

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. Navigate to that file, open in the text editor of your choice and copy the entire string and save it before going back to the SSO configuration tab.

SSO Configuration

In the SSO configuration (if you lost this page in the process you can go directly to: http://<host>:<port>/redwood-sso/?action=configurations/edit/) paste the secret string into the Product SSO secret field, enter the URL of the product including the protocol (https://), domain name (10.44.0.184), and port (8443) and the product suffix (RunMyJobs default is /redwood, or /r2w/signIn.do for Report2Web).

Capture of Redwood SSO configuration

Figure 14: Redwood SSO configuration

Choose Save Configuration to store the SSO configuration setup. After choosing Save Configuration you will be redirected to the confirmation page. On choosing Login Page you will be taken into the product as you have already authenticated with the IdP during the verify step.

Capture of saved Redwood SSO configuration

Figure 15: Saved Redwood SSO configuration

Upgrade SSO Web Application

The following steps are required to upgrade the SSO web application to a version:

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`

^*It is recommended that you stop Tomcat, copy the redwood-sso.war file and then restart Tomcat to deploy the war file.

Rename the existing sso directory:

mv redwood-sso redwood-sso-old

Deploy the new SSO Web Application

Put the new redwood-sso.war file in the webapps directory and wait for it to deploy:

Restore configuration settings

Copy the following files into the corresponding redwood-sso directories:

redwood-sso-old/config/sso.conf.
redwood-sso-old/config/metadata.conf.
redwood-sso-old/WEB-INF/web.xml.

After confirmation of the working of the solution, redwood-sso-old can be removed.

Troubleshooting

Missing JSON Module

The following was logged when the JSON module was missing from an older PHP release, more recent PHP releases ship with the standard JSON module:

[21-Oct-2022 07:04:52 UTC] PHP Fatal error:  Uncaught Exception: /opt/redwood/j2ee/cluster/server1/webapps/redwood-sso/config/redwoodsaml/config/config.php ['application']:
    The option 'baseURL' is not a valid string value. in /opt/redwood/j2ee/cluster/server1/webapps/redwood-sso/library/saml/lib/SimpleSAML/Configuration.php:731
Stack trace:
#0 /opt/redwood/j2ee/cluster/server1/webapps/redwood-sso/library/saml/lib/SimpleSAML/Utils/HTTP.php(890): SimpleSAML\Configuration->getString('baseURL', '')
#1 /opt/redwood/j2ee/cluster/server1/webapps/redwood-sso/library/saml/lib/SimpleSAML/Utils/HTTP.php(959): SimpleSAML\Utils\HTTP::getSelfURL()
#2 /opt/redwood/j2ee/cluster/server1/webapps/redwood-sso/library/saml/lib/SimpleSAML/SessionHandlerPHP.php(213): SimpleSAML\Utils\HTTP::isHTTPS()
#3 /opt/redwood/j2ee/cluster/server1/webapps/redwood-sso/library/saml/lib/SimpleSAML/Session.php(358):
    Simplee/cluster/server1/webapps/redwood-sso/library/saml/lib/SimpleSAML/XHTML/Template.php(914): SimpleSAML\Locale\Trans
    in /opt/redwoodleSAML/Locale/Translate.php on line 393
    SAML\SessionHandlerPHP->getCookieSessionId()
#4 /opt/redwood/j2ee/cluster/server1/webapps/redwood-sso/library/saml/lib/SimpleSAML/Session.php(285): SimpleSAML\Session::getSession() in
    /opt/redwood/j2ee/cluster/server1/webapps/redwood-sso/library/saml/lib/SimpleSAML/Configuration.php on line 731
[23-Oct-2022 11:35:38 UTC] PHP Fatal error:  Uncaught Error: Call to opt/redwood/j2ee/cluster/server1/webapps/redwood-sso/library/saml/lib/SimpleSAML/Locale/Translate.php:393
Stack trace:
#0 /opt/jsolupleSAML/Locale/Translate.php(446): SimpleSAML\Locale\Translate->readDictionaryJSON('/opt/redwood/j2e...')
#1 /opt/redwood/j2ee/cluster/server1/webapps/redwood-sso/library/saml/lib/SimpleSAML/Locale/Translate.php(115):
    SimpleSAML\Locale\T/redwood/j2ee/cluster/server1/webapps/redwood-sso/library/saml/lib/SimpleSAML/Locale/Translate.php(150): SimpleSAML\Locale\Translate->getDictionary('errors')
#3 /opt/redwood/j2ee/cluster/server1/webapps/redwood-sso/library/saml/lib/SimpleSAML/Locale/Translate.php(293):
    SimpleSAML\Locale\Translate->getTag('title_UNHANDLED...')
#4 /opt/redwood/j2ee/cluster/server1/webapps/redwood-sso/library/saml/lib/SimpleSAML/XHTML/Template.php(914):
    SimpleSAML\Locale\Trans in /opt/redwood/j2ee/cluster/server1/webapps/redwood-sso/library/saml/lib/SimpleSAML/Locale/Translate.php on line 393

Resolution

Install the JSON module for your PHP or install a PHP version with JSON support.

Introduction

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

Single Sign-On Authentication via SAML

SAML (Security Assertion Markup Language) is an XML and HTTP based secure, industry-standard way to perform Single Sign-On (SSO) between online applications.

SAML protocol high level description

Figure 1: SAML protocol high level description

Identity Providers (IdP)

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.

Single Sign-On Installation

This section describes how to install the Redwood SSO capabilities.

Prerequisites

Redwood SSO 1.0.0.0 to 1.0.0.4 (inclusive)
Version 9.2.8 or later.
Request, download, and extract the 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 non-Windows systems
- Requires the php5-cgi package (as well as dependent packages date, dom, hash, libxml, openssl, pcre, SPL, zlib) to be installed. The minimum php version is 5.6.20, ensure JSON support is available.
- The php.ini file related to your installation must be configured with short_open_tag = "On"
- The Redwood os user must have write access to /var/lib/php/sessions
On Windows systems requires the 32-bit version of the Visual C++ Redistributable for VS 2012 to be installed (vcredist_x86.exe). This can be downloaded from the following location:
Visual C++ Redistributable for Visual Studio

Installation

The following steps are required to make the SSO capabilities available for your Redwood product:

Deploy SSO Web Application

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`

^*It is recommended that you stop Tomcat, copy the redwood-sso.war file and then restart Tomcat to deploy the war file.

Layout of the webapps directory

Figure 2: Layout of the webapps directory

Set correct path to php-cgi

Open the redwood-sso/WEB-INF/web.xml file, set the correct full path to the php-cgi executable and save your changes

    <init-param>
      <param-name>executable</param-name>
      OB<param-value>C:\<!--ENTER FULL PATH HERE-->\webapps\redwood-sso\library\php\php-cgi.exe</param-value>
    </init-param>

    <init-param>
      <param-name>executable</param-name>
      <param-value>D:\Redwood\j2ee\cluster\server1\webapps\redwood-sso\library\php\php-cgi.exe</param-value>
    </init-param>

Example 1: RunMyJobs installed in D:\Redwood

    <init-param>
      <param-name>executable</param-name>
      <param-value>C:\Program Files\Apache Software Foundation\Tomcat 7.0\webapps\redwood-sso\library\php\php-cgi.exe</param-value>
    </init-param>

Example 2: Report2Web installed in Tomcat in C:\Program Files\Apache Software Foundation\Tomcat 7.0

    <init-param>
      <param-name>executable</param-name>
      <param-value>/usr/bin/php5-cgi</param-value>
    </init-param>

Example 3: Installed on Unix/Linux

Configure SSO

Now that the installation steps are done, everything can be configured to use Single Sign-On for your Redwood product.

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

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/).

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

Upload Metadata dialog capture

Figure 3: Upload Metadata dialog

Download Redwood’s metadata file

Choose Download Metadata to download the Redwood metadata file.

Provide the downloaded metadata file to the IdP administrators. Only once they have confirmed they have uploaded the metadata and have everything configured can you go to the next step.

Download Metadata dialog capture

Figure 4: Download Metadata dialog

Setup an IdP Claim rule

In your Identity Provider, the Claim rules/transformation rules that are required to 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

Figure 5: Setup for the NameID rule in ADFS.

Verify SSO

Verify SSO configuration

Figure 6: Verify the SSO setup.

Next step of the SSO configuration

Figure 7: After choose `Next Step` you will be taken to the SSO Configuration screen.

Last step of the SSO configuration

Figure 8: Before being able to fill this in completely, you need the SSO secret. See Force SSO in the Redwood product for instructions, which depend on your Redwood product.

Force SSO in the Redwood product

SSO Setup in RunMyJobs

Import saml.car file

For RunMyJobs installations import the saml.car file using your preferred promotion mechanism. For example, navigate to Promotion -> Import -> New Import:

Importing saml.car screen capture

Figure 9: Importing saml.car

Run SAML_GetPhpToken

In a separate window log into RunMyJobs via non-sso login method (https://10.44.0.184:8443/scheduler/?rw_no_sso=1) and run the job SAML_GetPhpToken.

Capture of the submit wizard of SAML_GetPhpToken

Figure 10: Choose the correct definition in the Submit Wizard and hit Submit

Capture of the submit wizard of SAML_GetPhpToken

Figure 11: Once the job has run, choose on the job and choose on the file called secret.

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

Add external Registry Entry

Add a registry entry /configuration/security/sso/external to redirect product logins to the SSO web application 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

Figure 12: /configuration/security/sso/external registry entry

Add nexturiparameter Registry Entry

SSO Setup in Report2Web

Setup Alternative Login Page

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

Choose the Yes option to Enable Alternative Sign-in Page.

Fill in the Sign-in Page URL using the following construct:

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

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

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://:/redwood-sso/?ssoUrl=

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

Figure 13: Capture of the Report2Web configuration System Security > Alternative URL's"

Retrieve SAML secret

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 running Report2Web with a Microsoft SQL database, the <jdbc_connection_string> is built as follows:

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

So, the complete execution might look as follows:

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

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

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

So, the complete execution might look as follows:

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

SSO Configuration

Capture of Redwood SSO configuration

Figure 14: Redwood SSO configuration

Capture of saved Redwood SSO configuration

Figure 15: Saved Redwood SSO configuration

Upgrade SSO Web Application

The following steps are required to upgrade the SSO web application to a version:

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`

^*It is recommended that you stop Tomcat, copy the redwood-sso.war file and then restart Tomcat to deploy the war file.

Rename the existing sso directory:

mv redwood-sso redwood-sso-old

Deploy the new SSO Web Application

Put the new redwood-sso.war file in the webapps directory and wait for it to deploy:

Restore configuration settings

Copy the following files into the corresponding redwood-sso directories:

redwood-sso-old/config/sso.conf.
redwood-sso-old/config/metadata.conf.
redwood-sso-old/WEB-INF/web.xml.

After confirmation of the working of the solution, redwood-sso-old can be removed.

Troubleshooting

Missing JSON Module

The following was logged when the JSON module was missing from an older PHP release, more recent PHP releases ship with the standard JSON module:

[21-Oct-2022 07:04:52 UTC] PHP Fatal error:  Uncaught Exception: /opt/redwood/j2ee/cluster/server1/webapps/redwood-sso/config/redwoodsaml/config/config.php ['application']:
    The option 'baseURL' is not a valid string value. in /opt/redwood/j2ee/cluster/server1/webapps/redwood-sso/library/saml/lib/SimpleSAML/Configuration.php:731
Stack trace:
#0 /opt/redwood/j2ee/cluster/server1/webapps/redwood-sso/library/saml/lib/SimpleSAML/Utils/HTTP.php(890): SimpleSAML\Configuration->getString('baseURL', '')
#1 /opt/redwood/j2ee/cluster/server1/webapps/redwood-sso/library/saml/lib/SimpleSAML/Utils/HTTP.php(959): SimpleSAML\Utils\HTTP::getSelfURL()
#2 /opt/redwood/j2ee/cluster/server1/webapps/redwood-sso/library/saml/lib/SimpleSAML/SessionHandlerPHP.php(213): SimpleSAML\Utils\HTTP::isHTTPS()
#3 /opt/redwood/j2ee/cluster/server1/webapps/redwood-sso/library/saml/lib/SimpleSAML/Session.php(358):
    Simplee/cluster/server1/webapps/redwood-sso/library/saml/lib/SimpleSAML/XHTML/Template.php(914): SimpleSAML\Locale\Trans
    in /opt/redwoodleSAML/Locale/Translate.php on line 393
    SAML\SessionHandlerPHP->getCookieSessionId()
#4 /opt/redwood/j2ee/cluster/server1/webapps/redwood-sso/library/saml/lib/SimpleSAML/Session.php(285): SimpleSAML\Session::getSession() in
    /opt/redwood/j2ee/cluster/server1/webapps/redwood-sso/library/saml/lib/SimpleSAML/Configuration.php on line 731
[23-Oct-2022 11:35:38 UTC] PHP Fatal error:  Uncaught Error: Call to opt/redwood/j2ee/cluster/server1/webapps/redwood-sso/library/saml/lib/SimpleSAML/Locale/Translate.php:393
Stack trace:
#0 /opt/jsolupleSAML/Locale/Translate.php(446): SimpleSAML\Locale\Translate->readDictionaryJSON('/opt/redwood/j2e...')
#1 /opt/redwood/j2ee/cluster/server1/webapps/redwood-sso/library/saml/lib/SimpleSAML/Locale/Translate.php(115):
    SimpleSAML\Locale\T/redwood/j2ee/cluster/server1/webapps/redwood-sso/library/saml/lib/SimpleSAML/Locale/Translate.php(150): SimpleSAML\Locale\Translate->getDictionary('errors')
#3 /opt/redwood/j2ee/cluster/server1/webapps/redwood-sso/library/saml/lib/SimpleSAML/Locale/Translate.php(293):
    SimpleSAML\Locale\Translate->getTag('title_UNHANDLED...')
#4 /opt/redwood/j2ee/cluster/server1/webapps/redwood-sso/library/saml/lib/SimpleSAML/XHTML/Template.php(914):
    SimpleSAML\Locale\Trans in /opt/redwood/j2ee/cluster/server1/webapps/redwood-sso/library/saml/lib/SimpleSAML/Locale/Translate.php on line 393

Resolution

Install the JSON module for your PHP or install a PHP version with JSON support.

onsiteTopic