Documentation Menu

Installation

Complete guide to deploying OpenAuthster and integrating it into your application.

Architecture Overview

OpenAuthster requires deploying two components in sequence:

  1. OpenAuthster Issuer - The authentication server (Cloudflare Worker)
  2. OpenAuthster WebUI - The management dashboard (Cloudflare Pages)

Once deployed, you integrate the client SDK into your application.

Part 1: Deploy the Issuer

The issuer is the core authentication server. Deploy it first.

Prerequisites

  • Wrangler CLI installed globally
  • Bun.js or Node.js
  • Cloudflare account with Workers and D1 access
# Install Wrangler globally
bun add -g wrangler
# or
npm install -g wrangler

1. Clone the Repository

Clone as a private repository (recommended for production):

git clone https://github.com/shpaw415/OpenAuthSter-issuer.git openauth-issuer
cd openauth-issuer

⚠️ Security: Keep your issuer repository private - it contains sensitive authentication configuration.

2. Install Dependencies

bun install

3. Configure Wrangler

# Rename example config
mv wrangler.example.json wrangler.json
 
# Generate TypeScript types
wrangler types

4. Create D1 Database

wrangler d1 create openauth-db

Copy the database_id and database_name from the output.

5. Update wrangler.json

Edit wrangler.json with your database credentials and environment variables:

{
  "d1_databases": [
    {
      "binding": "AUTH_DB",
      "database_name": "openauth-db",
      "database_id": "your-database-id-here",
      "migrations_dir": "drizzle/migrations",
      "remote": true
    }
  ],
  "vars": {
    "WEBUI_ADMIN_EMAILS": "[email protected]",
    "WEBUI_ORIGIN_URL": "https://admin.yourdomain.com",
    "ISSUER_URL": "https://auth.yourdomain.com"
  }
}

6. Run Database Migrations

wrangler d1 migrations apply AUTH_DB --remote

7. Configure OpenAuth

Edit openauth.config.ts:

// openauth.config.ts
export default async (env: Env) =>
  createExternalGlobalProjectConfig({
    register: {
      fallbackEmailFrom: "[email protected]",
      strategy: {
        email: {
          provider: "custom", // or "resend"
          sendEmailFunction(to, code) {
            console.log(`Send code ${code} to email ${to}`);
          },
        },
      },
    },
  });

8. Deploy to Cloudflare Workers

  1. Create a private GitHub repository and push your code
  2. Go to Cloudflare Dashboard → Workers & Pages
  3. Click "Create application" → "Create Worker"
  4. Connect to your GitHub repository
  5. Cloudflare will deploy using your wrangler.json configuration

Your issuer is now deployed! 🎉

Part 2: Deploy the WebUI

The WebUI allows you to manage projects, themes, and providers.

Prerequisites

  • Issuer deployed from Part 1
  • Same D1 database credentials

1. Clone the Repository

git clone https://github.com/shpaw415/OpenAuthSter-webUI.git openauth-webui
cd openauth-webui

2. Install Dependencies

bun install

3. Configure wrangler.jsonc

# Rename example config
mv wrangler.example.jsonc wrangler.jsonc

