SSO Setup

Authenticate users in Komo automatically so they never see a login screen. Users authenticated in your app are seamlessly authenticated in the embedded Komo experience.

Use Case

Your users are already logged into your event app, loyalty platform, or website. When they interact with an embedded Komo card, you don't want them to see a second login form. SSO passes their identity to Komo so the experience feels native — one session, one identity.

Approach

Komo SSO uses JWT (JSON Web Token) authentication via the embed SDK. The flow is:

  1. 1 User logs into your app (your existing auth system)
  2. 2 Your backend generates a JWT that Komo can verify (using a shared secret or public key configured in the Komo Portal)
  3. 3 Your frontend passes the JWT to the Komo Embed SDK
  4. 4 Komo verifies the JWT and authenticates the user — no login screen shown

Implementation Steps

1. Configure SSO in the Komo Portal

In the Komo Portal, navigate to your Site's settings and enable SSO authentication. Configure the signing secret or public key that Komo will use to verify your JWTs. Note the expected JWT claims (subject, email, name fields).

2. Generate JWTs on Your Backend

When a user is authenticated in your system, generate a JWT containing their identity. The JWT payload should include the claims Komo expects: 

// Node.js example using jsonwebtoken
const jwt = require('jsonwebtoken');

function generateKomoToken(user) {
  const payload = {
    sub: user.id,            // Unique user identifier
    email: user.email,       // User's email
    first_name: user.firstName,
    last_name: user.lastName
  };

  return jwt.sign(payload, KOMO_SSO_SECRET, {
    expiresIn: '1h',
    issuer: 'your-app-name'
  });
}

3. Pass the Token via the Embed SDK

On the frontend, pass the JWT to Komo using setAuthToken. Call this after the embed script loads and before the user interacts with a card. 

// Option A: Set the token directly (if you already have it)
const token = await fetch('/api/komo/auth-token')
  .then(res => res.json())
  .then(data => data.token);

komoEmbed.setAuthToken(token);

4. Handle Auth Requests (Recommended)

For a more robust approach, use setAuthRequestHandler. Komo calls this handler when it needs authentication — this handles token expiration and lazy loading gracefully. 

komoEmbed.setAuthRequestHandler(async function() {
  // This is called when Komo needs the user to be authenticated.
  // Fetch a fresh JWT from your backend.
  const response = await fetch('/api/komo/auth-token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      userId: currentUser.id,
      email: currentUser.email
    })
  });

  if (!response.ok) {
    throw new Error('Failed to get auth token');
  }

  const data = await response.json();
  return data.token;  // Return the JWT string
});

Recommended: setAuthRequestHandler is the preferred approach. It handles token refresh automatically and only requests a token when Komo actually needs one.

5. Handle Logout

When the user logs out of your app, clear their Komo session: 

function onUserLogout() {
  // Clear your app's session
  clearSession();

  // Clear Komo's session
  komoEmbed.forgetUser();
}

Testing

  1. 1. Log into your app as a test user
  2. 2. Open a page with an embedded Komo card
  3. 3. Click the card — it should open without showing a login form
  4. 4. Submit a form in the card — the contact should be created with the user's identity from the JWT
  5. 5. Check the Komo Portal's Contacts section to verify the user appears with the correct email and name

For the full authentication reference, see the Embed SDK authentication docs.