Test, Roll Out, and Maintain SAML SSO
Pilot SAML sign-in, make the provider available to users, and keep certificates current.
Use this guide after the SAML provider is saved and the IdP app is configured. Test with a small group before making SAML the default sign-in method.
Before you begin
You need:
- A saved SAML provider in Built LMS.
- A pilot user assigned to the IdP app.
- The IdP app configured with the Built LMS SP Entity ID and ACS URL.
- The IdP sending email as NameID and as the
emailattribute. - A non-SSO admin recovery path.
Test the provider
Step 1: Enable the provider for a pilot
In Authentication Providers, turn the provider on.
Keep Set as Default Provider off for the first test. When a provider is the 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 sends
email. - The IdP app uses the Built LMS SP Entity ID and ACS URL from this environment.
- A non-SSO admin can still sign in.
Step 2: Test SP-initiated sign-in
Use a private browser window or a different browser profile.
- Open the Built LMS login page for the organization.
- Select the SAML 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 name and mapped custom fields are correct.
- Confirm the user has the expected role and access.
If the provider button does not appear, confirm the provider is enabled and that login customization has not hidden or reordered the provider in a confusing way.
Step 3: Test IdP-initiated sign-in if you use app tiles
If users start from an IdP app tile, test that path after SP-initiated sign-in works.
- Open the IdP portal as the pilot user.
- Select the Built LMS app tile.
- Confirm the user lands in Built LMS.
- Confirm the landing page is acceptable.
New SAML providers are created with IdP-initiated SSO enabled and a default
relay state of /dashboard. If your IdP sends RelayState, keep it to a relative
Built LMS path such as:
/dashboard
/courses
/learning-pathsDo not use:
https://external.example.com
//external.example.com
/../admin-dashboardRoll out SAML
Step 4: Make SAML the default provider
Only make SAML the default provider after pilot testing.
Before enabling Set as Default Provider, confirm:
- A pilot user can sign in from the Built LMS login page.
- A pilot user can sign in from the IdP tile if that path is used.
- The
emailattribute matches the expected Built LMS identity. - Name and custom field mappings are correct.
- The provider button label is clear.
- A non-SSO admin recovery path still works.
- Support or admins know what to do if the IdP has an outage.
Step 5: 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
Sign in with JumpCloud. - Provider logo.
- Provider display order.
- Login page title, subtitle, and footer text.
Do this after a successful pilot sign-in test so copy and branding changes do not hide a broken provider setup.
Maintain SAML
Step 6: Rotate the SAML certificate
SAML certificates expire or rotate. Track the IdP certificate expiration date outside Built LMS.
To rotate a certificate:
- Add or rotate the signing certificate in the IdP.
- Open the SAML provider in Built LMS.
- Replace X.509 Certificate.
- Select Save Provider.
- Test with a pilot user.
If the IdP supports overlapping old and new certificates, coordinate the cutover with your identity team. Built LMS stores the certificate shown in the provider form.
Verify success
SAML is ready for rollout when:
- The SAML provider is saved and enabled.
- A pilot user can sign in from the Built LMS login page.
- A pilot user can sign in from the IdP app tile, if your organization uses IdP-initiated sign-in.
- The user lands in the expected learner, manager, or admin portal.
- The
emailvalue from the IdP matches the intended Built LMS user identity. - First name, last name, and mapped custom fields appear as expected.
- The provider button label is clear on the login page.
- A non-SSO admin recovery path still works.
Troubleshooting
Check that the provider is enabled, the user is on the correct organization domain, and login customization has not hidden or renamed the provider unexpectedly.
Check the IdP app assignment and the app values copied from Built LMS. Saving proves Built LMS accepted the provider configuration; it does not prove the IdP app assignment, audience, attributes, or certificate are correct for a real user.
Check the RelayState or app tile destination in the IdP. Prefer a relative Built
LMS path such as /dashboard.
Check for an expired or rotated IdP certificate, changed IdP entity ID, changed SSO URL, removed app assignment, changed assertion signing settings, or changed user email format.