Web Agent troubleshooting: SSO, Apache and the error log
The SSOGEN Web Agent (the Apache module mod_ssogen) says what is wrong in the web server’s error log. This page lists the messages an operator meets, by the moment they appear: at start, at sign-in, at sign-out. Find the message in your log, then read its row.
The first line gives the module’s version and build and the libraries it runs with. Then comes one line for each virtual host the agent serves: its mode, the SSOGEN or identity provider it signs in with, the session limits, the sign-out scope and, in the standalone modes, the license (license valid until YYYY-MM-DD (N days)).
What the summary shows
Meaning
No line for your site
The agent is not in use on that virtual host. Check that the directives are inside the right <VirtualHost>.
mod_ssogen: loaded; no virtual host is configured for it
The module is loaded and no site uses it.
-- no SSOGEN directives of its own: it uses the main server's settings
A virtual host without SSOGEN directives shares the main server’s settings, as the same application.
-- has SSOGEN directives of its own, so the main server's SSOGEN settings do not apply to it
The virtual host takes nothing from the main server except a license key. Write every directive it needs inside it.
Always run apachectl configtest after a change and before a restart. A start-time refusal stops the whole Apache, every virtual host. A graceful restart that meets one keeps the running server on its previous configuration.
Message
Cause
Fix
cannot start: SSOGENClientId is not set for <host>:<port>
The site names SSOGEN and has no client ID.
Add SSOGENClientId with the client ID from the application’s Integration page.
cannot start: no signing keys from <url> (discovery and JWKS): it cannot be reached from this server (name not resolved, connection refused or timed out); and ...; start Apache once while SSOGEN is reachable from this server, so the agent saves its keys in <dir>, or set the advanced directive SSOGENPublicKey
A full start could not reach SSOGEN and found no usable saved keys. The part after and says why the saved keys were not used: none saved, older than 7 days, saved under another SSOGENSessionSecret or SSOGENServerURL, damaged, or wrong file permissions.
Make SSOGEN reachable from the web server: DNS, firewall, outbound proxy (SSOGENHttpProxyURL). On a server with SELinux, Apache must be allowed to make network connections (the boolean httpd_can_network_connect). Then start Apache.
cannot start: no signing keys from <url> (discovery and JWKS): this server does not trust its TLS certificate (unknown certificate authority, or a name that does not match it); set SSOGENCACertificateFile to the PEM certificate of the authority that issued it
SSOGEN’s certificate comes from an authority the web server does not trust, or the name in SSOGENServerURL is not on the certificate.
Set SSOGENCACertificateFile to the PEM certificate of the authority that issued SSOGEN’s certificate. If the message says the file does not hold the authority that issued it, put the right authority’s certificate in that file.
cannot start: no signing keys from <url> (discovery and JWKS): the TLS handshake failed or no usable answer
Something answers at that address, but not SSOGEN over HTTPS.
Check SSOGENServerURL (scheme, host, port) and what stands between the web server and SSOGEN.
cannot start: no configuration bundle from <url>; the agent needs its Platform reachable at startup
The site sets SSOGENAgentGroupId, and a full start could not reach SSOGEN.
Make SSOGEN reachable and start again. A site with SSOGENAgentGroupId cannot do a full start during an SSOGEN outage.
still holds the placeholder: paste the agent key shown on the application's integration page in the SSOGEN console (Generate agent key)
The configuration still contains <agent-key>.
Select Generate agent key on the Integration page and paste the key in its place.
configtest refuses SSOGENAgentKey or SSOGENAgentKeyFile
The value does not have the shape of an agent key (ssogen_ak_ and 43 characters), the key file can be read by other users, or there are two key directives.
Paste the key exactly as shown; chmod 0600 the key file; keep one of the two directives.
SSOGENSessionSecret is too short: it must be at least 32 bytes
The session secret is too short.
Create one with openssl rand -base64 32.
SSOGENSessionSecret is too easy to guess: it must have at least 8 different characters and not repeat a shorter part
The session secret is too simple.
Create one with openssl rand -base64 32.
EXPLICIT_SSOGEN_MODE_REQUIRED — SSOGENMode must be set when SAML/OIDC standalone directives are present
The virtual host has SSOGENSaml… or SSOGENOidc… directives and no SSOGENMode.
Add SSOGENMode saml or SSOGENMode oidc.
SSO-WAG-LIC-001 SSOGENLicenseKey is required for SSOGENMode <mode>
A standalone mode without a license key.
Add SSOGENLicenseKey.
SSO-WAG-LIC-001 SSOGENLicenseKey is not valid for SSOGENMode <mode> (invalid or expired)
The license key is mistyped or has expired.
Paste the key again, or renew it.
SSOGENAttributeMap mode must be First or Join
The third word of an SSOGENAttributeMap line is wrong.
Write First or Join, or leave it out.
SSOGENAttributeMap rejected (invalid names, reserved/fixed target, or duplicate)
The target name is not allowed, or is used twice.
Choose another target name.
configtest fails on a file directive
The file is missing, empty or larger than 64 KiB.
Correct the path; a relative path is relative to ServerRoot.
configtest reports a different proxy or CA file in two virtual hosts
SSOGENHttpProxyURL, SSOGENHttpProxyCredentialsFile, SSOGENHttpNoProxy and SSOGENCACertificateFile apply to the whole Apache.
Set them once at server level, or identically everywhere.
configtest reports an invalid command after you put an older module back
An older module does not know a directive that a newer one added.
Use the module that matches the configuration, or remove the directive.
no agent key on <host>:<port>: paste the SSOGENAgentKey line from the application's integration page in the SSOGEN console into this configuration; until then SSOGEN refuses this site's sign-ins (invalid_workload_proof)
The site has no agent key. Apache runs, and every sign-in on that site fails.
Paste the SSOGENAgentKey line, or set SSOGENAgentKeyFile.
could not reach <url>; starting with the signing keys saved in <file> at <date> (a saved copy is accepted at a start for 7 days after it was saved); new sign-ins need SSOGEN, and the keys are refreshed at the first start or graceful restart that reaches it
A full start during an SSOGEN outage. People who are signed in continue; new sign-ins wait for SSOGEN.
Restore the connection. Restart gracefully afterwards so the keys are refreshed.
could not refresh signing keys from <url>; keeping the keys already held
A graceful restart could not reach SSOGEN.
Nothing at once. Restart gracefully when SSOGEN is reachable.
no signing keys from <url> ...; starting with the configured keys only until a graceful restart reaches it
SSOGEN is unreachable, no saved keys could be used, and the site has an SSOGENPublicKey.
Restore the connection, then restart gracefully.
could not save the signing keys to <dir>/<file>: <reason>; a full start while SSOGEN is unreachable will not start this server: set SSOGENStateDir to a directory only the user Apache starts as can write
The agent could not write its saved keys. Sign-ins work now, but a later full start during an outage will fail.
Point SSOGENStateDir (server level) at a directory whose parent exists and that only the user Apache starts as can write.
keeping configuration bundle revision <n> already held
A graceful restart on a site with SSOGENAgentGroupId could not reach SSOGEN.
Nothing at once.
SSOGENAttributeMap is ignored in ssogen mode; configure Claims-Headers on the application in the Platform console
SSOGENAttributeMap works in the standalone modes only.
Remove the line. Choose what the application receives in the Admin Console, under Identity sent to app.
SSOGENTxnDir or SSOGENConfigStoreDir accepted with a warning
Both directives are no longer used.
Remove them when convenient.
A license line with fewer than 30 days left
The standalone license expires soon. A running server is not affected until its next restart.
No refusal line; the site answers 503 at the first sign-in
A required value is missing or wrong. Most addresses are checked at the first sign-in, not by configtest.
Compare SSOGENServerURL, SSOGENClientURL and SSOGENClientId with the Integration page. In a standalone mode, check that every required directive of the mode is present.
No refusal line; a SAML site set up by an SSOGEN integration package answers 503
The identity-provider metadata lines in the generated configuration are still commented out (#SSOGENSamlIdpMetadataFile, #SSOGENSamlIdpMetadataURL).
Save the provider’s metadata file where the comment says, or take the provider’s metadata address, and remove the # from that one line. Restart gracefully.
<mode> sign-in refused: <n> sign-ins completed in the last minutes fill the table that stops replays; refusing rather than forgetting one
More sign-ins completed on this server in a short time than the agent records.
Spread the load over more web servers.
could not fetch OIDC provider metadata from <url>; OIDC sign-ins wait for it
sign-in ended by the Platform: error=access_denied: the Platform refused the sign-in: the person is not assigned to this application, or a sign-in policy denied it (the Platform's audit names the reason) (HTTP 400)
SSOGEN decided against this person.
In the Admin Console, check the person’s assignment to the application and the sign-in policy. The audit shows the reason.
sign-in ended by the Platform: error=temporarily_unavailable: the application is not available at the Platform: check that it is active
The application is not active in SSOGEN.
Activate the application.
sign-in ended by the Platform: error=invalid_request or error=unauthorized_client, with the Platform refused the sign-in request: check SSOGENClientId and the application's redirect address
The client ID or the redirect address does not match what SSOGEN holds.
Compare SSOGENClientId and SSOGENClientURL + /ssogen/callback (or SSOGENRedirectURI) with the application in SSOGEN.
sign-in ended by the Platform: error=server_error: the Platform could not complete the sign-in
A fault on SSOGEN’s side.
Read SSOGEN’s log for that moment.
sign-in ended by the Platform: error=<code> followed by (not a known code)
SSOGEN returned a code this agent version does not know.
Send the line to support.
sign-in callback with no matching sign-in in this browser: the sign-in cookie was missing, expired or already used (check that the site is reached over HTTPS and that every node has the same SSOGENSessionSecret)
The browser came back from SSOGEN without the cookie the sign-in started with: the person waited too long (a sign-in must complete within 5 minutes), used the Back button, the site was opened over http://, or another web server of the site answered.
Open the application again. If it happens for everybody, serve the site over HTTPS only and give every web server the same SSOGENSessionSecret.
sign-in callback without a code or state: not a return from the Platform (HTTP 400)
Somebody opened /ssogen/callback by hand, or from a bookmark.
Open the application’s own address.
request refused (400): a "." or ".." path segment with a ';' parameter, a backslash or an encoded separator, which the application server may resolve to another path
The request path is one that Apache and the application server could read differently. Browsers do not send such paths. Logged at info.
Correct the link or the program that built the address.
code redeem refused by the Platform: HTTP 401, invalid_workload_proof: SSOGEN refused this agent's credential; paste the current SSOGENAgentKey from the application's integration page in the SSOGEN console
SSOGEN does not accept the agent key: there is none, it was regenerated and the old key has stopped, or it belongs to another application.
Paste the current SSOGENAgentKey line and restart gracefully. Section 5 shows how to see SSOGEN’s exact reason.
code redeem refused by the Platform: HTTP 400, invalid_grant
The sign-in code was used twice or has expired, or the registered redirect address does not equal SSOGENClientURL + /ssogen/callback.
Sign in again. If it repeats, compare the addresses.
code redeem refused by the Platform: HTTP 500
A fault on SSOGEN’s side.
Read SSOGEN’s log for that moment.
code redeem failed: could not reach <url>
The web server cannot call SSOGEN: the name does not resolve, a firewall or proxy blocks the call, or the certificate is not trusted.
Check DNS, the firewall, SSOGENHttpProxyURL and SSOGENCACertificateFile from that web server.
grant refused: key id "<id>" is neither configured (SSOGENPublicKey) nor in the Platform's discovered key set
SSOGEN changed its signing keys since this Apache last started.
Restart gracefully.
grant carries no usable username; refusing
The attribute chosen under Identify the person by has no value for this person.
Give the person a value for that attribute, or choose another attribute on the application.
redeemed grant refused: <reason>
The sign-in result failed a check: issuer, audience or time.
Check that SSOGENServerURL is exactly SSOGEN’s own address, that SSOGENClientId is right, and that the web server’s clock is correct (the agent allows 120 seconds).
sign-in refused: the grant's sub or username is too long for the session
The person’s user name is longer than the agent can keep.
Choose a shorter attribute under Identify the person by.
<mode> sign-in refused: this sign-in was already completed (a replayed response)
The same response arrived twice. A double-click on a slow page shows this too; the first one signed in.
The browser is redirected several times, then shows “This server could not read your session. If there is more than one web server behind a load balancer, session stickiness may not be enabled.” The log says <n> sign-in redirects in <n>s for a session this server cannot read; if several servers share this site, session stickiness may not be enabled (or they need the same SSOGENSessionSecret)
Several web servers serve the site and each signs sessions with its own key. After three redirects within a minute the agent stops and answers 500.
Give every web server the same SSOGENSessionSecret, or enable session stickiness on the load balancer.
Everybody has to sign in again after an Apache restart
A full restart without SSOGENSessionSecret creates a new session key. A graceful restart does not.
When SSOGEN refuses an agent’s call, it records the reason. In the Admin Console open Audit and search for the event type agent.credential_refused; add the application to see its last refusal.
Reason
Meaning
Fix
no_credential
The agent sent no agent key.
Paste the SSOGENAgentKey line from the application’s Integration page.
development_proof_not_accepted
The agent sent no agent key.
Paste the SSOGENAgentKey line from the application’s Integration page.
agent_key_not_recognised
The key is not the application’s current key, or SSOGENClientId names no Web Agent application of this SSOGEN.
Copy the configuration again from the Integration page and paste it. If the key is lost, select Regenerate agent key.
agent_key_retired
The key was replaced with Regenerate agent key and the time the old key kept working has ended.
Paste the current SSOGENAgentKey line.
agent_key_not_issued
The application has no agent key.
Select Generate agent key on its Integration page.
agent_key_malformed
What arrived is not an agent key.
Check that nothing between the web server and SSOGEN rewrites the Authorization header.
web_agents_disabled
Web Agents are switched off for your organization (hosted service only).
Ask your SSOGEN contact.
check_unavailable
SSOGEN could not check the credential at that moment.
Check SSOGEN’s health; the agent’s next call is checked again.
SSOGEN records the same reason from the same address at most once in ten minutes, so one event can stand for many refused calls.
6. The application does not receive what it expects
SSOGENAppType Oracle passes the name in upper case; generic passes it unchanged.
Set SSOGENUserNameCase to upper, lower or none.
In a standalone mode, the user name is a long internal ID
The identity provider’s NameID or sub is an internal ID.
Set SSOGENSamlUserAttribute or SSOGENOidcUserClaim to the attribute that holds the name.
An attribute never arrives
SSOGEN or the identity provider did not send it, or the agent did not accept its name.
Raise the log level (section 1), sign in once and read the sign-in for line. A name that is missing from sent was not sent: check Identity sent to app on the application, or the provider. A name that is in sent and not delivered was refused by the agent or renamed by SSOGENAttributeMap.
A CGI program does not find an attribute under HTTP_…
Apache 2.4 does not pass a header whose name contains an underscore to CGI programs in that form.
Look for the variable under its exact name.
The application works for some people only
The application’s own user record does not match the name SSOGEN passes.
Use the application’s Test tab in the Admin Console to see what a given person delivers.
The response failed a check; the reason names it and the values in brackets show what the provider sent.
Compare issuer and audience with SSOGENSamlIdpEntityId and SSOGENSamlSpEntityId. The reason SubjectConfirmationData Recipient is not this ACS URL (SSOGENSamlAcsUrl) means the ACS address registered at the provider is not exactly this site’s.
SAML sign-in refused: neither the Response nor the Assertion is signed by a configured IdP certificate (check the IdP metadata or SSOGENSamlIdpCertFile)
The provider signs with a certificate the agent does not have.
Install the provider’s current metadata (SSOGENSamlIdpMetadataFile), use SSOGENSamlIdpMetadataURL, or replace SSOGENSamlIdpCertFile.
SAML sign-in refused: the assertion is encrypted and no SSOGENSamlSpPrivateKeyFile is configured
The provider encrypts and the site has no private key.
Set SSOGENSamlSpPrivateKeyFile, or turn encryption off at the provider.
SAML sign-in refused: the encrypted assertion cannot be decrypted with SSOGENSamlSpPrivateKeyFile
The provider encrypts to another certificate, or with a method the agent refuses.
Give the provider the certificate that belongs to this private key. With SSOGENSamlRequireGcm On the provider must use AES-GCM.
SAML sign-in refused: the assertion has no single "<name>" attribute (SSOGENSamlUserAttribute); it carries: <names>
The attribute named in SSOGENSamlUserAttribute is missing or has several values.
Choose one of the names the line lists, or release the attribute at the provider.
SAML sign-in refused: the response answers a sign-in this browser did not start or no longer holds (replayed, older than 5 minutes, or from another browser)
The person took more than 5 minutes, or the response was posted a second time.
Open the application again.
SAML sign-in refused: the POST holds no readable SAMLResponse (browser: 400)
The request to /ssogen/acs carried no usable response.
Check the ACS binding at the provider: it must be HTTP-POST.
SAML sign-in refused: the assertion stays usable for more than 24 hours (NotOnOrAfter)
The provider issues assertions with a very long lifetime.
Shorten the assertion lifetime at the provider.
SAML <message> refused: <kind> <ID> was already used (a replay)
The same assertion or response was presented again.
Open the application again.
IdP-initiated SAML response discarded; signing in afresh (SP-initiated), landing on <path>
Somebody started the application from the provider’s portal. This is normal; the agent signs in on its own.
Nothing. To land on a page other than /, set the relay state at the provider to a path on the site.
SAML sign-in refused: the IdP keeps sending unsolicited responses instead of answering this site's sign-in requests
The provider does not answer the agent’s own sign-in requests.
Check the provider’s configuration for this site.
SAML LogoutRequest refused: unsigned (the IdP must sign its single logout requests with a certificate in its metadata or SSOGENSamlIdpCertFile)
The provider sent a logout request without a signature. Nobody is signed out.
Make the provider sign its logout requests.
SAML LogoutRequest refused: its Destination <url> is not this SP's single logout URL <url>
The logout address registered at the provider is wrong.
After sign-out the person is signed straight back in
The SSOGEN or provider session is still alive: SSOGENLogoutScope is local (the default), or the link pointed to the application’s own logout page only.
Link people to /ssogen/logout and set SSOGENLogoutScope sso.
SSOGEN answers HTTP 400 at sign-out
With SSOGENLogoutScope sso, the landing address is not registered at SSOGEN.
Keep the default landing page /ssogen/loggedout, or use SSOGENLogoutScope local.
sign-out ended this application's session only: the OpenID provider publishes no end_session_endpoint (SSOGENOidcEndSessionEndpoint sets one)
The provider’s discovery document names no logout address.
Set SSOGENOidcEndSessionEndpoint, or accept that sign-out ends the application’s session only.
sign-out ended this application's session only: the IdP has no HTTP-Redirect SingleLogoutService (IdP metadata, or SSOGENSamlIdpSloUrl)
The SAML provider’s metadata has no logout address.
Set SSOGENSamlIdpSloUrl, or add single logout at the provider.
The application’s own logout button leaves the SSOGEN session open
SSOGENLogoutEndpoint clears the application’s session only, by design.
Link /ssogen/logout with SSOGENLogoutScope sso where the SSOGEN session must end too.
If a new module misbehaves, put the previous mod_ssogen.so back and restart gracefully. There is no data to migrate. Run apachectl configtest first: an older module rejects directives it does not know.