Handle the callback and find the user

Build the Modular SSO callback: check the state and errors, exchange the code, find or create the user in your database and start your app's session.

At the end of an SSO login, Scalekit redirects the user to your callback URL. This page builds that endpoint for production. By the end, your app:

starts each login with a state value and rejects responses it didn’t ask for
turns failed logins into a clear message
finds or creates the user in your database, keyed on a stable ID rather than an email address
starts your own session

Before you start

Complete the quickstart: your environment is in Modular Auth mode, and your callback URL is registered under Authentication > Redirect URLs > Allowed callback URLs.

Add these to your .env file. REDIRECT_URI is your registered callback URL. SESSION_SECRET signs your app’s session cookie; use a long random value.

SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
SCALEKIT_CLIENT_ID=<your-client-id>
SCALEKIT_CLIENT_SECRET=<your-client-secret>
REDIRECT_URI=http://localhost:3000/auth/callback
SESSION_SECRET=<a-long-random-value>

Build the endpoints

Install the SDK and a web framework
Section titled “Install the SDK and a web framework”
Terminal window
npm install @scalekit-sdk/node express express-session dotenv
Terminal window
pip install scalekit-sdk-python flask python-dotenv
Terminal window
go get -u github.com/scalekit-inc/scalekit-sdk-go/v2
Add com.scalekit:scalekit-sdk-java to a Spring Boot web app. See Install the SDK for the Maven and Gradle lines.

The example has two endpoints:

/auth/sso starts a login. It creates a random state value, stores it in the user’s browser session and passes it in the authorization URL. It takes the customer’s organization ID; in your app, look it up from your records, for example by the email domain the user entered.
/auth/callback finishes it. It checks the response, exchanges the code for the user’s profile, finds or creates the user and starts your session.

1
import crypto from 'node:crypto';
2
import 'dotenv/config';
3
import express from 'express';
4
import session from 'express-session';
5
import { ScalekitClient } from '@scalekit-sdk/node';
6

7
const scalekit = new ScalekitClient(
8
  process.env.SCALEKIT_ENVIRONMENT_URL,
9
  process.env.SCALEKIT_CLIENT_ID,
10
  process.env.SCALEKIT_CLIENT_SECRET,
11
);
12
const redirectUri = process.env.REDIRECT_URI;
13

14
const app = express();
15
app.use(
16
  session({ secret: process.env.SESSION_SECRET, resave: false, saveUninitialized: false }),
17
);
18

19
// Your users table. Replace with your database.
20
const users = new Map();
21

22
function findOrCreateUser({ organizationId, idpUserId, email, name }) {
23
  const key = `${organizationId}:${idpUserId}`;
24
  let user = users.get(key);
25
  if (!user) {
26
    user = { id: crypto.randomUUID(), organizationId, idpUserId };
27
    users.set(key, user);
28
  }
29
  // Keep the profile current: email and name can change at the IdP
30
  Object.assign(user, { email, name });
31
  return user;
32
}
33

34
// Start an SSO login for one of your customers
35
app.get('/auth/sso', (req, res) => {
36
  const state = crypto.randomBytes(16).toString('hex');
37
  req.session.ssoState = state;
38
  const url = scalekit.getAuthorizationUrl(redirectUri, {
39
    organizationId: req.query.organization_id,
40
    state,
41
  });
42
  res.redirect(url);
43
});
44

45
app.get('/auth/callback', async (req, res, next) => {
46
  const { code, state, error, error_description } = req.query;
47
  const expectedState = req.session.ssoState;
48
  delete req.session.ssoState;
49

50
  if (error) {
51
    console.warn(`SSO login failed: ${error}: ${error_description}`);
52
    return res.status(401).send('Sign-in failed');
53
  }
54
  if (!state || state !== expectedState) {
55
    return res.status(400).send('Sign-in failed: unexpected state');
56
  }
57

58
  let result, claims;
59
  try {
60
    result = await scalekit.authenticateWithCode(code, redirectUri);
61
    // The ID token's oid claim is the user's organization
62
    claims = await scalekit.validateToken(result.idToken);
63
  } catch (err) {
64
    console.warn('Code exchange failed:', err.message);
65
    return res.status(401).send('Sign-in failed');
66
  }
67

68
  const profile = result.user;
69
  const user = findOrCreateUser({
70
    organizationId: claims.oid,
71
    idpUserId: profile.id.slice(profile.id.indexOf(';') + 1),
72
    email: profile.email,
73
    name: [profile.givenName, profile.familyName].filter(Boolean).join(' '),
74
  });
75

76
  // Start a fresh session for the user, so a session ID set before login can't be reused
77
  req.session.regenerate((err) => {
78
    if (err) return next(err);
79
    req.session.userId = user.id;
80
    res.redirect('/');
81
  });
82
});
83

