Testing and Troubleshooting Single Sign-On
Most single sign-on problems come down to one of three things: the identity provider isn't releasing the attribute Aeon expects, the asserted identity isn't connected to a staff account, or something failed at the protocol level. This page is about telling those apart quickly, and about the guards that make a broken identity provider an inconvenience rather than a lockout.
Test sign-in​
Test sign-in in the page header opens a new tab and runs the complete, real round trip — request out, assertion validated, identity extracted, staff account matched — then stops without creating a session. Because nothing is created, you can run it as many times as you like while your identity-provider team adjusts attribute release. It uses the saved configuration and whichever protocol is saved, so save before testing.
The result page always confirms "The identity provider round trip completed and the assertion validated. No session was created — this tab can be closed." and then one of three outcomes:
| Result | What it means | What to do |
|---|---|---|
| Test sign-in succeeded, with the identity attribute used, the asserted identity, and the matched staff account | Everything works. | Nothing. |
| Did not match — the attribute is missing. "The assertion did not carry the identity attribute the configuration expects. Check the attribute name on the Single Sign-On page, or ask the IdP administrator to release it." | The assertion validated but didn't carry the expected attribute. | The page shows which attribute Aeon looked for. Either the name in Aeon is wrong or the provider isn't releasing it. |
| Did not match — no account. "The asserted identity didn't resolve to a sign-in-able staff account. Set the account's SSO identifier (or send it an invitation) in the staff editor, and confirm it isn't locked and has a site assignment." | The identity came through but no account can sign in with it. | Copy the asserted identity shown, exactly, into the account's SSO identifier, or send an invitation. |
The asserted identity and matched username travel in the URL fragment, which browsers never send to a server, and Aeon strips it on read, so they don't reach an access log or linger in history.
The test creates neither a session nor the ticket the linking page needs, so an identity no account claims reports as not matched even with Allow staff to link their own accounts on. Check linking with a real sign-in through the SSO button on the login page.
What staff-reported errors mean​
Staff see deliberately non-specific messages; the detail lives in the logs.
| What they see | What it means | Where to look |
|---|---|---|
| "Your institutional account isn't authorized for Aeon. Contact your administrator." | The assertion validated, but the identity didn't resolve to an account that can sign in: not connected yet, the attribute wasn't released, or the account is locked, inactive, or has no site assignment. | Test sign-in reports the asserted identity and why it didn't match, on screen. The same facts are recorded in the auth audit log. |
| "Single sign-on didn't complete. Try again, or sign in with a password." | A protocol-level failure: a bad signature, an expired assertion, clock skew, a replay. | The server log. |
| "The sign-in code is invalid or has expired. Start the sign-in again." | The final completion step failed, usually a stale tab or a back-button retry. If every user sees it, the staff web client isn't being served over HTTPS; the completion step needs a browser feature that exists only in a secure context. | The staff web client's address. |
Locked, inactive, and no-site-assignment messages behave exactly as for password sign-in; SSO bypasses none of them. One case looks like nothing happening: a staff member who is already signed in and follows a stale sign-in link stays in their own session, because Aeon discards the code rather than switch accounts.
Where the evidence lives​
| Question | Where to look |
|---|---|
| Why was this person denied? | Test sign-in, on screen. The auth audit log also records every denied SSO sign-in with the asserted identity and match outcome. |
| What changed, and who changed it? | The auth audit log: configuration saves, credential changes, invitations sent, revoked, and completed, identifier and authentication-method changes, emergency-access confirmations, and API restart requests. |
| Did someone use the emergency password path? | The auth audit log records a password sign-in while SSO is enabled specifically. |
| Was a self-service link attempted? | The auth audit log distinguishes a successful link from a denied attempt. |
| A protocol failure — signature, clock, replay? | The server log. |
| Why did an anonymous endpoint fail? | System → Logs, the Stream view rather than Support. The handshake endpoints (metadata, ACS, logout) are anonymous, so their failures are filed as "Background activity." Search for the endpoint and expand +exception on the error. |
| Is Aeon describing itself correctly to the identity provider? | Fetch the SP metadata endpoint from outside the server. localhost anywhere in it means the public base URLs need attention. |
| What state are the certificates in? | The Service provider tab, and the sign-in notices described in Managing Service Provider Certificates. |
The staff web auth audit log is the StaffWebAuthAuditLog table in your Aeon database, not a page you can open; nothing in the app reads it. The System → Logs viewer is a separate store that shows an action happened, by whom, and its result, but not the audit detail. Reading the records takes database access: your own database administrator on an on-premises install, a support request to Atlas on a hosted site.
Six columns: Id, EventDate (UTC), EventType, Username (the account the event is about), Detail, and PerformedBy (who did it), indexed on EventDate. A denied sign-in is EventType = SsoLoginDenied with the asserted identity in Detail; a configuration change is SsoConfigurationChanged.
If your identity provider sends a logout request whose NameID can't be read, Aeon revokes nothing and logs a warning, so with transient NameIDs a campus-wide sign-out may not reach Aeon's sessions.
The guards that prevent a lockout​
You must prove emergency access before enabling. Turning single sign-on on, or switching an enabled configuration to Single sign-on only, requires a Local administrator's username, password, and authenticator code, after which Aeon issues a short-lived, single-use token that completes the save. It proves the emergency way in works before a broken identity provider makes you need it. The check is rate-limited, so don't test it by guessing.
The last Local administrator can't be removed. Converting, locking, deactivating, or deleting the last unlocked Local administrator is refused: "At least one unlocked Local administrator must remain for emergency access. Convert or unlock another administrator first." Aeon also warns whenever fewer than two remain. Keep two or more, permanently: with authenticator codes mandatory, a single emergency administrator means one lost phone is a lockout.
Some accounts don't lock after failed password attempts. Failed attempts normally lock an account. Aeon exempts the accounts that could rescue you, because otherwise anyone who knew the username could disable your way back in by submitting wrong passwords during the very outage the account exists for. There is no "emergency administrator" designation to maintain; the exemption is worked out at each attempt and applies to any account that is unlocked, in Local mode, in a role holding Roles & Permissions, and has an authenticator enrolled. It covers however many people match, which is worth bearing in mind when deciding who gets that capability. An administrator with no authenticator enrolled is not exempt and locks like anyone else, since for that account a guessed password would let an attacker enroll their own authenticator. Failed attempts against exempt accounts are still counted and recorded.
"Single sign-on only" never turns off passwords. The password form moves behind an Admin sign-in link that is always on the login page, and the password endpoint keeps working. Each such sign-in while SSO is enabled is recorded.
Some configurations are refused outright. SAML can't be enabled without a signing certificate, or with Require signed assertion and Expect encrypted assertions both off. Metadata fetches are HTTPS-only and guarded against server-side request forgery, and OIDC authorities must be HTTPS. Two administrators saving at once get a clean conflict error rather than one silently overwriting the other.