Troubleshooting OpenID setup

This page provides general troubleshooting for the setup of an OpenID login on Matillion ETL.

Note

Due to the technical nature of this guide, it is highly recommended a member of the Matillion support team be consulted before beginning and/or if anything about this document is unclear.

---

Case sensitivity

Case sensitivity applies to OpenID when adding users. For example, James.Smith, james.smith, and JAMES.SMITH are each considered different users.

---

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 attributes and scopes are supplied for each identity provider (IdP), including, for example, unique/preferred usernames or email addresses. 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

Warning

Since OpenID log messages contain sensitive user information, you should revert your logging settings once you have completed your debugging activities. Additionally, consider archiving logs containing OpenID logging messages (zipping and copying elsewhere) and removing them from the Matillion ETL host's disk.