84
app.listen(3000, () => console.log('Listening on http://localhost:3000'));

Run it with node server.mjs.

1
import os
2
import secrets
3

4
from dotenv import load_dotenv
5
from flask import Flask, redirect, request, session
6
from scalekit import AuthorizationUrlOptions, CodeAuthenticationOptions, ScalekitClient
7

8
load_dotenv()
9

10
scalekit_client = ScalekitClient(
11
    env_url=os.environ["SCALEKIT_ENVIRONMENT_URL"],
12
    client_id=os.environ["SCALEKIT_CLIENT_ID"],
13
    client_secret=os.environ["SCALEKIT_CLIENT_SECRET"],
14
)
15
redirect_uri = os.environ["REDIRECT_URI"]
16

17
app = Flask(__name__)
18
app.secret_key = os.environ["SESSION_SECRET"]
19

20
# Your users table. Replace with your database.
21
users = {}
22

23

24
def find_or_create_user(organization_id, idp_user_id, email, name):
25
    key = (organization_id, idp_user_id)
26
    user = users.get(key)
27
    if user is None:
28
        user = {"id": secrets.token_hex(16), "organization_id": organization_id, "idp_user_id": idp_user_id}
29
        users[key] = user
30
    # Keep the profile current: email and name can change at the IdP
31
    user.update(email=email, name=name)
32
    return user
33

34

35
# Start an SSO login for one of your customers
36
@app.route("/auth/sso")
37
def start_sso():
38
    state = secrets.token_urlsafe(16)
39
    session["sso_state"] = state
40
    options = AuthorizationUrlOptions()
41
    options.organization_id = request.args.get("organization_id")
42
    options.state = state
43
    return redirect(scalekit_client.get_authorization_url(redirect_uri=redirect_uri, options=options))
44

45

46
@app.route("/auth/callback")
47
def callback():
48
    expected_state = session.pop("sso_state", None)
49
    error = request.args.get("error")
50
    if error:
51
        app.logger.warning("SSO login failed: %s: %s", error, request.args.get("error_description"))
52
        return "Sign-in failed", 401
53
    state = request.args.get("state")
54
    if not state or state != expected_state:
55
        return "Sign-in failed: unexpected state", 400
56

57
    try:
58
        result = scalekit_client.authenticate_with_code(
59
            request.args.get("code"), redirect_uri, CodeAuthenticationOptions()
60
        )
61
    except Exception as e:
62
        app.logger.warning("Code exchange failed: %s", e)
63
        return "Sign-in failed", 401
64

65
    profile = result["user"]
66
    user = find_or_create_user(
67
        # From the ID token's oid claim: the user's organization
68
        organization_id=result["organization_id"],
69
        idp_user_id=profile["id"].split(";", 1)[1],
70
        email=profile.get("email"),
71
        name=" ".join(filter(None, [profile.get("givenName"), profile.get("familyName")])),
72
    )
73

74
    # Start a fresh session for the user
75
    session.clear()
76
    session["user_id"] = user["id"]
77
    return redirect("/")
78

79

80
if __name__ == "__main__":
81
    app.run(port=3000)

Run it with python app.py.

1
package main
2

3
import (
4
  "crypto/rand"
5
  "encoding/hex"
6
  "log"
7
  "net/http"
8
  "os"
9
  "strings"
10
  "sync"
11

12
  scalekit "github.com/scalekit-inc/scalekit-sdk-go/v2"
13
)
14

