Supertokens

Name: Supertokens
Author: Antibusy

Плагин провайдера аутентификации SuperTokens для Medusa v2. Включает аутентификацию через OAuth2/OpenID Connect с SuperTokens в роли провайдера удостоверений.

В каталоге Medusa

npm install @antibusy/medusa-supertokens

Категория

Авторизация

Создано

Antibusy

Регионы

Во всех регионах

Сервис

SuperTokens

Версия

0.0.4

Последнее обновление

2 месяца назад

Ежемесячные загрузки

NPM Github

@patiparnne/medusa-supertokens

A Medusa v2 authentication provider plugin that enables session-based authentication using SuperTokens as the identity provider. Compatible with SuperTokens free tier (no OAuth2 license required).

Features

Direct session token verification with SuperTokens Core
Works with SuperTokens free tier (no paid features required)
Supports all SuperTokens authentication methods (Email/Password, Passwordless/OTP, Social Login)
Legacy CRM profile integration (refreshes profile data on every auth)
Email verification enforcement (optional)
Seamless integration with Medusa's auth module

Architecture Overview

1┌─────────────────┐     ┌─────────────────────┐     ┌─────────────────┐
2│   Storefront    │     │   hisher-auth       │     │ SuperTokens Core│
3│  (Next.js)      │     │   (Backend API)     │     │   (Database)    │
4│  localhost:3000 │     │   localhost:4002    │     │  localhost:3567 │
5└────────┬────────┘     └──────────┬──────────┘     └────────┬────────┘
       │                         │                          │
       │  1. Login (OTP/Social)  │                          │
       │ ───────────────────────>│                          │
       │                         │  2. Create session       │
       │                         │ ────────────────────────>│
       │  3. Access token        │                          │
       │ <───────────────────────│                          │
       │                         │                          │
       │  4. POST /auth/customer/supertokens                │
       │ ─────────────────────────────────────┐             │
       │                                      │             │
       │                    ┌─────────────────┴─────────────┴─────┐
       │                    │        Medusa Backend               │
       │                    │        localhost:9000               │
       │                    │                                     │
       │                    │  5. Verify token via /profile/      │
       │                    │     verify-token (hisher-auth)      │
       │                    │  6. Get user info & metadata        │
       │                    │  7. Create/retrieve auth identity   │
       │                    └─────────────────────────────────────┘
       │                                      │
       │  8. Medusa JWT token                 │
       │ <────────────────────────────────────┘

Port Configuration (His & Her Project)

Service	Port	Description
Storefront	3000	Next.js storefront app
SuperTokens Core	3567	SuperTokens database/core service
hisher-auth Backend	4002	SuperTokens backend API with OTP/profile routes
hisher-auth Frontend	4003	SuperTokens demo UI (optional, for testing)
Medusa Backend	9000	Medusa e-commerce API

Note: The hisher-auth frontend (port 4003) is a SuperTokens demo UI showing buttons like "Continue to Store", "Call API", "Logout". It's NOT an admin dashboard - it's designed for authenticated users to test the session. You don't need to run it for production.

Prerequisites

Medusa v2.x
SuperTokens Core running (self-hosted via Docker or managed)
SuperTokens Backend API (hisher-auth) running
Storefront configured to redirect to hisher-auth for login

Installation

1npm install @patiparnne/medusa-supertokens
2# or
3yarn add @patiparnne/medusa-supertokens

Configuration

1. Configure Medusa

Add the plugin to your :

1import { defineConfig } from '@medusajs/framework/utils';
2
3module.exports = defineConfig({
// ... other config
modules: [
  {
    resolve: "@medusajs/medusa/auth",
    options: {
      providers: [
        // SuperTokens Authentication Provider
        {
          resolve: "@patiparnne/medusa-supertokens/providers/supertokens-auth",
          id: "supertokens",
          options: {
            // SuperTokens Core URL (for direct session verification)
            coreUrl: process.env.SUPERTOKENS_CORE_URL || "http://localhost:3567",
            
            // hisher-auth Backend API URL (for profile enrichment)
            apiDomain: process.env.SUPERTOKENS_API_DOMAIN || "http://localhost:4002",
            
            // API base path (default: '/auth')
            apiBasePath: process.env.SUPERTOKENS_API_BASE_PATH || "/auth",
            
            // SuperTokens Core API key (if configured)
            apiKey: process.env.SUPERTOKENS_API_KEY,
            
            // Callback URL for redirects (your storefront)
            callbackUrl: process.env.SUPERTOKENS_CALLBACK_URL || "http://localhost:3000/auth/callback",
            
            // Require email verification (default: false)
            verifyEmail: false,
          },
        },
      ],
    },
  },
],
plugins: [
  // SuperTokens plugin - provides /store/auth/supertokens route for customer creation
  {
    resolve: '@patiparnne/medusa-supertokens',
    options: {},
  },
],
45});

2. Environment Variables

Add these to your file:

1# SuperTokens Configuration
2SUPERTOKENS_CORE_URL=http://localhost:3567
3SUPERTOKENS_API_DOMAIN=http://localhost:4002
4SUPERTOKENS_API_BASE_PATH=/auth
5SUPERTOKENS_API_KEY=your-api-key
6SUPERTOKENS_CALLBACK_URL=http://localhost:3000/auth/callback

Usage

Authentication Flow

User initiates login: Storefront redirects to hisher-auth login page
User authenticates: Via phone OTP, email/password, or social login (LINE, Google)
Session created: SuperTokens creates a session with access token
Token sent to Medusa: Storefront calls with the token
Profile enriched: Plugin calls on hisher-auth to get user data
Customer created/linked: Medusa creates or retrieves the customer
Medusa JWT returned: Storefront receives Medusa JWT for authenticated requests

API Endpoints

Authenticate with session token:

1POST /auth/customer/supertokens
2Content-Type: application/json
3
4{
5  "access_token": "<supertokens-session-access-token>"
6}

Or via Authorization header:

1POST /auth/customer/supertokens
2Authorization: Bearer <supertokens-session-access-token>

Response (success):

1{
2  "token": "<medusa-jwt-token>"
3}

Legacy Profile Integration

On every authentication, the plugin calls on hisher-auth to:

Verify the SuperTokens JWT token
Fetch user info and metadata from SuperTokens
Return any legacy CRM profile data stored in SuperTokens metadata

This ensures:

Real email addresses from legacy CRM are used (instead of generated phone@domain.com)
Customer first_name and last_name are populated
Legacy member_id is preserved for reference

Options Reference

Type	Required	Default	Description
string	Yes	-	SuperTokens Core URL (e.g., http://localhost:3567)
string	Yes	-	hisher-auth Backend API URL (e.g., http://localhost:4002)
string	No		API base path for SuperTokens endpoints
string	No	-	SuperTokens Core API key (for direct Core access)
string	No	-	Redirect URL after login (storefront callback)
boolean	No		Require email verification before allowing auth