Prevent passwords in logs: operator security notes

SSOGEN keeps passwords, codes and tokens out of its logs and fails closed: it refuses to start rather than run unprotected. This page is for the person who installs and runs SSOGEN on a server; it explains why SSOGEN may refuse to start, what to change, and which few server settings can weaken these safeguards.

None of this is configured in the Admin Console. These are server settings, set when SSOGEN is installed.

1. Logs never carry secrets, and SSOGEN fails closed

When people troubleshoot, they often turn logging up to its most detailed level. In many web applications that writes everything into the log file: the passwords people type, the codes in sign-in links, session cookies, and the contents of emails. SSOGEN is built so that raising the log level cannot do that.

SSOGEN keeps the parts of the system that handle web requests, mail and database values at the INFO level and above, whatever you set. If you set the main log level to the most detailed setting to investigate a sign-in problem, those parts still do not print request contents. You do not need to do anything for this to work.

When SSOGEN refuses to start

SSOGEN checks at start (and again once it is ready) that this protection is in place, and stops with an error rather than run unprotected. You will see a message beginning ssogen: refusing to start:. There are five causes.

You will see	What it means	What to do
`ssogen: refusing to start: logging below INFO is enabled for <name> and could write passwords, tokens or codes to the log`	Detailed logging is switched on for part of the system that handles secrets, through a route SSOGEN’s own protection does not reach. The usual cause is a logging set-up outside the application, such as a Java logging configuration file given to the Java process.	Remove or correct that logging configuration, then start again.
`ssogen: refusing to start: spring.mvc.log-request-details must be false; it logs request data such as passwords, client secrets and codes`	A setting that prints the contents of web requests has been turned on.	Set it back to `false` or remove it.
`ssogen: refusing to start: spring.mvc.log-resolved-exception must be false; it logs request data such as passwords, client secrets and codes`	A setting that prints the details of rejected requests has been turned on; the message says it logs request data such as passwords, client secrets and codes.	Set it back to `false` or remove it.
`ssogen: refusing to start: server.tomcat.accesslog.enabled is true and server.tomcat.accesslog.pattern records the query string or other request data (sign-in codes, reset links, session ids); ...`	The web server’s access log is on, and its format would record the full address (including one-time codes in the address) or other request data.	Use a safe pattern (below) or turn the access log off.
`ssogen: refusing to start: the logging backend is not logback (...), so HTTP body logging cannot be guarded`	The logging library SSOGEN ships has been replaced by another.	Remove the replacement; use the logging SSOGEN ships.

A setting whose value cannot be read as true or false is treated as true, so a typo also stops the start. Fix the spelling.

The access log

You can keep an access log. SSOGEN only insists that its pattern does not record anything secret. The pattern a standard installation uses records the client address as SSOGEN found it (behind a load balancer, the person’s address), the path but not the query string:

%{ssogen.client.ip}r %l %u %t "%m %U %H" %s %b %D

A simpler safe pattern is:

%h %l %u %t "%m %U %H" %s %b

That records the client address, the time, the method, the path, the protocol, the status code and the size.

The following are refused, because they carry secrets:

the shorthand patterns common and combined (and so the default, which is common);
%r (the whole request line) and %q (the query string);
%S (the session id);
request and response headers, cookies, and request or session attributes written as %{...}i, %{...}o, %{...}c, %{...}r or %{...}s, with two exceptions: %{User-Agent}i and the client address %{ssogen.client.ip}r are allowed.

Any pattern code SSOGEN has not reviewed is also refused until it is.

Keep these off

The safeguards above cover SSOGEN’s own logging settings. Do not turn on any of the following on a production server, because they write outside those settings:

a Java logging handler that is configured outside the application (for example a java.util.logging.config.file option on the Java command line);
output turned on by Java or library debug switches rather than by log level, such as mail.debug, javax.net.debug or jdk.httpclient.HttpClient.log;
any extra access log added outside the settings above.

2. Server settings that decide what SSOGEN trusts

These can only be set on the server, never from the Admin Console, on purpose: an administrator who could change them from a screen could turn the console against your own network.

Setting (environment variable)	Default	What to know
`SSOGEN_TRUSTED_PROXY_CIDRS`	empty	The network addresses of your load balancer. SSOGEN believes a client address passed on by a forwarding header only from these networks. Empty means forwarded addresses are ignored, so every request appears to come from the load balancer. Set it, or addresses in the audit log, network zones and sign-in limits will be wrong. The install guide’s section on a proxy or load balancer says how many forwarding hops to count and which header to read; System health shows what SSOGEN is doing with them under Client address.
`SSOGEN_CANONICAL_ORIGIN`	(a placeholder)	The one public address of this SSOGEN installation, for example `https://sso.acme.example`. SSOGEN builds all its addresses from it and never from the address a request claims.
`SSOGEN_SECRETS_ENV_ALLOWED`	empty	Which environment variables a `secret://env/NAME` reference may read. Empty allows none. SSOGEN’s own variables (database, keys, enrollment tokens) can never be read this way, whatever you list. See Secrets.
`SSOGEN_AUDIT_DIGEST_KEY`	empty	The key (at least 32 characters) that signs the daily audit checkpoints. Without it the checkpoints cannot be sealed or verified. See The audit log.
`SSOGEN_SECRETS_MASTER_KEY`	empty	The key that encrypts every stored secret. Keep it apart from your database backups. See Backups and upgrades.

The full list of what to back up and where each setting lives is in Backups and upgrades. The System health page shows which of these are set, without their values; see System health.