15
var (
16
  scalekitClient = scalekit.NewScalekitClient(
17
    os.Getenv("SCALEKIT_ENVIRONMENT_URL"),
18
    os.Getenv("SCALEKIT_CLIENT_ID"),
19
    os.Getenv("SCALEKIT_CLIENT_SECRET"),
20
  )
21
  redirectURI = os.Getenv("REDIRECT_URI")
22

23
  // Your users table. Replace with your database.
24
  usersMu sync.Mutex
25
  users   = map[string]*AppUser{}
26
)
27

28
type AppUser struct {
29
  ID, OrganizationID, IdpUserID, Email, Name string
30
}
31

32
func findOrCreateUser(organizationID, idpUserID, email, name string) *AppUser {
33
  usersMu.Lock()
34
  defer usersMu.Unlock()
35
  key := organizationID + ":" + idpUserID
36
  user, ok := users[key]
37
  if !ok {
38
    user = &AppUser{ID: randomHex(), OrganizationID: organizationID, IdpUserID: idpUserID}
39
    users[key] = user
40
  }
41
  // Keep the profile current: email and name can change at the IdP
42
  user.Email, user.Name = email, name
43
  return user
44
}
45

46
func randomHex() string {
47
  b := make([]byte, 16)
48
  if _, err := rand.Read(b); err != nil {
49
    panic(err)
50
  }
51
  return hex.EncodeToString(b)
52
}
53

54
// Start an SSO login for one of your customers
55
func startSSO(w http.ResponseWriter, r *http.Request) {
56
  state := randomHex()
57
  http.SetCookie(w, &http.Cookie{
58
    Name: "sso_state", Value: state, Path: "/auth", MaxAge: 600,
59
    HttpOnly: true, Secure: true, SameSite: http.SameSiteLaxMode,
60
  })
61
  authURL, err := scalekitClient.GetAuthorizationUrl(redirectURI, scalekit.AuthorizationUrlOptions{
62
    OrganizationId: r.URL.Query().Get("organization_id"),
63
    State:          state,
64
  })
65
  if err != nil {
66
    http.Error(w, "Could not start sign-in", http.StatusInternalServerError)
67
    return
68
  }
69
  http.Redirect(w, r, authURL.String(), http.StatusFound)
70
}
71

72
func callback(w http.ResponseWriter, r *http.Request) {
73
  q := r.URL.Query()
74
  stateCookie, cookieErr := r.Cookie("sso_state")
75
  http.SetCookie(w, &http.Cookie{Name: "sso_state", Path: "/auth", MaxAge: -1})
76

77
  if errCode := q.Get("error"); errCode != "" {
78
    log.Printf("SSO login failed: %s: %s", errCode, q.Get("error_description"))
79
    http.Error(w, "Sign-in failed", http.StatusUnauthorized)
80
    return
81
  }
82
  if cookieErr != nil || q.Get("state") == "" || q.Get("state") != stateCookie.Value {
83
    http.Error(w, "Sign-in failed: unexpected state", http.StatusBadRequest)
84
    return
85
  }
86

87
  result, err := scalekitClient.AuthenticateWithCode(
88
    r.Context(), q.Get("code"), redirectURI, scalekit.AuthenticationOptions{},
89
  )
90
  if err != nil {
91
    log.Printf("Code exchange failed: %v", err)
92
    http.Error(w, "Sign-in failed", http.StatusUnauthorized)
93
    return
94
  }
95
  // The ID token's oid claim is the user's organization
96
  claims, err := scalekitClient.ValidateToken(r.Context(), result.IdToken)
97
  organizationID, _ := claims["oid"].(string)
98
  if err != nil || organizationID == "" {
99
    log.Printf("ID token check failed: %v", err)
100
    http.Error(w, "Sign-in failed", http.StatusUnauthorized)
101
    return
102
  }
103

104
  profile := result.User
105
  _, idpUserID, _ := strings.Cut(profile.Id, ";")
106
  name := strings.TrimSpace(profile.GivenName + " " + profile.FamilyName)
107
  user := findOrCreateUser(organizationID, idpUserID, profile.Email, name)
108

109
  // Start your app's session for user.ID here, the way your app does after any login
110
  log.Printf("Signed in user %s", user.ID)
111
  http.Redirect(w, r, "/", http.StatusFound)
112
}
113

