Add Modular SSO

This quickstart adds enterprise single sign-on (SSO) to an app that keeps its own users and sessions. By the end, a test user signs in through the SSO simulator and your app reads their profile at its callback URL. New to Modular SSO? Start with What is Modular SSO.

Your app signs users in with Auth0, Amazon Cognito, Firebase or Supabase? Follow that system’s guide instead; see Choose how to integrate. Want Scalekit to run the whole login? Use the Full Stack Auth quickstart.

See a walkthrough of the integration

Play

Using a coding agent?Copy SSO prompt

• A Scalekit account. Use your development environment: it comes with a test organization and the SSO simulator.
• A web app whose backend can run the Node.js, Python, Go or Java SDK.

1. Switch the environment to Modular Auth mode

   Section titled “Switch the environment to Modular Auth mode”

   In the Scalekit dashboard, go to Settings > Authentication Mode, select Modular Auth and select Save. In this mode your app keeps its users and sessions, and Scalekit returns the verified user to your app.

2. Set up Scalekit

   Section titled “Set up Scalekit”

   Install the SDK for your stack.

   • Node.js
   • Python
   • Go
   • Java

   npm install @scalekit-sdk/node

   Copy your API credentials from Developers > Settings > API Credentials into your .env file:

   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

3. Register your callback URL

   Section titled “Register your callback URL”

   Scalekit sends users back to your app only at URLs you register. Go to Authentication > Redirect URLs and add http://localhost:3000/auth/callback under Allowed callback URLs. In production, add your app’s own callback URL. See Register redirect URLs.

4. Send the user to their identity provider

   Section titled “Send the user to their identity provider”

   Build an authorization URL with the SDK and redirect the user to it. The URL names your callback URL and the user’s organization. To try it now, use the ID of your test organization, under Organizations in the dashboard.

   • Node.js
   • Python
   • Go
   • Java
   • Direct URL (No SDK)

   1
   import { ScalekitClient } from '@scalekit-sdk/node';
   2
   
   3
   const scalekit = new ScalekitClient(
   4
     '<SCALEKIT_ENVIRONMENT_URL>',    // Your Scalekit environment URL
   5
     '<SCALEKIT_CLIENT_ID>',          // Unique identifier for your app
   6
     '<SCALEKIT_CLIENT_SECRET>',
   7
   );
   8
   
   9
   const options = {};
   10
   
   11
   // Send the user to their organization's SSO. To route by connection ID or by
   12
   // the user's email domain instead, see /sso/guides/authorization-url/
   13
   options['organizationId'] = 'org_15421144869927830';
   14
   
   15
   // redirect_uri: Your callback endpoint that receives the authorization code
   16
   // Must match the URL registered in your Scalekit dashboard
   17
   const redirectUrl = 'http://localhost:3000/auth/callback';
   18
   
   19
   const authorizationURL = scalekit.getAuthorizationUrl(redirectUrl, options);
   20
   // Redirect user to this URL to begin SSO authentication

   Scalekit sends the user to their organization’s identity provider. Once they sign in there, Scalekit sends them to your callback URL with a one-time code.

5. Read the user’s profile at your callback

   Section titled “Read the user’s profile at your callback”

   Add an endpoint at your callback URL. It receives a code, or an error and error_description if the login failed. Exchange the code for the user’s profile:

   • Node.js
   • Python
   • Go
   • Java

   1
   // Extract authentication parameters from the callback request
   2
   const { code, error, error_description } = req.query;
   3
   
   4
   if (error) {
   5
     // The login failed at Scalekit or at the identity provider
   6
     return res.status(401).send('Sign-in failed');
   7
   }
   8
   
   9
   // The same callback URL you passed to getAuthorizationUrl
   10
   const redirectUri = 'http://localhost:3000/auth/callback';
   11
   const result = await scalekit.authenticateWithCode(code, redirectUri);
   12
   const userEmail = result.user.email;
   13
   
   14
   // Create a session for the authenticated user and grant appropriate access permissions

   To read the claims in the tokens yourself, validate them with the SDK:

   • Node.js
   • Python
   • Go
   • Java

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

   • Auth result
   • ID token (decoded)
   • Access token (decoded)

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

   user.id is the ID token’s sub: the connection ID and the user’s ID at the identity provider, joined by ;. The ID token’s oid claim is the user’s organization ID. See Normalized user profile for every field.

   Before you go to production, check a state value on each callback and find or create the user in your database. See Handle the callback and find the user.

6. Check it worked

   Section titled “Check it worked”
   1. Open the authorization URL from step 4 with your test organization’s ID. The SSO simulator opens in place of a real identity provider.
   2. Leave User Login via SSO selected, enter a user name such as jane (the domain is example.com) and a first and last name, and select Simulate Login.

   Your callback receives a code, and the exchange returns a profile with the email and name you entered. If the callback receives an error instead, look it up in the SSO error reference. For more test cases, such as IdP-initiated login and error scenarios, see Test SSO.