Getting Started with Single Sign-on

Integrate with dozens of identity providers via SAML or OIDC

Single Sign-On (SSO) enhances B2B SaaS application's security and offers a smooth user experience. Scalekit is an authentication platform that enables developers to implement enterprise features like SSO with just a few lines of code. Scalekit abstracts the complexities associated with SAML, OIDC and offers prebuilt integrations with all major identity providers like Okta, Microsoft Entra ID, Jumpcloud, Onelogin.

This quickstart guide will show you how to implement SSO using Scalekit.

Scalekit offers turnkey SSO for B2B SaaS applications

1. Environment Setup

Before diving in, make sure you have:

• Access to your Scalekit account and API credentials
• Your app's codebase for implementing and testing changes

Install the Scalekit SDK

Scalekit offers language-specific SDKs for fast SSO integration. Use the installation instructions below for your technology stack.

Setup SDK

Node.js

npm install @scalekit-sdk/node

Python

pip install scalekit-sdk-python

Go

go get -u github.com/scalekit-inc/scalekit-sdk-go

Java

/* Gradle users - add the following to your dependencies in build file */
implementation "com.scalekit:scalekit-sdk-java:1.0.2"

<!-- Maven users - add the following to your `pom.xml` -->
<dependency>
    <groupId>com.scalekit</groupId>
    <artifactId>scalekit-sdk-java</artifactId>
    <version>1.0.2</version>
</dependency>

Set up API credentials

Secure your Scalekit API communication by setting up environment variables. You'll need three key pieces of information from your Scalekit Dashboard:

1. Environment URL: The base URL for API calls. Each environment (dev, staging, prod) has a unique URL.
2. Client ID: Your app's unique identifier for Scalekit communications.
3. Client Secret: A private key to authenticate your API requests. For security purposes, this is generated only when you request using the Scalekit Dashboard.

Get Your Credentials

1. Log into your Scalekit Dashboard.
2. Select the "Development" environment.
3. Click on "API Config" to view your credentials.

Store Credentials Securely

Never hardcode secrets in your app. Use environment variables instead. Here's how to set them in a .env file:

.env

SCALEKIT_ENVIRONMENT_URL='https://b2b-app-dev.scalekit.com'
SCALEKIT_CLIENT_ID='<CLIENT_ID_FROM_SCALEKIT_DASHBOARD>'
SCALEKIT_CLIENT_SECRET='<SECRET_FROM_SCALEKIT_DASHBOARD>'

tip

• Never commit your .env file to version control.
• Rotate your secret regularly. See the best practices for managing secrets.

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 the Users

To start login with Single Sign-On (SSO), your app must redirect users to the Scalekit Authorization URL with appropriate social connection provider details.

Construct the Authorization URL using the following query parameters:

Parameter	Details
redirect_uri	URI endpoint on your server to complete user login via SSO. Example: https://your-saas-app.com/auth/callback After the user is logged into the social provider, Scalekit redirects the user to this URI with one time authorization code. In the later section, we will explain how to use this unique code to fetch user details
client_id	Your app's unique Scalekit identifier which is mandatory for all requests. This uniquely identifies both your app and the environment (staging, prod).
Any one of the SSO connection identifiers - organization_id - connection_id - login_hint - domain	organization_id: Informs Scalekit which organization's Single Sign-on to use to authenticate the user with. For e.g., org_124234234 Note: If there are multiple active SSO connections configured for an organization, we will pick the first SSO connection to authenticate the user with. connection_id: Informs Scalekit which specific Single Sign-on connection to use to authenticate the user with 's Single Sign-on to use. For e.g., conn_124234234 domain: Informs Scalekit which Single Sign-on connection to use that is configured with the domain. For e.g., acmecorp.com login_hint: Informs Scalekit which Single Sign-on connection to use that is configured for that domain portion of the email address. For e.g., john@acmecorp.com

Example Authorization URL

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

See our Authorization URL Parameters Guide for a full list of accepted parameters.

Next, construct your Authorization URL with these parameters and redirect users to this URL when they try to log in.

Construct Authorization URL

Node.js

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);

Python