114
func main() {
115
  http.HandleFunc("/auth/sso", startSSO)
116
  http.HandleFunc("/auth/callback", callback)
117
  log.Fatal(http.ListenAndServe(":3000", nil))
118
}

Go doesn’t load .env files on its own: export the variables in your shell, then run go run main.go.

1
package com.example.sso;
2

3
import com.scalekit.ScalekitClient;
4
import com.scalekit.internal.http.AuthenticationOptions;
5
import com.scalekit.internal.http.AuthenticationResponse;
6
import com.scalekit.internal.http.AuthorizationUrlOptions;
7
import com.scalekit.internal.http.IdTokenClaims;
8
import jakarta.servlet.http.HttpServletRequest;
9
import jakarta.servlet.http.HttpSession;
10
import java.security.SecureRandom;
11
import java.util.HexFormat;
12
import java.util.Map;
13
import java.util.UUID;
14
import java.util.concurrent.ConcurrentHashMap;
15
import org.slf4j.Logger;
16
import org.slf4j.LoggerFactory;
17
import org.springframework.http.ResponseEntity;
18
import org.springframework.web.bind.annotation.GetMapping;
19
import org.springframework.web.bind.annotation.RequestParam;
20
import org.springframework.web.bind.annotation.RestController;
21

22
@RestController
23
public class SsoController {
24

25
    private static final Logger log = LoggerFactory.getLogger(SsoController.class);
26

27
    private final ScalekitClient scalekitClient = new ScalekitClient(
28
        System.getenv("SCALEKIT_ENVIRONMENT_URL"),
29
        System.getenv("SCALEKIT_CLIENT_ID"),
30
        System.getenv("SCALEKIT_CLIENT_SECRET")
31
    );
32
    private final String redirectUri = System.getenv("REDIRECT_URI");
33
    private final SecureRandom random = new SecureRandom();
34

35
    // Your users table. Replace with your database.
36
    public record AppUser(String id, String organizationId, String idpUserId, String email, String name) {}
37
    private final Map<String, AppUser> users = new ConcurrentHashMap<>();
38

39
    private AppUser findOrCreateUser(String organizationId, String idpUserId, String email, String name) {
40
        // Keep the profile current: email and name can change at the IdP
41
        return users.compute(organizationId + ":" + idpUserId, (key, existing) -> new AppUser(
42
            existing != null ? existing.id() : UUID.randomUUID().toString(),
43
            organizationId, idpUserId, email, name));
44
    }
45

46
    // Start an SSO login for one of your customers
47
    @GetMapping("/auth/sso")
48
    public ResponseEntity<Void> startSso(
49
            @RequestParam("organization_id") String organizationId, HttpSession session) {
50
        byte[] bytes = new byte[16];
51
        random.nextBytes(bytes);
52
        String state = HexFormat.of().formatHex(bytes);
53
        session.setAttribute("ssoState", state);
54

55
        AuthorizationUrlOptions options = new AuthorizationUrlOptions();
56
        options.setOrganizationId(organizationId);
57
        options.setState(state);
58
        String url = scalekitClient.authentication()
59
            .getAuthorizationUrl(redirectUri, options)
60
            .toString();
61
        return ResponseEntity.status(302).header("Location", url).build();
62
    }
63

64
    @GetMapping("/auth/callback")
65
    public ResponseEntity<String> callback(
66
            @RequestParam Map<String, String> params, HttpServletRequest request) {
67
        HttpSession session = request.getSession();
68
        String expectedState = (String) session.getAttribute("ssoState");
69
        session.removeAttribute("ssoState");
70

71
        String error = params.get("error");
72
        if (error != null) {
73
            log.warn("SSO login failed: {}: {}", error, params.get("error_description"));
74
            return ResponseEntity.status(401).body("Sign-in failed");
75
        }
76
        String state = params.get("state");
77
        if (state == null || !state.equals(expectedState)) {
78
            return ResponseEntity.status(400).body("Sign-in failed: unexpected state");
79
        }
80

81
        AuthenticationResponse result;
82
        Map<String, Object> claims;
83
        try {
84
            result = scalekitClient.authentication()
85
                .authenticateWithCode(params.get("code"), redirectUri, new AuthenticationOptions());
86
            // Validates the ID token's signature; its oid claim is the user's organization
87
            claims = scalekitClient.authentication()
88
                .validateAccessTokenAndGetClaims(result.getIdToken());
89
        } catch (Exception e) {
90
            log.warn("Code exchange failed: {}", e.getMessage());
91
            return ResponseEntity.status(401).body("Sign-in failed");
92
        }
93

94
        IdTokenClaims profile = result.getIdTokenClaims();
95
        String sub = profile.getId();
96
        String name = String.join(" ",
97
            java.util.stream.Stream.of(profile.getGivenName(), profile.getFamilyName())
98
                .filter(n -> n != null && !n.isBlank())
99
                .toList());
100
        AppUser user = findOrCreateUser(
101
            (String) claims.get("oid"),
102
            sub.substring(sub.indexOf(';') + 1),
103
            profile.getEmail(),
104
            name);
105

106
        // Start a fresh session for the user, so a session ID set before login can't be reused
107
        session.invalidate();
108
        request.getSession(true).setAttribute("userId", user.id());
109
        return ResponseEntity.status(302).header("Location", "/").build();
110
    }
111
}

