Troubleshooting OpenID Setup

Overview

This guide will provide general troubleshooting for the setup of an OpenID login on Matillion ETL.

Fixing Tomcat library conflict

When configuring an OpenID, an authentication library conflict may occur after upgrading to Tomcat 8.5.51+ without updating Matillion ETL. This conflict becomes evident after restarting the Matillion ETL instance, causing the server to become inaccessible from the UI and an error message to be displayed during the login process.

To prevent this conflict, we recommend that you either update to Matillion ETL 1.44.11 or later, or run the script below via an SSH client:

sudo su
cd /usr/share/emerald/WEB-INF/lib
wget https://boylesoftware.com/maven/repo-os/org/bsworks/catalina/authenticator/oidc/tomcat-oidcauth/2.3.0/tomcat-oidcauth-2.3.0-tomcat5.jar
# Remove KMS library into the tomcat lib
rm -f /usr/share/tomcat/lib/KMSJndiRealm*.jar
# Link tomcat oidcauth to tomcat lib
rm -f /usr/share/tomcat/lib/tomcat-oidcauth.jar
ln -s /usr/share/emerald/WEB-INF/lib/tomcat-oidcauth-2.3.0-tomcat5.jar /usr/share/tomcat/lib/tomcat-oidcauth.jar
/etc/init.d/tomcat restart

Removing an OpenID configuration

In the event an error occurs during the setup of an OpenID login that leads to access to the Matillion ETL instance becoming restricted, the OpenID configuration may need to be removed. To do this, take the following steps:

1. Connect to the Matillion ETL instance using SSH (read this article for details).

2. Make a backup of the /etc/tomcat/context.xml file.

3. Open the context.xml file.

4. Remove the node labelled <valve/> from the file.

5. Save and close this file.

6. Restart Tomcat using the following command:

tomcat sudo service tomcat restart

Using custom user attributes and scopes

When you configure OpenID for SSO authentication to Matillion ETL, default values for user attribute and scope are supplied for each identity provider (IdP), including, for example, unique/preferred username or email address. However, if you uniquely identify user accounts by an attribute other than these default values (Employee ID, for example), the default user attribute must be overridden by the preferred unique identifier. In some cases, it may also be necessary to specify a non-default scope.

When providing a custom user attribute, you may need to refer to your IdP's documentation and its admin console to understand which scope must be provided for Matillion ETL to correctly identify and authenticate users. Please have this information available or be able to log in to your IdP's admin console when debugging OpenID configuration with Matillion Support so we can best assist.

Enabling OpenID logging

When you encounter errors while configuring or authenticating using OpenID, you may find that your Matillion ETL log file includes little or no messaging. By default, OpenID logging is not enabled because it includes sensitive information like usernames and email addresses. You can temporarily enable OpenID logging by following these steps:

1. SSH to the instance and gain root access.

sudo su -

2. Open the /etc/tomcat/logging.properties file in your editor of choice, after first creating a backup of the file.

3. Add the following line at the bottom of the file:

org.bsworks.level = FINE

4. Save and close the file, then restart Tomcat with this command:

systemctl restart tomcat

5. Launch a new browser window and attempt configuration or authentication via OpenID.

6. Once you have observed any errors in the interface, review the OpenID messages in the Matillion ETL log file by clicking Download Server Log from the Admin menu (if you are able to log in with admin privileges). Alternatively, you can find the log file at /var/log/tomcat/catalina.out.