sso-frappe

sso-frappe

Reusable OAuth2/OIDC client for adding "Login with Frappe" to JavaScript/TypeScript applications.

One package, multiple entry points. Pick the entry point that matches your runtime. OAuth core stays shared and framework-agnostic.

Supported stacks

Entry points

Quick start

A. Next.js + Auth.js v5

npm install sso-frappe

// auth.ts
import NextAuth from 'next-auth';
import { frappeNextAuthProvider } from 'sso-frappe/next-auth';

export const { handlers, auth, signIn, signOut } = NextAuth({
  providers: [
    frappeNextAuthProvider({
      baseUrl: process.env.FRAPPE_SSO_BASE_URL!,
      clientId: process.env.FRAPPE_SSO_CLIENT_ID!,
      clientSecret: process.env.FRAPPE_SSO_CLIENT_SECRET!,
      redirectUri: `${process.env.NEXTAUTH_URL}/api/auth/callback/frappe`,
    }),
  ],
});

Full guide: docs/nextjs.md

B. React SPA + JS backend

npm install sso-frappe

// frontend
import { createFrappeSSOBrowser } from 'sso-frappe/browser';

const sso = createFrappeSSOBrowser({
  baseUrl: process.env.NEXT_PUBLIC_FRAPPE_SSO_BASE_URL!,
  clientId: process.env.NEXT_PUBLIC_FRAPPE_SSO_CLIENT_ID!,
  redirectUri: 'https://app.example.com/auth/callback',
});

await sso.startLogin();

const { code, codeVerifier } = await sso.handleCallback();
await fetch('/api/auth/frappe/callback', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({ code, codeVerifier }),
});

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

const sso = createFrappeSSO({
  baseUrl: process.env.FRAPPE_SSO_BASE_URL!,
  clientId: process.env.FRAPPE_SSO_CLIENT_ID!,
  clientSecret: process.env.FRAPPE_SSO_CLIENT_SECRET!,
  redirectUri: 'https://app.example.com/auth/callback',
});

app.post('/api/auth/frappe/callback', async (req, res) => {
  const { code, codeVerifier } = req.body;
  const token = await sso.exchangeCode({ code, codeVerifier });
  const profile = await sso.getUserProfile(token);
  // upsert user, create session, respond
});

Full guides: docs/react.md, docs/vue.md, docs/nuxt.md

C. Laravel / Lumen

Package PHP terpisah: sso-frappe/laravel.

Laravel

composer require sso-frappe/laravel laravel/socialite

use Laravel\Socialite\Facades\Socialite;

Route::get('/auth/frappe', fn () => Socialite::driver('frappe')->redirect());

Route::get('/auth/frappe/callback', function () {
    $frappeUser = Socialite::driver('frappe')->user();
    // match/create local user
});

Lumen

composer require sso-frappe/laravel

use SsoFrappe\Laravel\FrappeClient;

$client = app(FrappeClient::class);
$url = $client->authorizationUrl($state, $codeChallenge);
$token = $client->exchangeCode($code, $codeVerifier);
$profile = $client->getUserByToken($token['access_token']);
$user = $client->mapUser($profile);

Full guide: docs/laravel.md

D. Frappe → Frappe

Frappe already has built-in Social Login Key support. Zero code on consumer side.

Full guide: docs/frappe-to-frappe.md

Environment variables

Configuration reference

Security rules

• clientSecret lives only in backend. Never in browser bundles.
• redirectUri must exactly match Frappe registration.
• State must be validated on callback.
• PKCE uses S256.

Recommended user identity schema

Add user_identities to link external providers to users. One user can log in via Frappe, Google, password, and other providers without altering schema.

CREATE TABLE users (
    id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    email           VARCHAR(255) NOT NULL UNIQUE,
    name            VARCHAR(255),
    password        VARCHAR(255),
    image           TEXT,
    status          VARCHAR(20) DEFAULT 'AKTIF',
    role            VARCHAR(50) DEFAULT 'user',
    created_at      TIMESTAMPTZ DEFAULT now(),
    updated_at      TIMESTAMPTZ DEFAULT now()
);

CREATE TABLE user_identities (
    id               UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id          UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    provider         VARCHAR(50) NOT NULL,
    provider_subject VARCHAR(255) NOT NULL,
    provider_email   VARCHAR(255),
    metadata         JSONB,
    created_at       TIMESTAMPTZ DEFAULT now(),
    updated_at       TIMESTAMPTZ DEFAULT now(),
    UNIQUE (provider, provider_subject)
);

Full guide: docs/database-schema.md

Docs index

License

MIT