Setting Up OpenID Connect Single Sign-On

If your institution runs an OpenID Connect provider — Microsoft Entra ID, Okta, Keycloak, or similar — this is the shorter of the two setup paths. OIDC needs no service provider certificate and no metadata exchange: you register Aeon as an application at the provider, paste a few values into Aeon, and you're done.

Read Single Sign-On: Overview and Prerequisites first. The public base URLs matter here too: Aeon's redirect URI is built from the staff API's public address, and a wrong one is rejected by the provider.

Where you'll be working

Customization Manager → Integrations & Messaging → Single Sign-On, which requires the Integrations configuration capability.

Step 1 — Register Aeon at your provider

This side comes first, because you need the client ID and secret before Aeon has anything to store.

Create an application (an app registration in Entra ID; a client in Okta and Keycloak) and set its redirect URI to your staff API's public base URL followed by /api/v2/auth/oidc/callback. For an API published at https://aeon.example.edu/StaffAPI, that is https://aeon.example.edu/StaffAPI/api/v2/auth/oidc/callback. The URI has to match exactly. Read the API address off the Service provider tab first, and fix it if it shows localhost (the tab is relabelled Override public URLs while OpenID Connect is selected, so switch to SAML briefly to read the addresses).

Aeon uses the authorization-code flow with PKCE, which some providers ask you to choose or offer as a checkbox when you register. Note the client ID and the client secret; most providers show the secret only once.

Step 2 — Choose the protocol in Aeon

On the Identity Provider tab, set Protocol to OpenID Connect. Selecting it changes nothing on the server, but saving a protocol change clears the stored credential; see the settings reference before saving an established SAML configuration as OIDC.

Step 3 — Enter the provider details

Field	What to enter
Authority (issuer)	Your provider's issuer URL and nothing more — for Entra ID, of the form https://login.microsoftonline.com/{tenant}/v2.0. It must be HTTPS. Aeon discovers the authorization, token, JWKS, and end-session endpoints from it, which is why there is no endpoint list to maintain. Don't paste the discovery URL here (see below).
Discovery URL (optional)	Only when the discovery document isn't at the standard well-known path beneath the authority.
Client ID	The application ID from step 1.
Client secret	The secret from step 1. Stored encrypted and never shown again; when editing later, leave it blank to keep the current one. A public client using PKCE can leave it empty.
Scopes	Space-separated; openid profile email is the default, and openid is always requested.
Clock skew (seconds)	Leeway when validating the ID token's time window, 0–600.

The authority is the issuer, not the discovery URL

Most providers show you the discovery document's address first, ending /.well-known/openid-configuration. Aeon appends that path itself, so pasting it into Authority gives the path twice and sign-in fails. Aeon strips a trailing /.well-known/openid-configuration when you leave the field and again on save, so the mistake is caught rather than fatal, but enter the issuer alone and there is nothing to catch.

Step 4 — Review the sign-in options

The Sign-in options tab works as it does for SAML, minus the SAML-only protocol settings. Leave Login page on Password and single sign-on during rollout, and confirm Identity attribute lines up with the claim your provider issues. Every field is in Single Sign-On Settings Reference.

Step 5 — Enable, prove emergency access, and save

Switch Enable single sign-on on and click Save. Two things happen only on this save:

1. Full validation runs. Until now the page accepted incomplete drafts.
2. The Confirm emergency access dialog opens. Enter a Local administrator's username, password, and authenticator code. Aeon issues a short-lived, single-use token that completes the save, so don't leave it sitting.

The point is to prove your emergency way in works before a misconfigured provider makes you need it. Keep two or more unlocked Local administrators permanently and don't convert them; Aeon warns below two and refuses to remove the last one.

Step 6 — Run Test sign-in

Click Test sign-in in the page header. It runs the full round trip against the saved configuration — authorization, token exchange, identity extraction, staff-account matching — and reports the result without creating a session, so it is safe to repeat while you and your provider administrator sort out claims. Results are explained in Testing and Troubleshooting Single Sign-On.

Step 7 — Move staff onto single sign-on

Enabling converted nobody. See Moving Staff Accounts to Single Sign-On for the three ways to convert an account.

Before you call it done

Check	How you know
The staff web client is served over HTTPS	Sign-in completes rather than failing at the last step
The redirect URI registered at the provider matches Aeon's callback exactly	The provider doesn't reject the sign-in
Two or more unlocked Local administrators, authenticators enrolled, staying Local	No warning banner on the Single Sign-On page
SSO enabled and saved	The header badge reads Enabled
Test sign-in succeeds and matches a real staff account	"Test sign-in succeeded"
A pilot invitation sent, completed, and signed in end to end	The pilot account shows its invitation completed