SSO OIDC Authentication Flow — v1.0.8
SSO OIDC Authentication Flow
Available since: v1.0.8
The platform supports Single Sign-On (SSO) for learners using the OpenID Connect (OIDC) protocol, powered by Auth.js v5. Instead of managing a separate username and password, learners authenticate through their organisation's existing identity provider (IdP) — such as Okta, Microsoft Entra ID, Google Workspace, or any other OIDC-compliant provider.
How It Works
- Learner visits the sign-in page for their organisation (e.g.
acme.yourplatform.comoryourplatform.com/org/acme). - Platform resolves the OIDC provider — using the subdomain or organisation slug from the request, the platform dynamically loads the correct OIDC provider configuration registered for that organisation.
- Learner is redirected to their IdP — the platform initiates the OIDC authorisation code flow and redirects the learner to their organisation's identity provider login page.
- IdP authenticates the learner — the learner signs in with their existing organisational credentials.
- IdP redirects back to the platform — the identity provider returns the learner to the platform with an authorisation code.
- Session is established — Auth.js v5 exchanges the code for tokens, verifies the identity, and maps it to the correct organisation. A verified, organisation-scoped platform session is created.
- Learner accesses their courses — the learner is landed on their organisation's course library, fully authenticated.
Key Behaviours
- Dynamic, per-organisation provider loading — OIDC provider settings (client ID, client secret, discovery URL, etc.) are resolved at request time. There is no need to hard-code or redeploy when onboarding a new organisation.
- Multi-tenant session isolation — each session is scoped to a specific organisation. A learner authenticated in one tenant cannot access another tenant's content.
- No separate credentials required — learners use their existing IdP credentials; the platform never stores or manages learner passwords.
- Standard OIDC authorisation code flow — compatible with any OIDC-compliant identity provider.
Organisation Configuration Requirements
Before learners can sign in via SSO, the organisation must have a valid OIDC provider configuration registered in the platform. This typically includes:
| Field | Description |
|---|---|
| Issuer / Discovery URL | The base URL of the IdP (e.g. https://login.microsoftonline.com/{tenant}/v2.0) |
| Client ID | The OAuth 2.0 client identifier issued by the IdP |
| Client Secret | The corresponding client secret |
| Redirect URI | Must be registered with the IdP — provided by the platform during setup |
Contact your platform administrator to register or update your organisation's OIDC configuration.
Supported Identity Providers
Any OIDC-compliant identity provider is supported, including but not limited to:
- Okta
- Microsoft Entra ID (Azure AD)
- Google Workspace
- Auth0
- Keycloak
- PingIdentity
- OneLogin
Technical Implementation
The SSO flow is built on Auth.js v5. Provider configurations are loaded dynamically per request based on the incoming subdomain or orgSlug, ensuring the correct IdP is invoked for each organisation without requiring static configuration at build time.
Session tokens returned after a successful OIDC callback are scoped to the authenticated organisation, maintaining strict isolation in the multi-tenant architecture.
Troubleshooting
| Symptom | Likely Cause | Resolution |
|---|---|---|
| Redirect loop on sign-in | OIDC configuration not found for the organisation | Verify the org slug/subdomain is correct and an OIDC config is registered |
redirect_uri_mismatch error from IdP | Redirect URI not registered with the IdP | Register the platform's callback URL with your IdP |
| Session not created after IdP callback | Token verification failure | Check that the Client ID and Secret are correct and not expired |
| Learner lands on wrong organisation | Subdomain/slug mismatch | Ensure the learner is using the correct organisation URL |