Edit wrangler.jsonc with your configuration:

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "name": "openauthster-webui",
  "pages_build_output_dir": ".frame-master/build",
  "compatibility_date": "2025-11-09",
  "d1_databases": [
    {
      "binding": "PROJECT_DB",
      "database_name": "<YOUR_D1_DATABASE_NAME>",
      "database_id": "<YOUR_D1_DATABASE_ID>",
      "migrations_dir": "drizzle/migrations",
      "remote": true,
    },
  ],
  "vars": {
    // Redirect URI for your OpenAuthster-webui instance
    // e.g. https://webui.yourdomain.com/
    "PUBLIC_REDIRECT_URI": "<YOUR_WEBUI_URL>/",
    // Issuer URL for your OpenAuthster-issuer instance
    // e.g. https://auth.yourdomain.com
    "PUBLIC_ISSUER": "<YOUR_ISSUER_URL>",
    // Cloudflare API Token with permissions to manage Workers
    "CLOUDFLARE_API_TOKEN": "<YOUR_CLOUDFLARE_API_TOKEN>",
    // Cloudflare Account ID where your Cloudflare Worker OpenAuthster-issuer instance is deployed
    "CLOUDFLARE_ACCOUNT_ID": "<YOUR_CLOUDFLARE_ACCOUNT_ID>",
    // Cloudflare Zone ID for the domain used for auth endpoints
    // it must match the domain set in CLOUDFLARE_AUTH_ENDPOINT_DOMAIN
    "CLOUDFLARE_AUTH_DOMAIN_ZONE_ID": "<YOUR_CLOUDFLARE_AUTH_DOMAIN_ZONE_ID>",
    // Add your Cloudflare Worker Service name here
    // it's the name given to your Cloudflare Worker that is serving your OpenAuthster-issuer instance
    "CLOUDFLARE_WORKER_SERVICE_NAME": "<YOUR_WORKER_SERVICE_NAME>",
    /* (Optional)
    Add your custom auth endpoint domain here e.g. auth.yourdomain.com.
    it will be used to create auth endpoints for your projects as a suffix.
    you must be the owner of the domain and have it added to your Cloudflare account.
    If not set, PUBLIC_ISSUER will be used as the auth endpoint domain.
    e.g. https://auth.yourdomain.com
    */
    "CLOUDFLARE_AUTH_ENDPOINT_DOMAIN": "<YOUR_AUTH_ENDPOINT_DOMAIN>",
 
    // Do not changes the followings
    "BUN_VERSION": "1.3.4",
    "SKIP_DEPENDENCY_INSTALL": "true",
    "PUBLIC_CLIENT_ID": "openauth_webui",
  },
  "compatibility_flags": ["nodejs_compat"],
}

Note: Use the same D1 database as your issuer.

4. Deploy to Cloudflare Pages

  1. Create a private GitHub repository and push your code
  2. Go to Cloudflare Dashboard → Pages
  3. Click "Create a project" → "Connect to Git"
  4. Select your repository
  5. Configure build settings:
    • Build command: bun install --frozen-lockfile && NODE_ENV=production bun run build
    • Build output directory: .frame-master/build
  6. Add all environment variables from your wrangler.jsonc
  7. Deploy!

Your WebUI is now live! 🎉

Visit your WebUI URL and create your first project.

Part 3: Client SDK

For Local Development

Clone the shared types repository:

git clone https://github.com/shpaw415/OpenAuthSter-shared.git

npm Installation

# Coming soon
npm install openauthster-shared

Related Repositories

Package Exports

The package exposes several entry points you can import from:

Import PathContents
openauthster-sharedTypes, constants, provider registry
openauthster-shared/clientLow-level createClient / createServerClient (raw OpenAuth client with cookies)
openauthster-shared/client/userOpenAuthsterClient class + createOpenAuthsterClient factory (recommended)
openauthster-shared/databaseDrizzle ORM schemas for D1
openauthster-shared/endpointsAPI endpoint type definitions

For most apps you only need openauthster-shared/client/user.

TypeScript

The package ships with full TypeScript types. No @types/* package is needed.

You can provide generic type parameters for your session shapes:

import { createOpenAuthsterClient } from "openauthster-shared/client/user";
 
type PublicData = { displayName: string; theme: "light" | "dark" };
type PrivateData = { internalRole: string };
 
const client = createOpenAuthsterClient<PublicData, PrivateData>({
  clientID: "my_project",
  issuerURI: "https://auth.yourdomain.com",
  redirectURI: "https://myapp.com/",
  copyID: null,
});
 
// client.data.public is typed as PublicData
// client.data.private is typed as PrivateData

Next Steps