Self-Hosting Sigma Auth on Cloudflare Workers

Deploy your own Sigma Auth instance on Cloudflare Workers for complete control, zero recurring costs, and full customization. Sigma Auth is built specifically for Cloudflare Workers and KV storage.

Quick Deploy

Get started instantly with Cloudflare deployment:

Deploy to Cloudflare Workers

Deploy with Wrangler →

Sigma Auth is designed exclusively for Cloudflare Workers, leveraging edge computing and KV storage for optimal performance.

Manual Setup

Prerequisites

Cloudflare account (required)
Wrangler CLI - Cloudflare's deployment tool
Bun or Node.js 18+
Git

1. Clone the Repository

git clone https://github.com/b-open-io/sigma-auth.git
cd sigma-auth

2. Install Dependencies

bun install

3. Configure Environment

# Copy example environment file
cp .env.example .env

# Edit configuration
vim .env

Configure in wrangler.toml:

name = "sigma-auth"
main = "src/index.ts"
compatibility_date = "2024-01-01"

[vars]
ISSUER_URL = "https://auth.yourdomain.com"
SIGMA_API_URL = "https://api.sigmaidentity.com"
BITCOIN_NETWORK = "mainnet"

[[kv_namespaces]]
binding = "AUTH_STORAGE"
id = "your-kv-namespace-id"

[env.production]
routes = [
  { pattern = "auth.yourdomain.com/*", zone_name = "yourdomain.com" }
]

Set secrets via Wrangler:

# Required secret
wrangler secret put JWT_SECRET --env production

# Optional OAuth providers
wrangler secret put GOOGLE_CLIENT_ID --env production
wrangler secret put GOOGLE_CLIENT_SECRET --env production
wrangler secret put GITHUB_CLIENT_ID --env production
wrangler secret put GITHUB_CLIENT_SECRET --env production

4. Generate JWT Secret

# Generate a secure JWT secret
openssl rand -base64 32

# Save this value - you'll add it as a Cloudflare secret

5. Setup Cloudflare KV Storage

# Create KV namespace for auth storage
wrangler kv:namespace create "AUTH_STORAGE"

# Add the namespace ID to wrangler.toml
# [[kv_namespaces]]
# binding = "AUTH_STORAGE"
# id = "your-namespace-id"

# Set JWT secret
wrangler secret put JWT_SECRET

6. Deploy to Cloudflare

# Deploy to production
wrangler deploy --env production

# Or use the npm script
bun run deploy:production

Automated Deployment with GitHub Actions

Set up continuous deployment to automatically deploy your auth server when you push changes to GitHub.

Prerequisites

GitHub repository with your sigma-auth code
Cloudflare API Token with Workers permissions
Cloudflare Account ID from your dashboard

1. Create GitHub Actions Workflow

Create .github/workflows/deploy.yml in your repository:

name: Deploy Sigma Auth Worker

on:
  push:
    branches:
      - main
      - master
  workflow_dispatch:

jobs:
  deploy:
    runs-on: ubuntu-latest
    name: Deploy to Cloudflare Workers
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install dependencies
        run: npm install

      - name: Build
        run: npm run build
        continue-on-error: true

      - name: Deploy to Cloudflare Workers
        uses: cloudflare/wrangler-action@v3
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          environment: production
          wranglerVersion: '3.78.2'
          command: deploy --compatibility-date=2024-09-23 --message="Deploy ${{ github.sha }}"

2. Get Cloudflare Credentials

Get your Account ID:

wrangler whoami
# Copy the Account ID from the output

Create an API Token:
- Go to Cloudflare API Tokens
- Click "Create Token"
- Use "Custom token" template
- Set permissions:
  - Account: Cloudflare Workers:Edit
  - Zone: Zone:Read (for your domain)