from scalekit import ScalekitClient, AuthorizationUrlOptions, CodeAuthenticationOptions

# Initialize the SDK client
scalekit = ScalekitClient(
  '<SCALEKIT_ENVIRONMENT_URL>',
  '<SCALEKIT_CLIENT_ID>',
  '<SCALEKIT_CLIENT_SECRET>'
)

options = AuthorizationUrlOptions()


# Option 1: Authorization URL with the organization ID
options.organization_id = 'org_15421144869927830'

# Option 2: Authorization URL with login hint
options.login_hint = 'user@example.com'

# Option 3: Authorization URL with the connection ID
options.connection_id = 'conn_15696105471768821'

authorization_url = scalekit_client.get_authorization_url(
  redirect_uri=<redirect_uri>,
  options=options
)

# Redirect the user to this authorization URL

Go

import (
  "github.com/scalekit/scalekit-sdk-go"
)

func main() {
  // Initialize the SDK client
  scalekitClient := scalekit.NewScalekitClient(
    "<SCALEKIT_ENVIRONMENT_URL>",
    "<SCALEKIT_CLIENT_ID>",
    "<SCALEKIT_CLIENT_SECRET>"
  )

  options := scalekitClient.AuthorizationUrlOptions{}


  // Option 1: Authorization URL with the organization ID
  options.OrganizationId = "org_15421144869927830"

  // Option 2: Authorization URL with the connection ID
  options.ConnectionId = "conn_15696105471768821"

  // Option 3: Authorization URL with Login Hint
  // User's email domain detects the correct enterprise SSO connection.
  options.LoginHint = "user@example.com"

  authorizationURL := scalekitClient.GetAuthorizationUrl(
    redirectUrl,
    options,
  )
   // Next step is to redirect the user to this authorization URL
}

// Redirect the user to this authorization URL

Java

package com.scalekit;

import com.scalekit.ScalekitClient;
import com.scalekit.internal.http.AuthorizationUrlOptions;

public class Main {

  public static void main(String[] args) {
    // Initialize the SDK client
    ScalekitClient scalekitClient = new ScalekitClient(
      "<SCALEKIT_ENVIRONMENT_URL>",
      "<SCALEKIT_CLIENT_ID>",
      "<SCALEKIT_CLIENT_SECRET>"
    );
    AuthorizationUrlOptions options = new AuthorizationUrlOptions();
    // Option 1: Authorization URL with the organization ID
    options.setOrganizationId("org_13388706786312310");
    // Option 2: Authorization URL with the connection ID
    options.setConnectionId("con_13388706786312310");
    // Option 3: Authorization URL with Login Hint
    // User's email domain detects the correct enterprise SSO connection.
    options.setLoginHint("user@example.com");
    try {
      String url = scalekitClient
        .authentication()
        .getAuthorizationUrl(redirectUrl, options)
        .toString();
    } catch (Exception e) {
      System.out.println(e.getMessage());
    }
  }
}
// Redirect the user to this authorization URL

Finally, handle the callback at your redirect_uri to complete the Authentication. Understand user authorization procedure through a NextJS example for adding SSO to the Login Page

3. Fetch User Details

After a successful SSO, Scalekit redirects the user to your redirect_uri with a unique

code in the browser. Exchange the code for user profile details (on the serverside).

Here's how to turn that code into user data:

Fetch user profile

Node.js

// 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
}

// Check: if it is an idp initiated login
if (idp_initiated_login) {
  const { connection_id, organization_id, login_hint, relay_state } =
    await scalekit.getIdpInitiatedLoginClaims(idp_initiated_login);

  // Generate Authorization URL
  const authorizationURL = scalekit.getAuthorizationUrl(redirectUri, {
    connectionId: connection_id,
    ...(relay_state && {
      state: relay_state,
    }), // pass relay state
  });

  // Next:Redirect the user to this authorization URL
}

const res = await scalekit.authenticateWithCode(code, redirectUri);

// res.user has the authenticated user's details
const userEmail = res.user.email;

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

Python

