Skip to content
Scalekit Docs
Talk to an Engineer Dashboard
Build this faster with AI coding agents. Build with AI →

Add Modular SSO

Enable enterprise SSO for any customer in minutes with built-in SAML and OIDC integrations

Enterprise customers often require Single Sign-On (SSO) support for their applications. Rather than building custom integrations for every identity provider—such as Okta, Entra ID, or JumpCloud—and managing the detailed configuration of OIDC and SAML protocols, there are more scalable approaches available.

See a walkthrough of the integration Play
Review the authentication sequence

After your customer’s identity provider verifies the user, Scalekit forwards the authentication response directly to your application. You receive the verified identity claims and handle all subsequent user management—creating accounts, managing sessions, and controlling access—using your own systems.

Diagram showing the SSO authentication flow: User initiates login → Scalekit handles protocol translation → Identity Provider authenticates → User gains access to your application

This approach gives you maximum flexibility to integrate SSO into existing authentication architectures while offloading the complexity of SAML and OIDC protocol handling to Scalekit.

Modular SSO is designed for applications that maintain their own user database and session management. This lightweight integration focuses solely on identity verification, giving you complete control over user data and authentication flows.

Choose Modular SSO when you:

  • Want to manage user records in your own database
  • Prefer to implement custom session management logic
  • Need to integrate SSO without changing your existing authentication architecture
  • Already have existing user management infrastructure

Build with a coding agent

/plugin marketplace add scalekit-inc/claude-code-authstack
/plugin install modular-sso@scalekit-auth-stack

