Skip to content
Scalekit Docs

Getting started with SSO

Integrate Single Sign-On (SSO) with Scalekit to enhance your B2B SaaS application’s security. Scalekit provides seamless user experiences by abstracting the complexities of SAML and OIDC protocols. Using Scalekit’s authentication platform, you can implement enterprise-grade SSO with minimal code. We offer pre-built integrations with major identity providers including Okta, Microsoft Entra ID, JumpCloud, and OneLogin.

This quickstart guide walks you through the SSO implementation process. You will learn how to deliver enterprise authentication features without managing complex protocol details.

The following diagram illustrates the flow in a nutshell:

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

  1. Environment Setup

    Section titled “Environment Setup”

    Before implementing SSO with Scalekit, prepare your development environment with the necessary credentials and SDK. Sign up and get API credentials from the Scalekit dashboard.

    npm install @scalekit-sdk/node

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

  2. Authorize users

    Section titled “Authorize users”

    To initiate Single Sign-On (SSO) authentication, redirect users to the Scalekit Authorization URL with the appropriate enterprise identity provider parameters.

    Construct your authorization URL with these essential parameters:

    ParameterDescription
    redirect_uri
    		Your application endpoint that will receive the authorization code after successful authentication. Example: https://your-app.com/auth/callback
    client_id
    		Your unique Scalekit application identifier that specifies both your app and environment (staging, production).
    SSO Connection identifierChoose the appropriate identifier based on your implementation (use one).

    SSO connection identifiers

    When initiating SSO authentication, you must specify which connection to use through one of these identifiers, listed in order of precedence:

    • connection_id (e.g., conn_124234234): Specifies a particular SSO connection with highest precedence. If valid, this connection will be used regardless of other parameters.
    • organization_id (e.g., org_124234234): Directs users to a specific organization’s SSO. Used when no valid connection_id is provided. If an organization has multiple SSO connections, the system selects the first active one.
    • domain (e.g., acmecorp.com): Uses the SSO connection configured for the specified domain. Applied when neither connection_id nor organization_id are provided.
    • login_hint (e.g., john@acmecorp.com): Lowest precedence. The system extracts the domain portion of the email address and uses the corresponding SSO connection.

    After selecting the appropriate parameters for your implementation needs, construct your complete authorization URL and implement a redirect to this URL when users initiate the login process.

    import { ScalekitClient } from '@scalekit-sdk/node';
    // Initialize the SDK client
    const scalekit = new ScalekitClient(
      '<SCALEKIT_ENVIRONMENT_URL>',
      '<SCALEKIT_CLIENT_ID>',
      '<SCALEKIT_CLIENT_SECRET>',
    );
    

    const options = {};
    

    // Option 1: Authorization URL with the organization ID
    options['organizationId'] = 'org_15421144869927830';
    

    // Option 2: Authorization URL with login hint
    options['connectionId'] = 'conn_15696105471768821';
    

    // Option 3: Authorization URL with login hint
    options['loginHint'] = 'user@example.com';
    

    const authorizationURL = scalekit.getAuthorizationUrl(redirectUrl, options);

    This redirect will send users to the Scalekit authentication flow, where they’ll authenticate with their organization’s identity provider before being returned to your application.

    Example Authorization URL
    https://auth.scalekit.com/authorize?
      client_id=skc_122056050118122349527&
      redirect_uri=https://yourapp.com/auth/callback&
      organization_id=org_12434341

    After redirecting users to the Scalekit authorization endpoint, handle the callback at your redirect_uri to retrieve the user profile and complete the authentication process.

  3. Fetch user details

    Section titled “Fetch user details”

    After successful SSO authentication, Scalekit redirects users to your specified redirect_uri with a temporary authorization code parameter. This code must be exchanged for the user’s profile information through a secure server-side request.

    The authorization code exchange process should always be performed server-side to maintain security. This server-side request will:

    1. Validate the authorization code
    2. Return the authenticated user’s profile details
    3. Establish the user’s session in your application

    The following section demonstrates how to implement this exchange process to retrieve comprehensive user information and complete the authentication flow.

    Fetch user profile
    // Handle oauth redirect_url, fetch code and error_description from request params
    const { code, error, error_description, idp_initiated_login, connection_id, relay_state } =
      req.query;
    

    if (error) {
      // Handle errors
    }
    

    // Recommended: Handle idp initiated login
    

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

    // Next step: create a session for this user and allow access

    The result object

    Result object
    {
      user: {
        email: "john.doe@example.com",
        familyName: "Doe",
        givenName: "John",
        username: "john.doe@example.com",
        id: "conn_326735950921X7829;cc4aaef2-b395-4b40-81ae-b8183c1006e1"
      },
      idToken: "<USER_PROFILE_JWT>", // JWT containing user profile information
      accessToken: "<API_CALL_JWT>", // Token for API calls
      expiresIn: 899
    }