EMERSE Single Sign On with Shibboleth Guide

This guide outlines the configuration of Shibboleth, a single sign-on login system, and its integration with EMERSE. Setting up EMERSE with Tomcat and Httpd is out of the scope of this section, please refer to Installation Guide and More for details.

Single sign-on (SSO) is an authentication process that allows users to access multiple applications or systems with just one set of login credentials (such as username and password). Instead of requiring users to remember and enter separate login credentials for each application, SSO enables them to authenticate once and then seamlessly access various resources without needing to re-enter their credentials.

EMERSE 6.6 and subsequent versions provide Single Sign-On (SSO) support via integration with an SSO provider, such as Shibboleth. The instructions in this document assume the setup of Shibboleth on Red Hat Enterprise Linux 8.9 with Apache HTTPD and Tomcat 9.X with AJP protocol.

If you encounter errors when configuring shibboleth, it can be helpful to have an idea of where the issue lies. There are a few things you can check that should tell you whether shibboleth, httpd, tomcat, or EMERSE is to blame for the problem.

You need to set the preauth.loginUrl in the emerse.properties file. If this is set, then the login page should change so that only the login button appears without a username or password entry. This login button will redirect the browser to the given url. That URL should be then redirect to the IdP beginning the SSO flow. See here.

If you are expecting to see the IdP page before seeing any page served from the EMRESE app, then you need to change the httpd configuration to force auth earlier. We aren’t familiar on how to set up this use case, but it will probably involve changing the require shibboleth line to require valid-user, but check with the shibboleth documentation here.

This is probably an issue with the shibboleth configuration, such as public/private keys. It could be a lot of things, so we can’t offer a lot of help here, but it would probably be between the /etc/shibboleth/ configuration and the IdP’s configuration. You may need to restart shibd or httpd for changes to take effect.

Either HTTPD isn’t ending up with an authenticated user, or it isn’t passing it to tomcat, or tomcat is discarding it dispatching the request to EMERSE, or EMERSE isn’t looking in the right place for the user name, or the username sent from HTTPD / the IdP doesn’t match exactly with the user id in the LOGIN_ACCOUNT table.

First, you can check httpd’s access_log to see if it has a username for requests to EMERSE. This file is probably located at /etc/httpd/logs/access_log or var/log/httpd/access_log or somewhere similar. Lines by default should look like:

The third item on the line is the authenticated username of the request. This will appear as "" if there is no such username. If you notice this name doesn’t match the a user id in the LOGIN_ACCOUNT table in emerse (including case) then try changing the user id in EMERSE (or creating an new account) to see if login works. If requests after login has been done successfully still don’t have a username here, then there is an issue within httpd or between httpd and shibd daemon where the authentication information isn’t being consumed by httpd. Hard to say what’s going wrong there.

If the login name does appear in the httpd access_log, but it’s not the one you want, change the (or add a) REMOTE_USER attribute on the <ApplicationDefaults> element in the /etc/shibboleth/shibboleth.xml file, and restart shibd and httpd. Be sure the attribute you want is included in the /etc/shibboleth/attribute-map.xml file as it can’t use a value it doesn’t fetch from the IdP. You may need to reconfigure the IdP or re-generated the SP metadata and re-import it into the IdP so that the correct attributes are passed.

If httpd has the right username, then we can check to see if it’s sending it to EMERSE. For this, we will sniff the TCP packets being sent to tomcat, which requires the tcpdump command and root access typically. First, we need to get the name of the loopback device, which is typically lo on linux. However, you can check by doing a ip addr and looking for the entry that mentions localhost, loopback, or the ip 127.0.0.1. If ip addr doesn’t work, try ifconfig (the older command). Once you have that, issue the below tcpdump command with the loopback device name, and the port tomcat’s listening on for AJP requests. That’s the port in the conf/server.xml file for the AJP connector you configured above. It’s typically 8009, but we listed it as MY_AJP_PORT in the documentation above.

The tcp dump command will hang until you kill it with control-C. As it hangs, it will print any packets seen on the port. This could be a lot of text if you have a lot of traffic or none. While this command is running, do the login flow until you think you should be logged in, and then look through the mess of packet text for your username. Obviously requests before authentication is done won’t have your authenticated username on them, so you’re looking for roughly the last request you made. So, this is best done when there is little to no traffic. AJP is a binary protocol, but must of the data its carrying is text. Requests start with the URL requests, then some header information, and shortly after that will be AJP secret configured in the httpd config file and also in the AJP connector in Tomcat, and right after that is the authenticated username, if present. Most of the periods in the output signify non-printable characters. See below for an example:

If you see the username in the request, the problem lies in tomcat or EMERSE. Otherwise, in HTTPd. I’m not sure what would cause HTTPd to not pass the username if it’s already logging it in its own access_log, but I would look at the proxy pass rules or other auth-based commands in the configuration file.

If it is being passed, then make sure tomcat’s conf/server.xml has the tomcatAuthentication attribute set to false on the AJP connector element, possibly all connector elements. If it isn’t, Tomcat discards the authenticated username sent on AJP. Really, this file should be able to be replaced with exactly this (except for the AJP secret):

Tomcat has a lot of commented out stuff by default which is nice for documentation, but sometimes it’s more clear to only include what’s actually being used, and properly deleting everything else.

If this all looks correct, then make sure EMERSE has preauth enabled as a spring profile. This means the spring preauth should be part of the value of the spring.profiles.active property. EMERSE looks in a few places for configuration, so read through the documentation on that and check the various places. Only the "most siginifcant" definition of the spring.profiles.active property is used, so if there are multiple definitions, it’s probably best to consolodate them into one so it’s less confusing.

Rather than logging at static files to see how things are configured, it can be helpful to look directly at the process itself to see how it ended up getting run. This can sometimes find issues where you thing one thing is happening but another thing is actually happing. You can see what the exact commandline of the running tomcat process is by doing ps ax | grep tomcat This alows you to see what the java properties are, as these are parameters to the program; options starting with -Dname=value define the java property name to have value value.

To check envirnoment variables of a running process, get the PID of the running process, which is the first number on the line output by the that ps ax | grep tomcat command, then look at cat /proc/PID/environ where PID is the PID of the process. This will list environment variables in the form name=value separated by binary zeros. (Yes, that’s an nonprintable character so they kinda run together as seen on the console.) /proc/PID/environ is on the "proc" file system, which is not a real file system; reading from these "files" actually causes the OS to query the current state of the associated process. You typically have to be root to read these files, or ower of the process. Not all editions/configurations of linux use the proc file system, so you may not have it.

If you still have trouble getting SSO to work, you can contact us.