Java SSO agent configuration reference

The SSOGEN Java agent protects a Java web application from inside the application server: as a Tomcat valve, as a servlet filter, or as a Spring Boot starter. All three forms share one set of settings, which this page lists. For the installation steps, the jar files and the first sign-in see Protect a Java application.

The examples use the fictional company Acme Corp, with SSOGEN at https://sso.acme.example and an application at https://app.acme.example.

Start from the generated settings file

The Admin Console writes agent.properties for each application on its Integration page: serverUrl, clientUrl, clientId, agentKey, sessionSecretFile, protect and, for an application that is not an Oracle product, appType. Paste that file first and add a setting from this page only when you need the behavior it describes.

1. Where settings come from

Form	Where you write the settings
Tomcat valve (com.ssogen.agent.tomcat.SsogenAuthenticator)	The file named by the valve’s configFile attribute, and/or attributes of the valve with the same names as the settings. An attribute overrides the file.
Servlet filter (com.ssogen.agent.servlet.SsogenFilter)	init-params with the same names as the settings, and/or the file named by the configFile init-param or by the system property ssogen.agent.configFile.
Spring Boot starter	Application properties ssogen.agent.<setting>, in relaxed form (ssogen.agent.server-url, environment variable SSOGEN_AGENT_SERVERURL), and/or the file named by ssogen.agent.config-file. The file is read first; an application property overrides it.

The settings file is a Java properties file in UTF-8, one name=value per line. The names are case-sensitive, written exactly as below. A name the agent does not know is refused (unknown setting <name>), in the file and in the application’s own properties alike.

A settings file that holds agentKey must be readable by the account the application server runs as and by nobody else (mode 0600 or 0400); otherwise the agent refuses to start.

What happens when a setting is wrong:

Form	Effect
Tomcat valve	The web application’s context does not start. Tomcat’s log shows SSOGEN agent did not start: followed by the reason, or SSOGEN agent: configFile unreadable.
Servlet filter	The filter’s init fails. If the container keeps the application running anyway, the filter answers every request 503 until it holds a working agent.
Spring Boot starter	The application does not start. SSOGEN agent: ssogen.agent.config-file is unreadable or SSOGEN agent: setting <name> is given twice under different spellings name the usual causes. An environment variable SSOGEN_AGENT_<NAME> that is not a setting is ignored with a warning that suggests the setting you may have meant.

In Spring Boot, ssogen.agent.enabled=false is the only way to run the application without the agent. The agent’s filter runs before Spring Security’s chain, on every path.

2. Check the settings

Run the check from the account the application server uses, with the jar of the java-agent folder:

java -jar "$CATALINA_BASE"/lib/ssogen-web-agent-java-core-*.jar check-config /etc/ssogen/agent/agent.properties

Output	Meaning
valid: serverUrl=..., clientUrl=..., clientId=..., sessionSecretFile=set, ..., agentKey=set, protect=1 rule(s), identityHeaders=on, logoutScope=local, sessionMax=43200s, sessionIdle=1800s	Every setting is accepted. The line is the same summary the agent logs at start. No secret value is printed.
invalid: <problem>, one line per problem	A setting is missing or wrong. The problems are the messages in the tables below.

The command also checks the file permissions of sessionSecretFile, agentKeyFile and the settings file itself, so run it as the account the application server runs as.

3. Connect the application to SSOGEN

Setting	Values	Default	What it does
serverUrl	an HTTPS origin, no path	required	The address of SSOGEN, as on the Integration page. Example: https://sso.acme.example.
clientUrl	an HTTPS origin, no path	required	The address of the application as the browser sees it. The agent’s return address is this value plus the application’s context path plus /ssogen/callback; it must equal what SSOGEN holds for the application. Example: https://app.acme.example.
clientId	the client ID from the Integration page, at most 2048 printable characters	required	Identifies the application to SSOGEN.
agentKey	the agent key from the Integration page: ssogen_ak_ followed by 43 letters, digits, - or _	one of agentKey or agentKeyFile is required	The credential SSOGEN checks on every call of this agent. Shown once in the Admin Console when you select Generate agent key.
agentKeyFile	a file that holds the agent key alone		The same key, kept in its own file instead of the settings file. The file follows the rules of sessionSecretFile. Give agentKey or agentKeyFile, not both.
sessionSecretFile	a file of at least 32 bytes	required	The key that signs the agent’s session cookie. Every server that serves the same application must hold the same file.
instanceLabel	1 to 128 of A-Z a-z 0-9 . _ -	the host name	The name under which this server appears under Servers seen on the application. The agent reports every 60 seconds; a server stays listed until 30 days after its last report, at most 256 per application.
expectedAgentId	at most 128 printable characters	not set	Pins the agent identity SSOGEN must name in what it sends. Leave it unset unless an SSOGEN guide tells you otherwise.

Messages of this group:

Message	Cause
<name> is required	serverUrl, clientUrl, clientId or sessionSecretFile is missing.
<name>: an https origin with no path, such as https://sso.example.com	The value has a path, a query, or is not https://.
<name>: not a URL	The value cannot be read as an address.
agentKeyFile is required: the application's agent key from the console	Neither agentKey nor agentKeyFile is set.
agentKey and agentKeyFile: give one	Both are set.
<name>: not an agent key (ssogen_ak_ and 43 letters, digits, - or _, as the console shows it)	The key was not pasted whole.
clientId: no colon with an agent key	The client ID contains a colon. Use the client ID the Integration page shows.
instanceLabel: 1-128 of A-Z a-z 0-9 . _ -	The label has another character or is too long.

Rules for the secret files

sessionSecretFile and agentKeyFile must each be:

• a readable file, owned by the account the application server runs as (<name>: not a readable file, <name>: owned by another account than the one the agent runs as);
• mode 0600 or 0400 (<name>: readable or writable by group or others; use mode 0600 or 0400);
• in a directory that group and others cannot write (<name>: its directory is writable by group or others).

The session secret must hold at least 32 bytes and no NUL byte (sessionSecretFile: at least 32 bytes of secret, sessionSecretFile: contains a NUL byte). A line ending at the end of the file is ignored. The commands the Integration page gives create a correct file:

install -d -m 0750 /etc/ssogen/agent
umask 077
openssl rand -base64 32 > /etc/ssogen/agent/session.secret

4. Choose what is protected

