Server Client API

Import:

import { createFrappeSSO } from 'sso-frappe/server';

`createFrappeSSO(config)`

Creates a server-side Frappe SSO client. This is the only entry point that accepts clientSecret.

const sso = createFrappeSSO({
  baseUrl: 'https://erp.example.com',
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
  redirectUri: 'https://app.example.com/api/auth/callback/frappe',
  scope: ['openid'],           // optional, default ['openid']
  usePkce: true,               // optional, default true
  allowInsecureHttp: false,    // optional, default false
  timeoutMs: 10_000,           // optional, default 10000
});

Returns a FrappeSSOClient with the methods below.

`createAuthorizationUrl()`

Generates the authorization URL, state, and PKCE pair. Use this when your backend owns the redirect (e.g. Nuxt Nitro, Express).

const { url, state, codeVerifier } = await sso.createAuthorizationUrl();

// Store state + codeVerifier in a server-side session
req.session.frappeState = state;
req.session.frappeVerifier = codeVerifier;

// Redirect the user
res.redirect(url);

`exchangeCode({ code, codeVerifier })`

Exchanges the authorization code for an access token. Server-only — requires clientSecret.

const token = await sso.exchangeCode({
  code: 'auth-code-from-frappe',
  codeVerifier: 'verifier-from-session',
});

// token.accessToken  — string
// token.tokenType    — string (usually 'Bearer')
// token.expiresIn    — number | undefined
// token.refreshToken — string | undefined
// token.raw          — full response from Frappe

Throws FrappeSSOTokenError on failure.

`getUserProfile(token)`

Fetches the user profile from Frappe's userinfo endpoint.

const profile = await sso.getUserProfile(token);

// profile.subject  — stable user ID (the `sub` claim)
// profile.email    — email address
// profile.name     — full name
// profile.username — Frappe username
// profile.image    — avatar URL
// profile.roles    — string[] (e.g. ['System User', 'Employee'])
// profile.raw      — full userinfo response

Throws FrappeSSOProfileError on failure.

`discover()`

Fetches the OIDC discovery document. Called automatically by exchangeCode and getUserProfile if explicit endpoints aren't configured.

const metadata = await sso.discover();

// metadata.authorization_endpoint
// metadata.token_endpoint
// metadata.userinfo_endpoint
// ...

Throws FrappeSSODiscoveryError if the endpoint is unreachable or malformed.

`validateState(stored, received)`

Validates that the state returned by Frappe matches the one you stored. Exported from both sso-frappe and sso-frappe/server.

import { validateState } from 'sso-frappe/server';

validateState(storedState, receivedState);  // throws FrappeSSOStateError on mismatch

Configuration reference

Field	Required	Default	Description
`baseUrl`	Yes	—	Frappe instance URL
`clientId`	Yes	—	OAuth client ID
`clientSecret`	Yes	—	OAuth client secret (server-only)
`redirectUri`	Yes	—	Consumer callback URL
`scope`	No	`['openid']`	OAuth scopes
`usePkce`	No	`true`	PKCE S256
`allowInsecureHttp`	No	`false`	Allow `http://` for local dev
`timeoutMs`	No	`10000`	HTTP timeout
`authorizationEndpoint`	No	discovery	Explicit override
`tokenEndpoint`	No	discovery	Explicit override
`userInfoEndpoint`	No	discovery	Explicit override
`discoveryEndpoint`	No	`${baseUrl}/.well-known/openid-configuration`	Explicit override

Errors

All errors extend FrappeSSOError. Error messages never include secrets.

Error	When
`FrappeSSOConfigError`	Invalid config (missing field, bad URL, etc.)
`FrappeSSOStateError`	State mismatch or missing state/code/verifier
`FrappeSSOTokenError`	Token exchange failed
`FrappeSSOProfileError`	Userinfo fetch failed
`FrappeSSODiscoveryError`	Discovery endpoint unreachable/malformed