- Account Resources: Include your account
- Zone Resources: Include your domain
- Click "Continue to summary" and "Create Token"
- Copy the token (you won't see it again!)

3. Add GitHub Secrets

In your GitHub repository:

Go to Settings → Secrets and variables → Actions
Click "New repository secret"
Add these secrets:
- Name: CLOUDFLARE_ACCOUNT_ID
  Value: Your account ID from step 2.1
- Name: CLOUDFLARE_API_TOKEN
  Value: The API token from step 2.2

4. Test Deployment

Push to your main branch:

git add .github/workflows/deploy.yml
git commit -m "Add GitHub Actions deployment"
git push origin main

Check the Actions tab in GitHub to see your deployment progress
View deployment history in Cloudflare dashboard or with:
```
wrangler deployments list
```

Benefits of Automated Deployment

Git-tracked deployments: Each deployment shows the commit SHA
Automatic rollbacks: Easy to revert to previous versions
CI/CD pipeline: Run tests before deployment
Team collaboration: Anyone with repo access can deploy
Deployment history: Full audit trail of who deployed what

Advanced Configuration

Deploy on Tags Only

To deploy only when you create a release tag:

on:
  push:
    tags:
      - 'v*'

Multiple Environments

Deploy to staging on all pushes, production on tags:

jobs:
  deploy-staging:
    if: github.ref == 'refs/heads/main'
    # ... deployment steps with environment: staging

  deploy-production:
    if: startsWith(github.ref, 'refs/tags/v')
    # ... deployment steps with environment: production

Add Tests Before Deploy

- name: Run tests
  run: npm test

- name: Deploy to Cloudflare Workers
  if: success()
  # ... deployment steps

Cloudflare-Specific Configuration

Custom Domain Setup

Configure your domain in Cloudflare:

Add route in wrangler.toml:

[env.production]
routes = [
  { pattern = "auth.yourdomain.com/*", zone_name = "yourdomain.com" }
]

Deploy with custom route:
```
wrangler deploy --env production
```

Update environment variables:

wrangler secret put ISSUER_URL --env production
# Enter: https://auth.yourdomain.com

OAuth Providers

Enable additional login methods:

# Google OAuth
wrangler secret put GOOGLE_CLIENT_ID --env production
wrangler secret put GOOGLE_CLIENT_SECRET --env production

# GitHub OAuth  
wrangler secret put GITHUB_CLIENT_ID --env production
wrangler secret put GITHUB_CLIENT_SECRET --env production

Stripe Payments

Enable subscription billing:

wrangler secret put STRIPE_SECRET_KEY --env production

Cloudflare Workers Architecture

Sigma Auth is built specifically for Cloudflare Workers:

Why Cloudflare Workers?

Edge Computing:

Sub-10ms latency globally
Automatic scaling to millions of requests
No servers to manage

Built-in Features:

KV storage for sessions and backups
Durable Objects for real-time features
Workers Sites for static assets
Zero cold starts

Resource Limits

Free Tier:

100,000 requests/day
10ms CPU time per request
1GB KV storage

Paid Plans:

Unlimited requests
50ms CPU time per request
Unlimited KV storage

Monitoring & Maintenance

Health Checks

Monitor your instance:

curl https://your-domain.com/health

Log Monitoring

View real-time logs:

# Stream live logs
wrangler tail --env production

# Filter by status
wrangler tail --env production --status error

# Search logs
wrangler tail --env production --search "user@example.com"

Updates

Keep your instance updated:

git pull origin main
bun install
bun run build
bun run deploy

Security Considerations

Key Management

Store JWT keys securely
Rotate keys periodically
Use strong random passwords

Network Security

Always use HTTPS
Configure CORS properly
Enable rate limiting

CORS Configuration

By default, sigma-auth uses a permissive CORS policy (Access-Control-Allow-Origin: *) for ease of development. For production deployments, you should configure specific allowed origins:

1. Add Environment Variable

Update your wrangler.toml or environment configuration:

[vars]
ALLOWED_ORIGINS = "https://yourdomain.com,https://app.yourdomain.com"

For Cloudflare Workers using Wrangler CLI:

wrangler secret put ALLOWED_ORIGINS
# Enter comma-separated list of allowed origins

2. Update Worker Configuration

The sigma-auth service needs to be updated to use the ALLOWED_ORIGINS environment variable. Currently, it uses a wildcard policy. To implement secure CORS:

Origins should be validated against the whitelist
Preflight requests should be handled correctly
Credentials should only be allowed for whitelisted origins

3. Common CORS Configurations

Development + Production:

ALLOWED_ORIGINS="http://localhost:3000,https://sigmaidentity.com,https://www.sigmaidentity.com"

Multiple Subdomains:

ALLOWED_ORIGINS="https://app.example.com,https://admin.example.com,https://api.example.com"

Staging + Production:

ALLOWED_ORIGINS="https://staging.example.com,https://example.com"

4. Testing CORS Configuration

Test your CORS setup:

# Test preflight request
curl -X OPTIONS https://your-auth-domain.com/backup \
  -H "Origin: https://yourdomain.com" \
  -H "Access-Control-Request-Method: POST" \
  -H "Access-Control-Request-Headers: Authorization,Content-Type"

# Should return proper CORS headers

5. Security Best Practices

Never use wildcards (*) in production unless building a public API
Always validate origins on the server side
Use HTTPS only for all allowed origins
Limit exposed headers to only what's necessary
Set appropriate max-age for preflight caching
Monitor CORS errors in your logs for potential attacks

Access Control

Restrict admin access
Monitor authentication logs
Implement fail2ban for repeated failures

Troubleshooting

Common Issues

Build Failures:

# Clear cache and rebuild
rm -rf node_modules
bun install
bun run build

KV Storage Issues:

# Recreate KV namespaces
bun run setup:kv

JWT Token Errors:

# Regenerate JWT keys
bun run setup:secrets

Getting Help

Documentation: Full API Reference
GitHub Issues: Report bugs
Community: GitHub Discussions

Migration from Hosted

Moving from auth.sigmaidentity.com to self-hosted:

Export user data (contact support)
Deploy your instance following this guide
Update client apps to use your domain
Import user data to your KV storage
Test authentication flow thoroughly

Next Steps

Integration Guide - Connect your applications
API Reference - Detailed endpoint documentation
Security Guide - Harden your deployment
Customization - Brand your instance

On this page