Apache Tomcat SSO: protect a Java app with the SSOGEN Java agent

The SSOGEN Java agent (SSO4J) adds single sign-on and multi-factor authentication to a Java web application running on Tomcat 9, 10.1 or 11, or built with Spring Boot 3.5, without changing the application’s code. It works like the Web Agent for Apache: the person signs in through SSOGEN, and the application receives the signed-in user. It uses the same agent key, sign-in policy and sign-out behavior.

Good to know before you start

• Two people, two jobs. The SSOGEN administrator registers the application and copies the generated settings. The application team pastes them on the application server. Nothing is enrolled: no command, no token and no certificate authority file on the server.
• Where the files come from. The agent’s jar files are in the java-agent folder of SSOGEN download you installed from.
• Versions. The agent needs version 4.1.1 or later to use the agent key. The agent jars for Tomcat 9 run on Java 8 or later; the jars for Tomcat 10.1 and 11 need Java 11 or later; the Spring Boot starter needs Java 17 or later. Spring Boot 4 is not supported yet.

Part A: register the application in SSOGEN (the administrator)

1. Register the application as a Web Agent application, exactly as in Part A of the Web Agent guide. Use the address people type in their browser as the Client URL.
2. Activate it and assign people (see Assign, test and activate an application).
3. Open the application, then the Integration tab. The section Agent key is shared with the Apache configuration above it. Select Generate agent key.
4. Scroll to Java Agent (SSO4J) for Tomcat and Spring Boot. It shows a settings file for this application. After you generated the key, the key is filled into it, once. Select Copy Java Agent settings. SSOGEN keeps only a hash of the key and cannot show it again, so copy the settings before you leave the page (select I have copied it in the agent key box when you have).

The settings file has one setting per line: the SSOGEN address, the application’s address and client ID, the agent key, the place of the session secret file, and the protected paths (all of them by default).

Part B: install on the application server (the application team)

Do this on each application server, as the account that runs Tomcat.

1. Copy the agent. From the java-agent folder copy ssogen-web-agent-java-core-<version>.jar and, for Tomcat 9, ssogen-web-agent-java-tomcat9-<version>.jar, or, for Tomcat 10.1 and 11, ssogen-web-agent-java-tomcat10-<version>.jar, into the Tomcat lib folder. A Spring Boot application uses ssogen-web-agent-java-spring-boot-<version>.jar together with the core jar and ssogen-web-agent-java-servlet-jakarta-<version>.jar, on its class path.
2. Create the session secret. The Integration tab shows the commands to copy: create the folder /etc/ssogen/agent, and write 32 random bytes in base64 to /etc/ssogen/agent/session.secret (openssl rand -base64 32), readable only by the Tomcat account. Use the same secret file on every server of the application, so a person’s sign-in is accepted wherever the next request lands.
3. Save the settings file as /etc/ssogen/agent/agent.properties with mode 0600. The agent refuses to start with a key that another account can read or write. To keep the key in a file of its own, write it on one line to a file only that account can read and replace the agentKey= line with agentKeyFile=<path>.
4. Check it. Run the check command the page shows (check-config, run with java -jar on the core jar from the lib folder). It reports what is wrong with the settings without starting anything.
5. Switch it on.
   • Tomcat: add the agent’s valve to the application’s context file (the exact line is on the Integration tab).
   • Spring Boot: set ssogen.agent.config-file in application.properties to the settings file.
6. Restart the application.

Open the application in a private browser window. You should be sent to SSOGEN to sign in and then returned to the page you asked for.

Servers seen

Each application server reports to SSOGEN about once a minute under its host name. The Servers seen list at the top of the Java Agent section shows each server with the time of its last report, until 30 days after the last one. Until a server reports, the list says “No server has reported yet. A server appears here about a minute after it starts with the agent key.” Use it to confirm that every server of the application has the key. You can give a server another name with the instanceLabel setting.

Rotate the agent key

Select Regenerate agent key on the Integration tab, choose how long the old key keeps working (so you can update servers one by one), paste the new agentKey= line into the settings file on each server, and restart the application. If the key may have leaked, choose Regenerate and revoke the old key now: the old key stops working at once.

Signing out

By default /ssogen/logout ends only this application’s session (logoutScope is local). On shared computers, add logoutScope=sso to the settings file so that signing out also ends the person’s SSOGEN session. Otherwise the next person at that browser who opens this application, or another SSOGEN application, is signed in as the first person. For Spring Boot use the matching ssogen.agent setting.

If it does not work

Symptom	What to do
The application will not start and the log says the settings file or the key is readable by others	Set the file to mode 0600, owned by the Tomcat account.
Sign-in fails with a 401 or 403 and the log mentions the agent’s credential	The key is missing, was regenerated, or belongs to another application. Paste the current key from the Integration tab.
A redirect loop	The servers use different session secret files. Copy the same file to every server.
The server does not appear under Servers seen	Wait a minute; check the agent version is 4.1.1 or later and that the server can reach SSOGEN over HTTPS.

Related guides

• Protect an on-premise app with the Web Agent
• Choose how to connect an application