SAML Single Sign-On with Okta

Who this guide is for: The IT administrator who manages your organization’s Okta tenant. You will need Okta Super Administrator access. See also: SAML SSO Admin Guide for the embaylms side.

Overview

This guide walks through configuring Okta as the SAML 2.0 Identity Provider (IdP) for embaylms. Once complete, your users can click Sign in with SSO on the embaylms login page and authenticate with their Okta credentials.

Protocol: SAML 2.0, SP-initiated, HTTP-POST binding

Prerequisites

Okta Super Administrator access
embaylms admin access — needed to retrieve SP values and enter IdP values
embaylms tenant slug (e.g., acme for acme.embaylms.com)

Step 1 — Get SP values from embaylms

In embaylms: Admin Panel → Settings → Single Sign-On → View SP Metadata.

Note these values:

embaylms Value	You’ll paste this into Okta
SP Entity ID	Single sign-on URL / Audience URI
ACS URL	Single sign-on URL
SP Metadata URL	Optional: import metadata by URL

The values follow this pattern:

SP Entity ID:  https://{slug}.embaylms.com/api/auth/saml/{slug}/metadata
ACS URL:       https://{slug}.embaylms.com/api/auth/saml/{slug}/acs
Metadata URL:  https://{slug}.embaylms.com/api/auth/saml/{slug}/metadata

Step 2 — Create an Okta application

In the Okta Admin Console, go to Applications → Applications.
Click Create App Integration.
Select SAML 2.0 and click Next.
Set the App name (e.g., EmbayLMS) and optionally upload your logo.
Click Next.

Step 3 — Configure SAML settings

On the Configure SAML tab:

General

Okta Field	Value (replace `{slug}` with your tenant slug)
Single sign-on URL	`https://{slug}.embaylms.com/api/auth/saml/{slug}/acs`
Use this for Recipient URL and Destination URL	✓ Checked
Audience URI (SP Entity ID)	`https://{slug}.embaylms.com/api/auth/saml/{slug}/metadata`
Name ID format	`EmailAddress`
Application username	`Email`
Update application username on	`Create and update`

Attribute statements (required)

Add the following attribute mappings so embaylms receives the user’s name:

Name	Name format	Value
`email`	Unspecified	`user.email`
`firstName`	Unspecified	`user.firstName`
`lastName`	Unspecified	`user.lastName`

Note: The email attribute is required. firstName and lastName are used when JIT-provisioning a new account; they fall back gracefully if missing.

Group attribute statements (optional)

If you want embaylms to receive Okta group memberships (for future role mapping):

Name	Name format	Filter	Value
`groups`	Unspecified	Matches regex	`embaylms.*`

Click Next, then Finish.

Step 4 — Get IdP values from Okta

After creating the application, go to the Sign On tab.

Click View SAML setup instructions or scroll to the SAML Signing Certificates section.

Collect:

Value	Where to find it in Okta
Identity Provider Issuer (Entity ID)	Shown under “View SAML setup instructions”
Identity Provider Single Sign-On URL	Shown under “View SAML setup instructions”
X.509 Certificate	Download from the SAML Signing Certificates section (Active)

Step 5 — Enter IdP values in embaylms

In embaylms: Admin Panel → Settings → Single Sign-On → Add Identity Provider.
Select SAML 2.0.
Enter the values from Step 4:

embaylms Field	Value from Okta
Entity ID (Issuer)	Identity Provider Issuer from Step 4
SSO URL	Identity Provider Single Sign-On URL from Step 4
Certificate	Paste the full PEM certificate (including `-----BEGIN CERTIFICATE-----`)

Under JIT Provisioning, confirm the settings:
- Enabled (recommended): Users are created on first login with the default role.
- Default role: Set to learner for most organizations.
Click Save and toggle Enabled to ON.

Step 6 — Assign users in Okta

In Okta, go to the embaylms application → Assignments tab.
Click Assign and add the users or groups who should have access to embaylms.
Click Done.

Only assigned users will be able to sign in via SSO.

Step 7 — Test

Open a private / incognito browser window.
Navigate to https://{slug}.embaylms.com/login.
Click Sign in with SSO.
You should be redirected to your Okta login page.
Sign in with a test user who is assigned to the embaylms app.
You should be redirected back to the embaylms dashboard.

Troubleshooting

Redirect to Okta fails (ERR_CONNECTION_REFUSED or similar) The SSO URL entered in embaylms may be incorrect. Verify it matches the “Identity Provider Single Sign-On URL” shown in Okta’s SAML setup instructions.

“The SSO response from your identity provider was invalid” The certificate in embaylms doesn’t match Okta’s signing certificate. In Okta, go to Applications → embaylms → Sign On → SAML Signing Certificates, download the Active certificate, and update it in embaylms.

“Application username” error in Okta Ensure the Application username is set to Email in the SAML settings (Step 3). Okta must send the user’s email as the NameID.

User gets “You do not have access to this application” in Okta The user is not assigned to the embaylms Okta application. Go to Applications → embaylms → Assignments and add the user.

User gets “Your account was not found” in embaylms JIT provisioning is off. Either enable it (Admin Panel → Settings → User Management → SSO → Edit) or manually create the user in embaylms before their first SSO login.

Overview SAML — Microsoft Entra ID