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 Users

To start login with Single Sign-On (SSO), your app must redirect users to the Scalekit Authorization URL with appropriate enterprise identity 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
}

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

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)

# Recommended: Handle idp initiated login

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
}

// Recommended: Handle idp initiated login

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

if err != nil {
  // Handle errors
}

// result.User has the authenticated user's details
userEmail: = result.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;
}

// Recommended: Handle idp initiated login

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

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

The result object

Result Object

Loading...

tip

The idToken is a JWT containing user profile information, while the accessToken is used for API calls.