How Modular SSO works

This page explains the parts of a Modular SSO login and how they fit together. Read it after the quickstart, or before it if you want the whole picture first.

An environment holds everything for one stage of your app, such as development or production: its own API credentials, environment URL, organizations and connections. Its credentials are under Developers > Settings > API Credentials in the dashboard.

To use Modular SSO, set the environment’s authentication mode to Modular Auth in Settings > Authentication Mode. In this mode your app keeps its users and sessions, and Scalekit returns the verified user to your app.

A development environment comes with a test organization and an SSO simulator, so you can test before you have a customer. See Test SSO.

An organization is one of your customers, usually a company, such as Megacorp. Create one for each customer that wants SSO, in the dashboard or with the API. Its ID starts with org_.

Store the organization ID with the customer’s record in your app. You use it to start their users’ logins, and the ID token at the end of each login tells you which organization the user belongs to.

A connection links an organization to its identity provider (IdP), such as Okta or Microsoft Entra ID, over SAML or OIDC. Its ID starts with conn_.

Usually your customer’s IT admin sets up the connection in the admin portal: they enter the IdP’s details and test the login. You can also set it up for them from the organization’s page in the dashboard. Each IdP’s setup steps are in the IdP guides.

An organization’s domains are the email domains its users sign in with, such as megacorp.com. With a domain on the organization, your app can send a user to the right IdP from their email address alone, without asking which company they’re from. See Route users to SSO by email domain.

Scalekit only sends users to URLs you’ve registered under Authentication > Redirect URLs:

• Allowed callback URL: where Scalekit sends the user at the end of a login, with a one-time code. Your app exchanges the code for the user’s profile.
• Initiate login URL: where Scalekit sends a user who started from their IdP’s dashboard, so your app can start the login itself.

See Register redirect URLs.

Your app starts a login by redirecting the user to an authorization URL that the SDK builds. The URL names your callback URL and the customer, by one of:

• the connection ID
• the organization ID
• a domain hint, such as megacorp.com
• a login hint, the user’s email address, whose domain picks the organization

If you pass more than one, Scalekit uses them in a fixed order. See Authorization URL parameters.

Pass a state value too. Scalekit returns it unchanged to your callback, so your app can check that the response belongs to a login it started.

Some users start from their IdP’s dashboard, such as an app tile in Okta. Scalekit sends them to your initiate login URL with an idp_initiated_login token. Your endpoint reads the organization and connection from the token and starts a normal login with an authorization URL. See IdP-initiated SSO.

At the end of a login, Scalekit redirects the user to your callback URL with a code and the state you sent, or with error and error_description if the login failed. Your app exchanges the code with the SDK and gets:

• The user’s profile: email, name and the other fields of the normalized user profile, in the same format for every IdP.
• An ID token: a signed JWT with the same profile. Its sub claim is the connection ID and the user’s ID at the IdP, joined by ;. Its oid claim is the organization ID.
• An access token.

There’s no refresh token: after the login, your app runs the session. To find or create the user in your database, see Handle the callback and find the user.

The admin portal is a page Scalekit hosts where your customer’s IT admin sets up and tests their SSO connection. Share a link to it, or embed it in your app’s settings page. See Admin portal.

Scalekit sends webhook events when a customer’s SSO connection is created, enabled, disabled or deleted, so your app can turn SSO on for the customer at the right time. See SSO events.