Setting	Values	Default	What it does
protect	entries path=on, path=optional or path=off, separated by commas or white space	/*=on	Which paths need a signed-in person. A path is /exact, /prefix/* or /*, relative to the application’s context. The first entry that matches wins; a path that matches no entry is protected. optional passes the request with the person’s identity when there is a session, and without it when there is none or when SSOGEN cannot be reached; off passes every request untouched.

protect=/health=off, /public/*=off, /*=on

Messages: protect: path=on|optional|off entries (an entry has no =), protect: a pattern is /exact, /prefix/* or /* (the path has another form), protect: on, optional or off (the value after = is something else).

The servlet filter cannot serve a declarative <auth-constraint> in web.xml; use the Tomcat valve for an application that relies on container-managed security.

5. Sessions

Setting	Values	Default	What it does
sessionMaxDuration	a duration: 45s, 30m, 12h, 1d, or plain seconds; more than 0 and at most 30 days	43200 (12 hours)	How long a session lasts from sign-in, whatever the activity.
sessionIdleTimeout	a duration as above, or off or 0 for none	1800 (30 minutes)	How long a session survives without a request.
cookieName	1 to 64 of A-Z a-z 0-9 _ -	__Host-SSOGEN-APP for an application at the root context; __Secure-SSOGEN-APP, limited to the context path, for any other	The name of the agent’s session cookie. Change it only when two applications on the same host name and context path would otherwise share a name.

The limits SSOGEN sends for the application can shorten these values; they never lengthen them. Messages: <name>: a duration such as 30m, 12h or 1d, <name>: more than 0 and at most 30 days, cookieName: 1-64 of A-Z a-z 0-9 _ -.

6. Sign-out

Setting	Values	Default	What it does
logoutEndpoints	exact paths starting with /, separated by commas or white space	none	The application’s own logout addresses. A request to one of them ends the agent’s session before it reaches the application.
logoutScope	sso or local	local	What the agent’s own sign-out address (/ssogen/logout under the context) ends. local: this application’s session only; the person’s SSOGEN session stays and the next visit signs in without a prompt. sso: the SSOGEN session too, so every application is signed out.
logoutRedirectUrl	a path on the client URL, starting with / (not //, no backslash)	<context>/ssogen/loggedout	Where the browser lands after sign-out.

Messages: logoutEndpoints: exact paths starting with /, logoutScope: sso or local, logoutRedirectUrl: a path on the client URL starting with /.

7. The user name and attributes

Setting	Values	Default	What it does
appType	generic or oracle	the application’s setting in SSOGEN, else oracle	The kind of application. The Admin Console writes appType=generic for an application that is not an Oracle product.
identityHeaders	on or off (true and false are accepted)	on	on: the person’s user name and attributes reach the application as request headers and through the servlet API. off: through the servlet API only (the request’s principal and request attributes), for an application that reads them in code.
attributeJoinDelimiter	1 to 8 printable characters	;	The separator between the values of an attribute that has several.

Messages: appType: generic or oracle, identityHeaders: on or off, attributeJoinDelimiter: 1-8 printable characters.

Which attributes the application receives is chosen in the Admin Console, under Identity sent to app on the application. The agent’s log line event=outputs_dropped reason=attribute_outputs_too_large (or cookie_outputs_too_large) says that what SSOGEN sent for a person was larger than the agent passes on; reduce the attributes sent.

8. Outbound calls and certificate trust

The agent calls SSOGEN from the application server: at start, at each sign-in and every 60 seconds afterwards. It ignores the JVM’s proxy system properties and uses these settings only:

Setting	Values	Default	What it does
httpProxyUrl	http://host:port	none	The forward proxy for the agent’s calls to SSOGEN. Only an http:// proxy address with a port is accepted (httpProxyUrl: http://host:port).
httpNoProxy	host names, separated by commas or white space	none	Hosts the agent reaches without the proxy.
caCertificateFile	a readable PEM file	the JVM’s trust store	The certificate of the authority that issued SSOGEN’s certificate, when the JVM does not trust it.

9. Start while SSOGEN is unreachable

Setting	Values	Default	What it does
revocationStateFile	a file path the agent can write	not set	The agent keeps the last complete sign-out list it fetched from SSOGEN in this file, readable by its own account only, and uses it at a start while SSOGEN cannot be reached. Without the setting, an application server started during an outage answers 503 until SSOGEN answers.

The warnings event=persisted_feed_unusable and event=persist_feed_failed reason=io say that the file could not be read or written; check the path and the directory’s permissions.

10. The paths the agent serves

Under the application’s context path, the agent answers these addresses itself. Do not map application resources there.

Path	Purpose
/ssogen/callback	The return from SSOGEN after sign-in. Register clientUrl + context path + this path at SSOGEN.
/ssogen/login	Starts a sign-in and returns to the page asked for.
/ssogen/logout	Ends the session (see logoutScope).
/ssogen/loggedout	The page shown after sign-out, unless logoutRedirectUrl is set.

Any other address under /ssogen/ answers 404.

11. Responses the agent gives

Status	When
401	A protected path was asked for without a session with a method other than GET or HEAD (sign_in_required): a sign-in cannot start from a POST. A GET is sent to SSOGEN to sign in instead.
403	SSOGEN refused the sign-in (provider_error), the person has no user name the application can take (identity_inexpressible), the sign-in cookie or the result of the sign-in failed a check, or the same result was presented twice.
500	More than three sign-in redirects in 60 seconds for one browser (session_loop): the session cookie is not coming back. Check that the site is served over HTTPS and that every server holds the same sessionSecretFile.
503	The agent holds no usable keys or configuration from SSOGEN yet, the sign-out list it needs is stale, or the agent itself failed. The response carries Retry-After: 30.
400	/ssogen/callback was opened without the values SSOGEN sends.

12. What the agent logs

The agent logs through java.util.logging under the logger name com.ssogen.agent, so it follows the application server’s logging configuration. Every line is event=<name> followed by key=value pairs; a value is a reason code, a status or a client ID, never a secret, a token or a person’s attribute.

Line	Meaning
event=agent_start version=<v> java=<v> settings: <summary>	The agent started with the settings shown (same summary as check-config).
event=signed_in client_id=<id>	A sign-in completed.
event=refused reason=<code> ... client_id=<id>	A request was refused; the reason is one of the codes in section 11.
event=session_ended reason=revoked	SSOGEN ended the session (the person signed out elsewhere or the session was revoked).
event=answered status=<n> reason=<code>	The agent answered a request itself.
event=keys_unavailable reason=<code>, event=bundle_unavailable reason=<code>	The agent cannot get SSOGEN’s keys or its configuration; it answers 503 until it does.
event=jwks_refresh reason=<code>, event=refresh_fault reason=<code>	A periodic refresh failed; the agent keeps what it holds.
event=revocation_feed_failed reason=<code>	The sign-out list could not be fetched.
event=revocation_feed_incomplete reason=more_than_1000_entries	The sign-out list SSOGEN sent was cut at 1000 entries. The agent keeps the last complete list it holds.
event=refused reason=revocation_stale client_id=<id>	The sign-out list is older than the agent accepts; requests answer 503 until a fresh list arrives.
event=heartbeat_failed status=<n> or reason=io	The 60-second report to SSOGEN failed; Servers seen will show the server as not reporting.
event=agent_fault reason=<code> route=<path>	An unexpected fault; the request was answered 503. Send the line to support.
event=setting_ignored reason=cache_is_always_off	Tomcat only: the valve’s cache attribute has no effect.

13. The jar files

Jar	Form	Runs on
ssogen-web-agent-java-core-<version>.jar	Needed by every form; holds check-config	Java 8 or later
ssogen-web-agent-java-tomcat9-<version>.jar	Tomcat valve	Tomcat 9, Java 8 or later
ssogen-web-agent-java-tomcat10-<version>.jar	Tomcat valve	Tomcat 10.1 and 11, Java 11 or later
ssogen-web-agent-java-servlet-javax-<version>.jar	Servlet filter	Servlet 3.1 containers (javax.servlet), Tomcat 8.5 and 9, Java 8 or later
ssogen-web-agent-java-servlet-jakarta-<version>.jar	Servlet filter	Servlet 6.0 containers (jakarta.servlet), Tomcat 10.1 and 11, Java 11 or later
ssogen-web-agent-java-spring-boot-<version>.jar	Spring Boot starter	Spring Boot 3.5, Java 17 or later

The servlet filter jars register the filter on /* through their web-fragment.xml when the application declares nothing; declare it in web.xml yourself to control its position among other filters.

Related guides

• Protect a Java application
• Web Agent configuration reference
• Web Agent troubleshooting