Configure OIDC SSO
Choose the right OpenID Connect setup guide for provider setup, claims, testing, rollout, and maintenance.
Use OpenID Connect when your organization signs users in through an identity provider such as JumpCloud, Okta, Microsoft Entra ID, Google Workspace, Auth0, Ping, or another OIDC-compatible provider.
OIDC setup depends on exact matches between Built LMS and the IdP:
- Issuer URL.
- Client ID.
- Client secret.
- Redirect URI.
- Token endpoint authentication method.
- Scopes and claims.
Before you begin
You need:
- Built LMS admin access to Settings > Identity & Access > Authentication.
- Permission to add or edit authentication providers.
- Admin access in the identity provider.
- Permission to create an OIDC application or client.
- A pilot user assigned to the IdP app.
- A non-SSO admin recovery path while you test.
- The IdP issuer URL.
- A client ID.
- A client secret for the current Built LMS OIDC setup.
The OIDC form includes a None / PKCE only auth-method option, but the current provider registration path still expects a stored client secret. Use a confidential web application with a client secret unless Built LMS support has confirmed that your environment supports secretless OIDC clients.
Choose the right guide
| Goal | Use this guide |
|---|---|
| Create the OIDC app in the IdP, create the Built LMS provider, configure issuer/client/scopes, and copy redirect URLs. | Set Up an OIDC Provider |
| Configure email, name, and custom field claims. | Map OIDC Claims and Profile Fields |
| Test sign-in, test IdP app tiles, make OIDC default, customize the login button, rotate secrets, or troubleshoot. | Test and Roll Out OIDC SSO |
| Compare SAML and OIDC setup paths. | Authentication |
How OIDC works in Built LMS
Built LMS uses the provider ID in the callback URL. That means a new OIDC provider cannot show its final redirect URI until it has been saved once.
The visible callback pattern is:
/api/auth/sso/callback/{providerId}For a new provider, the form shows that the URL will be generated after saving. The practical setup flow is:
- Create the OIDC app in the IdP.
- Use a temporary or placeholder redirect URI if the IdP requires one before it gives you a client ID and client secret.
- Create the OIDC provider in Built LMS with issuer, client ID, and client secret.
- Save the provider.
- Reopen the provider.
- Copy the final Redirect URI from Built LMS.
- Replace the temporary redirect URI in the IdP.
- Test sign-in.
Do not test sign-in until the IdP has the final redirect URI copied from Built LMS.
Verify success
OIDC is ready for rollout when:
- The OIDC provider is saved and enabled.
- A pilot user can sign in from the Built LMS login page.
- The IdP app tile works if your organization uses app-tile launch.
- The redirect URI in the IdP exactly matches the Built LMS provider value.
- The
emailclaim is present and matches the intended Built LMS identity. - Name and mapped custom fields appear as expected.
- The user lands in the expected learner, manager, or admin portal.
- The provider button label is clear on the login page.
- A non-SSO admin recovery path still works.
Troubleshooting
Start with Set Up an OIDC Provider. Use Map OIDC Claims and Profile Fields when sign-in works but profile data is wrong. Use Test and Roll Out OIDC SSO when you are ready to pilot, default, maintain, or troubleshoot the provider.
Copy Redirect URI from the saved Built LMS provider and paste it into the IdP exactly. Do not use the placeholder text from the new-provider form.
Check whether Default Provider is enabled. Leave it off until rollout is complete.