Social Login & Internal SSO

This page covers two systems that are different from the OAuth IdP for external clients. Do not confuse them:

System	Purpose	Key token	Entry point
OAuth IdP (OIDC)	External OAuth clients	code → ES256 → internal exchange	`/api/v3/oauth/*`
Social login	B Brands end users sign in with a social provider	internal HS256 JWT	`/api/v3/auth/login/oauth/<provider>`
Internal SSO	Carry a session across B Brands apps on different domains	short-lived signed token in the URL	`/api/v3/auth/sso/exchange`

End users sign into B Brands apps with a social provider. This uses the managed engine’s social sign-in directly, then mints the internal B Brands JWT — it does not use the OAuth IdP, ES256 tokens, or the consent screen.

Routes

Step	Method	Path
1. Start	GET	`/api/v3/auth/login/oauth/<provider>?redirect_url=<url>&format=json`
2. Callback (HTML bridge)	GET	`/api/v3/auth/login/oauth/<provider>/callback`
3. Processing	GET	`/api/v3/auth/login/oauth/<provider>/callback-redirect`

The start route requires redirect_url; format=json (or Accept: application/json) returns JSON instead of a 302.
The /callback page is an HTML bridge that reads the URL fragment (#access_token…) or ?code= and forwards it to /callback-redirect.
/callback-redirect sets the engine session, auto-registers a profile if needed, and returns the internal B Brands JWT (HS256) plus account data.

Legacy routes exist for additional providers under an earlier API version. The current flow adds a parametrizable redirect_url and JSON/deep-link support.

2. Internal SSO — the cross-app handshake

When a user logs in via the authentication app and must land on a sibling B Brands app on a different domain, the session is carried with a short-lived signed token in the URL. A small shared internal package handles this.

Shared internal SSO package

A small package for consumer apps, with helpers for:

Helper	Purpose
Sign / verify	Create and validate the short-lived HS256 handshake token (`{ jwt, nonce, next? }` claims, default TTL 60s)
Exchange	Call `POST /api/v3/auth/sso/exchange` and receive the session `{ jwt }`
Proxy	A middleware that turns the handshake token into a session cookie

// Consumer app proxy (pseudocode)
const sso = createSsoProxy({
  backendUrl: config.routeApiUrl,
  cookieDomain: config.sessionCookieDomain,
  cookieName: config.sessionCookieName,
  hmacSecret: config.ssoHmacSecret,
  isProduction: config.isProduction,
});

export default function proxy(request) {
  if (hasHandshakeToken(request)) return sso.proxy(request);
  // ...session guard
}

The SSO issuer

The authentication app is the centralized login/register/2FA + consent UI. It is the issuer: it signs the handshake token and writes the session cookie directly in server actions (it does not mount the consumer proxy). Same-domain targets redirect without a handshake token; cross-domain targets receive one.

The internal SSO exchange (/api/v3/auth/sso/exchange) is for cross-app session transfer. It is not the external OAuth client exchange (/api/v3/oauth/exchange). See Token exchange.

Security model

Aspect	Detail
Algorithm	HS256
Secret	A shared HMAC secret between issuer and backend
TTL	60s — only survives one redirect
Claims	`jwt`, `nonce`, `next?` + `iss`/`aud`/`iat`/`exp`
Target cookie	`HttpOnly`, `SameSite=Lax`, `Secure` in prod
Failure	Proxy redirects to a clean URL with `?sso_error=exchange_failed`

Get Started

API Documentation

OAuth & Identity (IdP)

Monitoring & Infrastructure

Realtime (Pusher)

Notifications (OneSignal)

Social Login & Internal SSO

Routes

2. Internal SSO — the cross-app handshake

Shared internal SSO package

The SSO issuer

Security model

​1. Social login

​Routes

​2. Internal SSO — the cross-app handshake

​Shared internal SSO package

​The SSO issuer

​Security model

1. Social login

Routes

2. Internal SSO — the cross-app handshake

Shared internal SSO package

The SSO issuer

Security model