Skip to main content

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.

How Scalekit
works

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
npm install @scalekit-sdk/node

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

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:

ParameterDetails
redirect_uriURI 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_idYour 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.

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

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:

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

Is this page helpful? Yes No