Test and Roll Out OIDC SSO
Pilot OIDC sign-in, test app-tile launch, make OIDC the default provider, customize login, and rotate secrets.
Use this guide after the OIDC provider has been saved, callback URLs are copied to the IdP, and required claims are configured.
Before you begin
You need:
- A saved OIDC provider.
- The final Built LMS Redirect URI copied into the IdP app.
- A pilot user assigned to the IdP app.
- The
emailclaim available for the pilot user. - A non-SSO admin recovery path while you test.
Keep Default Provider off until pilot testing passes.
Test OIDC sign-in
Enable the provider for a pilot
In Authentication Providers, turn the provider on.
Keep Default Provider off for the first test. When a provider is default, users may be sent to that provider before they can choose another method.
Before pilot testing, confirm:
- The pilot user is assigned to the IdP app.
- The IdP app contains the final Built LMS redirect URI.
- The IdP sends the
emailclaim. - A non-SSO admin can still sign in.
Test sign-in
Use a private browser window or a different browser profile.
- Open the Built LMS login page for the organization.
- Select the OIDC provider button.
- Complete sign-in at the IdP.
- Confirm the user returns to Built LMS.
- Confirm the user lands in the expected portal.
- Confirm the user's email, name, and mapped custom fields are correct.
- Confirm the user has the expected role and access.
If the IdP returns an error, Built LMS redirects to the auth error page with the provider error when available. Start by checking the redirect URI, client secret, token endpoint auth method, and requested scopes.
Test IdP app-tile launch
If users start from an IdP portal tile, test that path after the Built LMS login button works.
- Open the IdP portal as the pilot user.
- Select the Built LMS app tile.
- Confirm the user lands in Built LMS.
New OIDC providers are created with IdP-initiated SSO enabled and a default
relay state of /dashboard. Use the Login URL copied from Built LMS for
IdP app tile settings when the IdP asks for a sign-on or home URL.
Roll out OIDC
Make OIDC the default provider
Only enable Default Provider after pilot testing.
Before making OIDC default, confirm:
- A pilot user can sign in from the Built LMS login page.
- The IdP app tile works if your organization uses it.
- The redirect URI in the IdP exactly matches Built LMS.
- The
emailclaim is present. - Name and custom field mappings are correct.
- A non-SSO admin recovery path still works.
- Support or admins know what to do if the IdP has an outage.
Customize the login button
After the provider works, use Login Customization on the Authentication page to adjust the sign-in experience.
Common updates:
- Button text, such as
Continue with JumpCloud. - Provider logo.
- Provider display order.
- Login page title, subtitle, and footer text.
Do this after a successful pilot sign-in test so branding changes do not hide a broken provider setup.
Maintain OIDC
Rotate the client secret
To rotate an OIDC client secret:
- Create a new client secret in the IdP.
- Open the OIDC provider in Built LMS.
- Replace Client Secret with the new secret.
- Select Save Provider.
- Test sign-in with a pilot user.
- Retire the old secret in the IdP after the new one works.
If the IdP supports secret expiration dates, track the expiration date outside 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
Enable the provider in Authentication Providers and test again.
Check that the failing user is assigned to the IdP app, allowed to receive the requested scopes, has an email claim, and is not blocked by conditional access or MFA policy.
Check whether Default Provider is enabled. Leave it off until rollout is complete.
Check for an expired client secret, changed issuer, changed redirect URI, changed token endpoint auth method, removed app assignment, or conditional access or security policy changes in the IdP.