Back to Guides

SSO Integration

Configure Single Sign-On with SAML 2.0 or OIDC

Single Sign-On (SSO) lets your learners authenticate using your organization's identity provider instead of managing separate credentials. This guide walks through configuring SAML 2.0 and OpenID Connect (OIDC) with Thought Industries, including role mapping and just-in-time user provisioning.

Prerequisites

Admin access to your Thought Industries instance

An identity provider that supports SAML 2.0 or OIDC

Access to your IdP's metadata URL or configuration values

A test user account for validation

SAML Configuration

SAML 2.0 is the most common enterprise SSO protocol. You'll need your IdP's metadata XML or these four values: SSO URL, Entity ID, x509 Certificate, and Name ID Format.

Step 1 — Collect IdP Metadata

Download or copy your identity provider's metadata XML. It typically looks like this:

saml-metadata.xml

<?xml version="1.0" encoding="UTF-8"?>
<EntityDescriptor xmlns="urn:oasis:names:tc:SAML:2.0:metadata"
  entityID="https://your-idp.com/saml/metadata">
  <IDPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
    <KeyDescriptor use="signing">
      <KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
        <X509Data>
          <X509Certificate>MIIDXTCCAkWgAwIBAgIJAK...</X509Certificate>
        </X509Data>
      </KeyInfo>
    </KeyDescriptor>
    <SingleSignOnService
      Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
      Location="https://your-idp.com/saml/sso" />
    <SingleSignOnService
      Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
      Location="https://your-idp.com/saml/sso" />
  </IDPSSODescriptor>
</EntityDescriptor>

Step 2 — Configure in Thought Industries Admin

1. Navigate to Settings → Authentication → SSO
2. Select SAML 2.0 as the protocol
3. Paste your IdP metadata XML or enter values manually
4. Set the ACS URL to your Thought Industries SAML endpoint
5. Save and enable SSO

Step 3 — Test the Login Flow

The SAML initiation URL follows this pattern. Visit it in an incognito window:

https://acme.thoughtindustries.com/saml/init?returnTo=/dashboard

OIDC Configuration

OpenID Connect is simpler than SAML and works well with modern identity providers like Okta, Azure AD, and Auth0. You need a Client ID, Client Secret, and Discovery URL.

1. In your IdP, create a new OIDC application
2. Set the redirect URI to https://your-domain.thoughtindustries.com/auth/callback
3. Copy the Client ID and Client Secret
4. In Thought Industries Admin, go to Settings → Authentication → SSO → OIDC
5. Paste the Client ID, Client Secret, and Discovery URL
6. Save and test

Role Mapping

Map identity provider roles to Thought Industries roles so users receive the correct permissions automatically. Common mappings:

role-mapping.json

{
  "idp_role_admin": "admin",
  "idp_role_manager": "moderator",
  "idp_role_learner": "user"
}

Role claims are read from the roles or groups attribute in the SAML assertion or OIDC ID token. Configure the claim name in SSO settings if your IdP uses a different field.

User Provisioning

With just-in-time provisioning, users are created automatically on first SSO login. You can also pre-provision users via the REST API for more control:

POST /incoming/v2/users

{
  "email": "[email protected]",
  "firstName": "Jane",
  "lastName": "Doe",
  "externalId": "idp_user_12345",
  "roles": ["user"],
  "customFields": {
    "department": "Engineering",
    "employeeId": "E-9876"
  }
}

Testing & Troubleshooting

Test in an incognito window

Avoid cached sessions. Always test SSO in a private browser window.

Check the SAML tracer

Use your browser's network tab or a SAML tracer extension to inspect assertions.

Verify the Name ID format

Thought Industries expects email address (urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress).

Validate the clock skew

Ensure server clocks are synchronized. SAML assertions are time-bound.

If users see "Authentication failed" after SAML login, the most common causes are clock skew, mismatched Entity IDs, or an invalid x509 certificate. Check the Thought Industries admin logs for detailed error messages.