Check the response before you trust it
Section titled “Check the response before you trust it”

The callback handles three outcomes, in this order:
- An error parameter. The login failed at Scalekit or at the identity provider (IdP). Log error and error_description, and show the user a short message rather than the raw text. The codes and their fixes are in the SSO error reference.
- A state that doesn’t match. The response isn’t for a login this browser started, for example a forged link. Reject it. The stored value is removed on each callback, so the same response can’t be used twice.
- A code. Exchange it once, with the same redirect URI you passed to the authorization URL. The SDK checks the ID token’s signature and returns the user’s profile.
Your initiate login endpoint also builds an authorization URL, for users who start from their IdP’s dashboard. Store a state value there the same way, or those logins fail the check.
Find or create the user
Section titled “Find or create the user”

Key each user on two values, not on their email:
- The organization ID, which says which customer the user belongs to.
- The user’s ID at the IdP: the part of the profile’s id (the ID token’s sub) after the ;. The part before it is the connection ID, which changes if your customer deletes their SSO connection and creates a new one.
Email addresses change when a user is renamed, and two customers’ IdPs can each assert any address, so an email alone can’t safely identify a user. Store the email and name, and update them at each login. Some IdPs send a changeable value, such as an email address, as the user’s ID; see Choose a stable user identifier, which covers Microsoft Entra ID.

If your app already has users who signed in another way, link an SSO user to an existing account only after a check you trust, such as the email domain being one of the organization’s verified domains.
Start your session
Section titled “Start your session”

Scalekit doesn’t return a refresh token: after the callback, your app runs the session for as long as your app decides. Start it the way your app does after any login. When the session ends, send the user through SSO again; if they’re still signed in at their IdP, they come straight back.

To log a user out, end your app’s session.
Check it worked
Section titled “Check it worked”
1. Start your app.
2. Find your test organization’s ID under Organizations in the dashboard of your development environment.
3. Open http://localhost:3000/auth/sso?organization_id=<test-organization-id>. The SSO simulator opens.
4. 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.
The callback redirects you to /, which this example doesn’t serve, so a “not found” page is expected. Your users table has a user with the test organization’s ID, jane@example.com and the name you entered. Open http://localhost:3000/auth/callback?code=x&state=forged: the response is 400 Sign-in failed: unexpected state.

Onboard an enterprise customer: create their organization and give their IT admin the admin portal.
Map custom user attributes: send roles or groups from the IdP and use them in your app.

Handle the callback and find the user

Before you start

Build the endpoints

Install the SDK and a web framework

Add the login and callback endpoints

Check the response before you trust it

Find or create the user

Start your session

Check it worked

Next