Quick Start

Get IDPFlare up and running in less than 5 minutes.

Prerequisites

Node.js 18 or later
A Cloudflare account (free tier works fine)
Wrangler CLI installed (npm install -g wrangler)

Installation

# Clone the repository
git clone https://github.com/yourusername/idpflare
cd idpflare

# Install dependencies
npm install

# Login to Cloudflare
wrangler login

# Create D1 database
wrangler d1 create idpflare-db

# Create KV namespaces
wrangler kv:namespace create SESSIONS
wrangler kv:namespace create RATE_LIMIT

# Generate JWT keys
npm run generate:keys

# Run migrations
npm run db:migrate

# Deploy
npm run deploy

Note: After creating resources, update the IDs in wrangler.toml and add secrets to .dev.vars for local development.

Configuration

IDPFlare is configured via wrangler.toml and secrets. Everything is customizable without touching code.

Branding

[vars]
BRAND_NAME = "MyApp"
BRAND_TAGLINE = "Secure authentication for everyone"
BRAND_LOGO_URL = "https://example.com/logo.png"
BRAND_FAVICON_URL = "https://example.com/favicon.ico"

Colors & Theme

THEME_PRIMARY_COLOR = "#6366f1"
THEME_SECONDARY_COLOR = "#4f46e5"
THEME_ACCENT_COLOR = "#f59e0b"
THEME_BACKGROUND_COLOR = "#0f172a"
THEME_SURFACE_COLOR = "#1e293b"

Security Settings

PASSWORD_MIN_LENGTH = "12"
REQUIRE_EMAIL_VERIFICATION = "true"
ALLOW_REGISTRATION = "true"
RATE_LIMIT_LOGIN_ATTEMPTS = "5"
RATE_LIMIT_WINDOW_SECONDS = "900"

OAuth 2.0 / OpenID Connect

IDPFlare implements OAuth 2.0 and OpenID Connect protocols with full support for modern flows.

Supported Grant Types

Authorization Code (with PKCE)
Refresh Token

Discovery Endpoint

GET https://your-domain.com/.well-known/openid-configuration

Example Integration

// Using oidc-client-ts
import { UserManager } from 'oidc-client-ts';

const userManager = new UserManager({
  authority: 'https://your-domain.com',
  client_id: 'your-client-id',
  redirect_uri: 'https://yourapp.com/callback',
  response_type: 'code',
  scope: 'openid profile email',
});

// Start login
await userManager.signinRedirect();

Admin Dashboard

IDPFlare includes a full-featured admin dashboard for managing users, API keys, and viewing system settings.

Setting Up Admin Access

First, set a user as admin in the database:

# Run database migration for roles
npm run db:migrate

# Set user as admin
wrangler d1 execute idpflare-db --local --command \
  "UPDATE users SET roles = 'admin' WHERE email = '[email protected]'"

Accessing the Admin Panel

Navigate to /admin on your deployed instance. You'll need to log in with an admin user.

Features

Dashboard: View user statistics and system health
User Management: Create, edit, and delete users
API Keys: Generate and manage API keys with scoped permissions
Settings: View current system configuration
Help: Access documentation and API examples

Management API

Programmatically manage users and configuration via RESTful APIs with full OpenAPI documentation.

Base URL

https://your-domain.com/api/v1

API Documentation

Interactive Swagger UI available at:

https://your-domain.com/api/v1/docs

Authentication

The Management API supports two authentication methods:

1. API Key (Recommended for Backends)

Create an API key through the admin dashboard, then use it in requests:

curl https://your-domain.com/api/v1/users \
  -H "Authorization: Bearer idk_your_api_key_here"

2. Admin Token (JWT)

Use a JWT access token from a user with admin role:

curl https://your-domain.com/api/v1/users \
  -H "Authorization: Bearer your_jwt_token"

User Management

List Users

GET /api/v1/users?limit=50&search=john&role=admin

Create User

POST /api/v1/users
Content-Type: application/json

{
  "email": "[email protected]",
  "password": "SecurePassword123!",
  "given_name": "John",
  "family_name": "Doe",
  "roles": ["user"],
  "email_verified": true,
  "is_active": true
}

Update User

PATCH /api/v1/users/{userId}
Content-Type: application/json

{
  "roles": ["user", "admin"],
  "is_active": true
}

Delete User

DELETE /api/v1/users/{userId}

Deployment

Deploying to Cloudflare Workers

# Deploy to production
npm run deploy

# Deploy with specific environment
wrangler deploy --env production

Environment Variables

Set secrets using Wrangler:

# JWT Keys
wrangler secret put JWT_PRIVATE_KEY
wrangler secret put JWT_PUBLIC_KEY
wrangler secret put ENCRYPTION_KEY

# Email Provider (choose one)
wrangler secret put RESEND_API_KEY
# or
wrangler secret put SENDGRID_API_KEY

# Social Login (optional)
wrangler secret put GOOGLE_CLIENT_ID
wrangler secret put GOOGLE_CLIENT_SECRET

Custom Domain

Add a custom domain through the Cloudflare dashboard:

Go to Workers & Pages
Select your IDPFlare worker
Go to Settings → Triggers
Click "Add Custom Domain"
Enter your domain (e.g., auth.yourdomain.com)
Update BASE_URL in wrangler.toml

Tip: Use a subdomain like auth.yourdomain.com for better organization.