Migrate SSO without IdP reconfiguration for customers

Single Sign-On capability of your application allows users in your customer’s organizations to access your application using their existing credentials. In this guide, you will migrate SSO connections to Scalekit without requiring customers to reconfigure their identity providers from their existing SSO provider solutions such as Auth0 or WorkOS.

Prerequisites

You control DNS for your auth domain, and its CNAME points to your external SSO provider.
Scalekit is set up — you have signed up and installed the Scalekit SDK.

Approach to migrate SSO connections

Our main goal is to make sure your current SSO connections keep working seamlessly, while enabling new connections to be set up with Scalekit—giving you the flexibility to migrate to Scalekit whenever you’re ready.

This primarily involves two key components:

The data migration of tenant resources such as organizations and users. We provide a data migration utility to automate this approach.
A SSO proxy service that routes SSO connections between your existing SSO provider and Scalekit. We can assist with a ready-to-deploy SSO proxy service that best suits your infrastructure.

SSO proxy implementation

The SSO proxy ensures those connections continue to work while you gradually migrate. This approach is ideal when you prefer a staged rollout—move organizations one by one or all at once with data migration utilty without forcing customers to reconfigure SSO connection settings in their IdP.

Proxy routes SSO requests to external providers or Scalekit

The SSO proxy acts as a smart router that directs authentication requests to the right provider. It sits between your application and both SSO systems, making migration seamless.

Provider selection

Your app sends login requests with user information (email, domain, or organization ID). The proxy analyzes this data and routes authentication to either the external provider or Scalekit.
Redirection to proxy domain

Users are redirected to your proxy domain (e.g., auth.yourapp.com) to begin authentication. This domain handles all SSO traffic during migration.
Request forwarding

The proxy forwards authentication requests to the selected provider while preserving all necessary identifiers and session parameters.
Identity provider processing

The user’s IdP processes authentication and sends responses (SAML or OIDC) back to your proxy domain via configured callback URLs.
Response routing

The proxy examines response identifiers to determine which provider handled authentication and routes the callback accordingly.
Code exchange

Your app receives an authorization code with a state indicator showing which provider processed the request. Use this information to complete the authentication flow.

Set up provider selection in your auth server

Maintain organization migration mapping

Store information about which organizations are migrated to Scalekit versus those still using external SSO providers. You can use a database, configuration file, or API endpoint based on your app architecture. This mapping determines which SSO provider to use for each organization.
example: organization-mapping.js
```
1
const organizationMapping = {
2
  'megasoft.com': { provider: 'workos', migrated: false },
3
  'example.com': { provider: 'workos', migrated: false },
4
  'newcompany.com': { provider: 'scalekit', migrated: true }
5
};
```

Implement conditional routing logic

Add logic to your authentication endpoint that checks the organization mapping and redirects users to the appropriate SSO provider. For migrated organizations, route to Scalekit; for others, use the external provider.

1
app.post('/sso-login', (req, res) => {
2
  const { email } = req.body;
3
  const [, domain] = email.split('@');
4

5
  // Check for force Scalekit header (helpful for debugging)
6
  const forceScalekit = req.headers['x-force-sk-route'] === 'yes';
7

8
  if (forceScalekit || organizationMapping[domain]?.migrated) {
9
    // Route to Scalekit
10
    const authUrl = scalekit.getAuthorizationUrl(redirectUri, { loginHint: email, domain });
11
    res.redirect(authUrl);
12
  } else {
13
    // Route to external provider
14
    const authUrl = externalProvider.getAuthorizationUrl(redirectUri, { email });
15
    res.redirect(authUrl);
16
  }
17
});

SSO proxy handles provider interactions

The SSO proxy manages all interactions with SSO providers and identity providers. See the SSO proxy architecture overview section above for details on how this works.
Create separate callback endpoints

Set up two callback endpoints to handle authorization codes from different providers. While you can use one endpoint, separate endpoints are recommended for clarity and easier debugging.
Callback endpoints
```
1
https://yourapp.com/auth/ext-provider/callback  # External provider
2
https://yourapp.com/auth/scalekit/callback     # Scalekit
```

Handle code exchange and user profile retrieval

Your callback endpoints receive authorization codes and exchange them for user profile details. The proxy adds state indicators to help identify which provider processed the authentication.

1
// External provider callback
2
app.get("/auth/ext-provider/callback", async (req, res) => {
3
  const { code, state } = req.query;
4
  // Exchange code with external provider for user profile
5
  const userProfile = await externalProvider.exchangeCode(code);
6
  // Create session and redirect
7
});
8

9
// Scalekit callback
10
app.get("/auth/scalekit/callback", async (req, res) => {
11
  const { code } = req.query;
12
  // Exchange code with Scalekit for user profile
13
  const userProfile = await scalekit.authenticateWithCode(code, redirectUri);
14
  // Create session and redirect
15
});

Once you create equivalent organizations in Scalekit for the ones you plan to migrate, the proxy can begin routing callbacks to Scalekit for those organizations while others continue on the external provider.

Update organization mapping for migrated organizations

When organizations are ready for Scalekit, update your mapping to mark them as migrated. The proxy will automatically route these to Scalekit.
Proxy routes Scalekit requests appropriately

The proxy detects migrated organizations and routes authentication to Scalekit while maintaining the same callback URLs for seamless user experience.
Handle Scalekit callbacks

Use your existing Scalekit callback endpoint to process authentication responses and complete the login flow.