# SuperTokens — Open Source Auth0 Alternative

> SuperTokens is an open-source authentication solution with email/password, passwordless, social login, session management, and MFA. Drop-in UI components for React, Vue, and Angular.

## Install

Save as a script file and run:

## Quick Use

```bash
# Self-host SuperTokens core
docker run -d --name supertokens -p 3567:3567 registry.supertokens.io/supertokens/supertokens-postgresql

# Then add to your app
npx create-supertokens-app@latest
```

## Intro

**SuperTokens** is an open-source authentication solution designed as an alternative to Auth0, Firebase Auth, and AWS Cognito. It provides pre-built login UI components, session management, and backend SDKs — making it fast to integrate while giving you full control over the user data stored in your own database.

With 15K+ GitHub stars, SuperTokens focuses on developer experience with drop-in React/Vue/Angular components that handle the entire auth flow, while the core service runs as a self-hosted Docker container.

## What SuperTokens Does

- **Email/Password**: Classic login with strength validation and account verification
- **Passwordless**: Magic link and OTP-based authentication via email or phone
- **Social Login**: Google, GitHub, Apple, Facebook, Twitter, and custom OAuth providers
- **Multi-Factor Auth**: TOTP-based second factor with recovery codes
- **Session Management**: Secure, rotating refresh tokens with anti-CSRF protection
- **User Roles & Permissions**: RBAC with custom claims in JWT tokens
- **Pre-built UI**: Drop-in React, Vue, and Angular components for login/signup flows
- **Multi-tenancy**: Per-tenant login methods, branding, and user pools
- **Account Linking**: Connect multiple auth methods to a single user account

## Architecture

```
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  Frontend    │────▶│  Your Backend│────▶│  SuperTokens │
│  (React UI)  │     │  (Node/Python│     │  Core (Java) │
│  SuperTokens │     │  /Go SDK)    │     │              │
│  Components  │     └──────────────┘     └──────┬───────┘
└──────────────┘                                 │
                                          ┌──────┴───────┐
                                          │  PostgreSQL /│
                                          │  MySQL       │
                                          └──────────────┘
```

Unlike Keycloak (redirect-based), SuperTokens embeds directly into your app — users never leave your domain.

## Integration (Next.js Example)

### 1. Install

```bash
npm install supertokens-auth-react supertokens-node
```

### 2. Frontend Config

```typescript
// config/frontend.ts
import SuperTokens from "supertokens-auth-react";
import EmailPassword from "supertokens-auth-react/recipe/emailpassword";
import ThirdParty from "supertokens-auth-react/recipe/thirdparty";
import Session from "supertokens-auth-react/recipe/session";

SuperTokens.init({
  appInfo: {
    appName: "My App",
    apiDomain: "http://localhost:3000",
    websiteDomain: "http://localhost:3000",
  },
  recipeList: [
    EmailPassword.init(),
    ThirdParty.init({
      signInAndUpFeature: {
        providers: [
          ThirdParty.Google.init(),
          ThirdParty.Github.init(),
          ThirdParty.Apple.init(),
        ],
      },
    }),
    Session.init(),
  ],
});
```

### 3. Backend Config

```typescript
// config/backend.ts
import supertokens from "supertokens-node";
import EmailPassword from "supertokens-node/recipe/emailpassword";
import ThirdParty from "supertokens-node/recipe/thirdparty";
import Session from "supertokens-node/recipe/session";

supertokens.init({
  supertokens: {
    connectionURI: "http://localhost:3567", // SuperTokens core
  },
  appInfo: {
    appName: "My App",
    apiDomain: "http://localhost:3000",
    websiteDomain: "http://localhost:3000",
  },
  recipeList: [
    EmailPassword.init(),
    ThirdParty.init({
      signInAndUpFeature: {
        providers: [
          { config: { thirdPartyId: "google", clients: [{ clientId: "...", clientSecret: "..." }] } },
          { config: { thirdPartyId: "github", clients: [{ clientId: "...", clientSecret: "..." }] } },
        ],
      },
    }),
    Session.init(),
  ],
});
```

### 4. Protect Routes

```typescript
// Protected API route
import { verifySession } from "supertokens-node/recipe/session/framework/express";

app.get("/api/user", verifySession(), (req, res) => {
  const userId = req.session.getUserId();
  res.json({ userId });
});
```

## Self-Hosting

### Docker Compose

```yaml
services:
  supertokens:
    image: registry.supertokens.io/supertokens/supertokens-postgresql
    ports:
      - "3567:3567"
    environment:
      POSTGRESQL_CONNECTION_URI: "postgresql://supertokens:supertokens@db:5432/supertokens"
    depends_on:
      - db

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: supertokens
      POSTGRES_PASSWORD: supertokens
      POSTGRES_DB: supertokens
    volumes:
      - pg-data:/var/lib/postgresql/data

volumes:
  pg-data:
```

## SuperTokens vs Alternatives

| Feature | SuperTokens | Auth0 | Clerk | Keycloak |
|---------|------------|-------|-------|----------|
| Open Source | Yes | No | No | Yes |
| Integration style | Embedded (no redirect) | Redirect | Embedded | Redirect |
| Pre-built UI | React/Vue/Angular | Universal Login | React | Login page |
| Self-hosted | Yes | No | No | Yes |
| MFA | TOTP | Yes | Yes | Yes |
| Multi-tenancy | Yes | Yes | No | Realms |
| Session management | Built-in | Built-in | Built-in | Built-in |
| Pricing | Free (self-host) | Free + paid | Per MAU | Free |

## 常见问题

**Q: SuperTokens 和 Keycloak 的区别？**
A: SuperTokens 嵌入你的应用（用户不会被重定向到外部登录页），提供 React/Vue 组件直接集成。Keycloak 使用重定向模式（跳转到 Keycloak 登录页再回跳）。SuperTokens 更适合需要定制登录界面的 SaaS 应用，Keycloak 更适合企业 SSO 场景。

**Q: 用户数据存储在哪里？**
A: 存储在你自己的 PostgreSQL 或 MySQL 数据库中。SuperTokens 不会把用户数据发送到任何外部服务器。

**Q: 支持哪些后端框架？**
A: 官方 SDK 支持 Node.js（Express、Next.js、NestJS）、Python（Flask、Django、FastAPI）和 Go。社区也有 PHP 和 Rust 的 SDK。

## 来源与致谢

- GitHub: [supertokens/supertokens-core](https://github.com/supertokens/supertokens-core) — 15K+ ⭐
- 官网: [supertokens.com](https://supertokens.com)

---
Source: https://tokrepo.com/en/workflows/2da136b5-34c8-11f1-9bc6-00163e2b0d79
Author: Script Depot