Set up a SAML Provider
Create a SAML 2.0 provider, import IdP metadata, and copy Built LMS ACS values into the IdP.
Use this guide to create the SAML connection between Built LMS and your identity provider. Examples include JumpCloud, Okta, Microsoft Entra ID, Ping, OneLogin, Auth0, or another SAML-compatible IdP.
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.
- The IdP entity ID, SSO URL, and signing certificate, or the IdP metadata XML.
- A non-SSO admin recovery path while you configure the provider.
Gather SAML values
What Built LMS needs from the IdP
Built LMS stores these values on the SAML provider:
| Built LMS field | Required | What to enter |
|---|---|---|
| Display Name | Yes | The user-facing provider name, such as JumpCloud, Okta, Entra ID, or Company SSO. |
| IdP Entity ID | Yes | The IdP issuer/entity ID for this SAML app. |
| SSO URL | Yes | The IdP single sign-on endpoint. |
| X.509 Certificate | Yes | The IdP signing certificate in PEM format. |
| Custom field mappings | No | SAML attribute names mapped to active Built LMS custom user fields. |
Saving fails if the required SAML fields are missing or the provider cannot be registered. Treat a failed save as a configuration problem, not as partial success.
What the IdP needs from Built LMS
Copy these values from the Built LMS SAML provider page after you create or open the provider:
| IdP field name may be called | Built LMS value |
|---|---|
| Audience URI, SP Entity ID, Entity ID, Identifier | SP Entity ID |
| ACS URL, Assertion Consumer Service URL, Reply URL, Recipient URL | ACS (Assertion Consumer Service) URL |
| NameID Format | urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress |
| Signature Algorithm, Digest Algorithm | RSA-SHA256 |
The current SAML ACS path shown by the admin UI uses:
/api/jackson/samlCopy the full URL from Built LMS instead of rebuilding it by hand. Built LMS uses the current portal domain, custom domain, or configured SSO domain for the value shown in the form.
Create the provider
Step 1: Open the provider form
- Open Admin Dashboard.
- Go to Settings > Identity & Access > Authentication.
- Open Auth Providers.
- Select Add Provider.
- Set Provider Type to SAML 2.0.
- Select Continue.
- On New SAML Provider, enter a Display Name.
Use a name that the learner or admin will recognize on the sign-in page. If the
IdP is JumpCloud, name it JumpCloud or Company JumpCloud, not an internal
ticket or project name.
Step 2: Configure the app in the IdP
In the IdP, create a SAML application for Built LMS.
Configure the IdP app with:
| IdP setting | Value |
|---|---|
| SSO mode | SAML 2.0 |
| Audience / SP Entity ID | Built LMS SP Entity ID |
| ACS / Reply URL | Built LMS ACS (Assertion Consumer Service) URL |
| NameID | User email address |
| NameID format | urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress |
| Signed assertions | Enabled |
| Signature algorithm | RSA-SHA256 / SHA-256 |
If the IdP asks for a default relay state or app tile target, use a relative Built LMS path such as:
/dashboardAvoid absolute external URLs. The current Built LMS SSO flow is designed around same-site destinations.
Step 3: Import IdP metadata when possible
Metadata import is the safest setup path because it reduces copy-and-paste mistakes.
In Built LMS:
- Find Import Metadata (Optional).
- Choose one option:
- Select Upload XML and upload the IdP metadata XML file.
- Paste the metadata URL and select Fetch.
- Confirm Built LMS fills in:
- IdP Entity ID
- SSO URL
- X.509 Certificate
Metadata upload accepts .xml and .txt. Built LMS parses the first
EntityDescriptor entity ID, first SingleSignOnService location, and first
X509Certificate it finds, then stores the raw metadata for future updates.
If your IdP metadata contains more than one signing certificate or more than one SSO endpoint, review the values after import. Built LMS only shows the value it parsed into the form.
Step 4: Enter IdP values manually if metadata is not available
If metadata import is not available, fill in the IdP values directly.
- Enter IdP Entity ID.
- Enter SSO URL.
- Paste the X.509 Certificate, or upload a certificate file.
The certificate must be the IdP signing certificate. If the IdP shows separate encryption and signing certificates, use the signing certificate.
Accepted upload file extensions include:
.pem.crt.cer.p7b.p7c.p12.pfx
When pasting a certificate, keep the PEM wrapper:
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----Step 5: Save the provider
Select Save Provider.
After the provider saves:
- It appears in Authentication Providers.
- It can be edited with the pencil action.
- It can be enabled or disabled from the provider list.
- Its generated copy values are available from the edit page.
If save fails, check the required fields first:
- IdP Entity ID
- SSO URL
- X.509 Certificate
Then check that the certificate is PEM formatted and belongs to the IdP app you are configuring.
Verify success
The provider setup is complete when:
- The SAML provider saves without errors.
- Built LMS shows the generated SP Entity ID and ACS URL.
- The matching IdP app contains those exact values.
- The IdP signing certificate in Built LMS matches the app you will test.
Troubleshooting
Check IdP Entity ID, SSO URL, and X.509 Certificate. The certificate must be the IdP signing certificate and should include the PEM wrapper when pasted manually.
Some metadata files include multiple certificates or endpoints. Review the parsed fields after import and replace any value that does not match the app you will assign to users.
Use the Built LMS value that matches the IdP's label. For example, ACS URL, Reply URL, and Recipient URL usually refer to the same Built LMS ACS value.