# Handle oauth redirect_url, fetch code and error_description from request params
code = request.args.get('code')
error = request.args.get('error')
error_description = request.args.get('error_description')
idp_initiated_login = request.args.get('idp_initiated_login')
connection_id = request.args.get('connection_id')
relay_state = request.args.get('relay_state')

if error:
    raise Exception(error_description)

if idp_initiated_login:
    claims = await scalekit.get_idp_initiated_login_claims(idp_initiated_login)
    connection_id = claims.get('connection_id', None)
    organization_id = claims.get('organization_id', None)
    login_hint = claims.get('login_hint', None)
    relay_state = claims.get('relay_state', None)
    options.connection_id=connection_id
    options.state=relay_state

    # Generate Authorization URL
    authorization_url = scalekit.get_authorization_url(
      redirect_uri=redirect_uri,
      options=options
    )
    # Next:redirect the user to this authorizationURL

result = scalekit.authenticate_with_code(code, <redirect_uri>)

# result.user has the authenticated user's details
user_email = result.user.email

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

Go

// Handle oauth redirect_url, fetch code and error_description from request params
code: = r.URL.Query().Get("code")
error: = r.URL.Query().Get("error")
errorDescription: = r.URL.Query().Get("error_description")
idpInitiatedLogin: = r.URL.Query().Get("idp_initiated_login")
connectionID: = r.URL.Query().Get("connection_id")
relayState: = r.URL.Query().Get("relay_state")

if error != "" {
  // Handle errors
}

// Check: if it is an idp initiated login
if idpInitiatedLogin: = r.URL.Query().Get("idp_initiated_login");
idpInitiatedLogin != "" {
  claims, err: = a.scalekit.GetIdpInitiatedLoginClaims(idpInitiatedLogin)
  if err != nil {
    http.Error(w, err.Error(), http.StatusInternalServerError)
    return
  }

  // Generate Authorization URL
  options: = scalekit.AuthorizationUrlOptions {
    // Either ONE of the following properties
    ConnectionId: claims.ConnectionID,
    OrganizationId: claims.OrganizationID,
    LoginHint: claims.LoginHint,
  }
  authUrl, err: = a.scalekit.GetAuthorizationUrl(<redirectUrl>,options)

  if err != nil {
    http.Error(w, err.Error(), http.StatusInternalServerError)
    return
  }
  http.Redirect(w, r, authUrl.String(), http.StatusFound)
}



res, err: = a.scalekit.AuthenticateWithCode(code,<redirectUrl>)

if err != nil {
  // Handle errors
}

// res.User has the authenticated user's details
userEmail: = res.User.Email

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

Java

// Handle oauth redirect_url, fetch code and error_description from request params
String code = request.getParameter("code");
String error = request.getParameter("error");
String errorDescription = request.getParameter("error_description");
String idpInitiatedLogin = request.getParameter("idp_initiated_login");
String connectionID = request.getParameter("connection_id");
String relayState = request.getParameter("relay_state");

if (error != null && !error.isEmpty()) {
    // Handle errors
    return;
}

// Check: if it is an idp initiated login
  if (idpInitiatedLoginToken != null) {
    IdpInitiatedLoginClaims idpInitiatedLoginClaims =
        scalekit.authentication().getIdpInitiatedLoginClaims(idpInitiatedLoginToken);
    if (idpInitiatedLoginClaims == null) {
      response.sendError(HttpStatus.BAD_REQUEST.value(),
          "Invalid idp_initiated_login token");
      return null;
    }
    // Either ONE of ConnectionId or OrganizationId or LoginHint
    AuthorizationUrlOptions options = new AuthorizationUrlOptions();
    if (idpInitiatedLoginClaims.getConnectionID() != null) {
      options.setConnectionId(idpInitiatedLoginClaims.getConnectionID());
    }

    // Generate Authorization URL
    String url = scalekit.authentication()
                     .getAuthorizationUrl(redirectUrl, options)
                     .toString();
    response.sendRedirect(url);

try {
    AuthenticationResponse res = scalekit.authentication().authenticateWithCode(code, redirectUrl);
    String userEmail = res.getIdTokenClaims().getEmail();

    // Next step: create a session for this user and allow access
} catch (Exception e) {
    // Handle errors
}