Continue building with AI →

  1. Configure “Modular Auth” mode

    Section titled “Configure “Modular Auth” mode”

    Ensure your environment is configured in Modular Auth mode.

    1. Go to Dashboard > Settings > Authentication Mode
    2. Select “Modular Auth” and save

    Now you’re ready to start integrating SSO into your app! Next, we’ll cover how to use the SDK to authenticate users.

  2. Set up Scalekit

    Section titled “Set up Scalekit”

    Use the following instructions to install the SDK for your technology stack.

    npm install @scalekit-sdk/node

    Configure your environment with API credentials. Navigate to Dashboard > Developers > Settings > API credentials and copy these values to your .env file:

    .env
    SCALEKIT_ENVIRONMENT_URL=<your-environment-url> # Example: https://acme.scalekit.dev or https://auth.acme.com (if custom domain is set)
    SCALEKIT_CLIENT_ID=<app-client-id> # Example: skc_1234567890abcdef
    SCALEKIT_CLIENT_SECRET=<app-client-secret> # Example: test_abcdef1234567890

    Register redirect URL for your app

    Section titled “Register redirect URL for your app”

    You need to register redirect URL for your application. Go to Scalekit dashboard → Authentication → Redirect URLs and configure:

    • Allowed callback URLs: The endpoint where users are sent after successful authentication to exchange authorization codes and retrieve profile information. Learn more
    • Initiate login URL: The endpoint in your app that redirects users to Scalekit’s /authorize endpoint. Required when user starts sign-in directly from their identity provider (IdP-initiated SSO). Learn more

  3. Redirect the users to their enterprise identity provider login page

    Section titled “Redirect the users to their enterprise identity provider login page”

    Create an authorization URL to redirect users to Scalekit’s sign-in page. Use the Scalekit SDK to construct this URL with your redirect URI and required scopes.

    authorization-url.js
    8 collapsed lines
    import { Scalekit } from '@scalekit-sdk/node';
    

    const scalekit = new ScalekitClient(
      '<SCALEKIT_ENVIRONMENT_URL>',    // Your Scalekit environment URL
      '<SCALEKIT_CLIENT_ID>',          // Unique identifier for your app
      '<SCALEKIT_CLIENT_SECRET>',
    );
    

    const options = {};
    

    // Specify which SSO connection to use (choose one based on your use case)
    // These identifiers are evaluated in order of precedence:
    

    // 1. connectionId (highest precedence) - Use when you know the exact SSO connection
    options['connectionId'] = 'conn_15696105471768821';
    

    // 2. organizationId - Routes to organization's SSO (useful for multi-tenant apps)
    //    If org has multiple connections, the first active one is selected
    options['organizationId'] = 'org_15421144869927830';
    

    // 3. loginHint (lowest precedence) - Extracts domain from email to find connection
    //    Domain must be registered to the organization (manually via Dashboard or through admin portal during enterprise onboarding)
    options['loginHint'] = 'user@example.com';
    

    // redirect_uri: Your callback endpoint that receives the authorization code
    // Must match the URL registered in your Scalekit dashboard
    const redirectUrl = 'https://your-app.com/auth/callback';
    

    const authorizationURL = scalekit.getAuthorizationUrl(redirectUrl, options);
    // Redirect user to this URL to begin SSO authentication

    Enterprise users see their identity provider’s login page. Users verify their identity through the authentication policies set by their organization’s administrator. Post successful verification, the user profile is normalized and sent to your app.

    For details on how Scalekit determines which SSO connection to use, refer to the SSO identifier precedence rules.

  4. Handle IdP-initiated SSO Recommended

    Section titled “Handle IdP-initiated SSO ”

    When users start the login process from their identity provider’s portal (rather than your application), this is called IdP-initiated SSO. Scalekit converts these requests to secure SP-initiated flows automatically.

    Your initiate login endpoint receives an idp_initiated_login JWT parameter containing the user’s organization and connection details. Decode this token and generate a new authorization URL to complete the authentication flow securely.

    Terminal window
    https://yourapp.com/login?idp_initiated_login=<encoded_jwt_token>

    Configure your initiate login endpoint in Dashboard > Authentication > Redirects

    handle-idp-initiated.js
    // Your initiate login endpoint receives the IdP-initiated login token
    const { idp_initiated_login, error, error_description } = req.query;
    5 collapsed lines
    

    if (error) {
      return res.status(400).json({ message: error_description });
    }
    

    // When users start login from their IdP portal, convert to SP-initiated flow
    if (idp_initiated_login) {
      // Decode the JWT to extract organization and connection information
      const claims = await scalekit.getIdpInitiatedLoginClaims(idp_initiated_login);
    

      const options = {
        connectionId: claims.connection_id,      // Specific SSO connection
        organizationId: claims.organization_id,  // User's organization
        loginHint: claims.login_hint,            // User's email for context
        state: claims.relay_state                // Preserve state from IdP
      };
    

      // Generate authorization URL and redirect to complete authentication
      const authorizationURL = scalekit.getAuthorizationUrl(
        'https://your-app.com/auth/callback',
        options
      );
    

      return res.redirect(authorizationURL);
    }

    This approach provides enhanced security by converting IdP-initiated requests to standard SP-initiated flows, protecting against SAML assertion theft and replay attacks.

    Learn more: IdP-initiated SSO implementation guide

  5. Get user details from the callback

    Section titled “Get user details from the callback”

    After successful authentication, Scalekit redirects to your callback URL with an authorization code. Your application exchanges this code for the user’s profile information and session tokens.

    1. Add a callback endpoint in your application (typically https://your-app.com/auth/callback)
    2. Register it in your Scalekit dashboard > Authentication > Redirect URLS > Allowed Callback URLs

    In authentication flow, Scalekit redirects to your callback URL with an authorization code. Your application exchanges this code for the user’s profile information.

    Fetch user profile
    // Extract authentication parameters from the callback request
    const {
      code,
      error,
      error_description,
      idp_initiated_login,
      connection_id,
      relay_state
    } = req.query;
    

    if (error) {
      // Handle authentication errors returned from the identity provider
    }
    

    // Recommended: Process IdP-initiated login flows (when users start from their SSO portal)
    

    const result = await scalekit.authenticateWithCode(code, redirectUri);
    const userEmail = result.user.email;
    

    // Create a session for the authenticated user and grant appropriate access permissions

    The result object

    Validate tokens
    // Validate and decode the ID token from the authentication result
    const idTokenClaims = await scalekit.validateToken(result.idToken);
    

    // Validate and decode the access token
    const accessTokenClaims = await scalekit.validateToken(result.accessToken);
     
    {
      user: {
        email: 'john@example.com',
        familyName: 'Doe',
        givenName: 'John',
        username: 'john@example.com',
        id: 'conn_70087756662964366;dcc62570-6a5a-4819-b11b-d33d110c7716'
      },
      idToken: 'eyJhbGciOiJSU..bcLQ',
      accessToken: 'eyJhbGciO..',
      expiresIn: 899
    }

  6. Test your SSO integration

    Section titled “Test your SSO integration”

    Validate your implementation using the IdP Simulator and Test Organization included in your development environment. Test all three scenarios before deploying to production.

    Your environment includes a pre-configured test organization (found in Dashboard > Organizations) with domains like @example.com and @example.org for testing.

    Pass one of the following connection selectors in your authorization URL:

    • Email address with @example.com or @example.org domain
    • Test organization’s connection ID
    • Organization ID

    This opens the SSO login page (IdP Simulator) that simulates your customer’s identity provider login experience.

    IdP Simulator

    For detailed testing instructions and scenarios, see our Complete SSO testing guide

  7. Set up SSO with your existing authentication system

    Section titled “Set up SSO with your existing authentication system”

    Many applications already use an authentication provider such as Auth0, Firebase, or AWS Cognito. To enable single sign-on (SSO) using Scalekit, configure Scalekit to work with your current authentication provider.

    Firebase Auth

    Add enterprise authentication to Firebase projects

    Know more →

  8. Onboard enterprise customers

    Section titled “Onboard enterprise customers”

    Enable SSO for your enterprise customers by creating an organization in Scalekit and providing them access to the Admin Portal. Your customers configure their identity provider settings themselves through a self-service portal.

    Create an organization for your customer in Dashboard > Organizations, then provide Admin Portal access using one of these methods:

    Generate a secure link your customer can use to access the Admin Portal:

    generate-portal-link.js
    // Generate a one-time Admin Portal link for your customer
    const portalLink = await scalekit.organization.generatePortalLink(
      'org_32656XXXXXX0438'  // Your customer's organization ID
    );
    

    // Share this link with your customer's IT admin via email or messaging
    // Example: '<SCALEKIT_ENVIRONMENT_URL>/magicLink/8930509d-68cf-4e2c-8c6d-94d2b5e2db43
    console.log('Admin Portal URL:', portalLink.location);

    Send this link to your customer’s IT administrator through email, Slack, or your preferred communication channel. They can configure their SSO connection without any developer involvement.

    Enable domain verification for seamless user experience. Once your customer verifies their domain (e.g., @megacorp.org), users can sign in without selecting their organization. Scalekit automatically routes them to the correct identity provider based on their email domain.

    Pre-check SSO availability before redirecting users. This prevents failed redirects when a user’s domain doesn’t have SSO configured:

    check-sso-availability.js
    // Extract domain from user's email address
    const domain = email.split('@')[1].toLowerCase();  // e.g., "megacorp.org"
    

    // Check if domain has an active SSO connection
    const connections = await scalekit.connections.listConnectionsByDomain({
       domain
     });
    

    if (connections.length > 0) {
      // Domain has SSO configured - redirect to identity provider
      const authUrl = scalekit.getAuthorizationUrl(redirectUri, {
        domainHint: domain  // Automatically routes to correct IdP
      });
      return res.redirect(authUrl);
    } else {
      // No SSO for this domain - show alternative login methods
      return showPasswordlessLogin();
    }

    This check ensures users only see SSO options when available, improving the login experience and reducing confusion.