Cloudflare Custom Hostnames Skill (SaaS for SaaS)

Design and implement custom hostname solutions for SaaS platforms that allow customers to bring their own domains. Handle SSL certificate provisioning, domain verification, and DNS configuration.

SaaS Custom Hostname Architecture

graph TB
    subgraph "Customer Domain"
        CD[customer.com]
        CNAME[CNAME → proxy.saas.com]
    end
    subgraph "Cloudflare for SaaS"
        CH[Custom Hostname<br/>customer.com]
        SSL[SSL Certificate<br/>Auto-provisioned]
        FO[Fallback Origin<br/>app.saas.com]
    end
    subgraph "SaaS Platform"
        W[Worker<br/>Multi-tenant Router]
        DB[(Database<br/>Tenant Config)]
    end

    CD --> CNAME --> CH
    CH --> SSL --> FO --> W
    W --> DB

Custom Hostname Lifecycle

Stage	Status	Action Required
1. Created	pending	Customer adds CNAME record
2. Verification	pending_validation	DNS TXT record verification
3. SSL Issuance	active (pending SSL)	Certificate provisioning
4. Active	active	Fully operational
5. Renewal	active	Auto-renewal (90 days before expiry)

Implementation Patterns

Pattern 1: Worker-Based Routing

Route requests based on Host header to tenant-specific configuration:

// src/index.ts - Multi-tenant SaaS Worker
import { Hono } from 'hono';

interface Tenant {
  id: string;
  customHostname: string;
  config: Record<string, unknown>;
}

const app = new Hono<{ Bindings: Env }>();

// Middleware: Resolve tenant from hostname
app.use('*', async (c, next) => {
  const hostname = c.req.header('host') || '';

  // Check cache first
  let tenant = await c.env.KV_TENANTS.get<Tenant>(`host:${hostname}`, 'json');

  if (!tenant) {
    // Query database for tenant config
    const result = await c.env.DB.prepare(
      'SELECT * FROM tenants WHERE custom_hostname = ? OR hostname = ?'
    ).bind(hostname, hostname).first<Tenant>();

    if (result) {
      tenant = result;
      // Cache for 5 minutes
      await c.env.KV_TENANTS.put(`host:${hostname}`, JSON.stringify(tenant), {
        expirationTtl: 300
      });
    }
  }

  if (!tenant) {
    return c.text('Unknown domain', 404);
  }

  c.set('tenant', tenant);
  await next();
});

// Tenant-aware routes
app.get('/', (c) => {
  const tenant = c.get('tenant') as Tenant;
  return c.json({ tenant: tenant.id, message: 'Welcome!' });
});

export default app;

Pattern 2: Custom Hostname API Integration

// api/hostnames.ts - Custom hostname management
interface CreateHostnameRequest {
  tenantId: string;
  hostname: string;
}

export async function createCustomHostname(
  env: Env,
  request: CreateHostnameRequest
): Promise<CustomHostnameResult> {
  const { tenantId, hostname } = request;

  // 1. Create custom hostname via Cloudflare API
  const response = await fetch(
    `https://api.cloudflare.com/client/v4/zones/${env.ZONE_ID}/custom_hostnames`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${env.CF_API_TOKEN}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        hostname,
        ssl: {
          method: 'http',  // or 'cname', 'txt', 'email'
          type: 'dv',      // Domain Validation
          settings: {
            http2: 'on',
            min_tls_version: '1.2',
            tls_1_3: 'on',
          },
        },
        custom_metadata: {
          tenant_id: tenantId,
        },
      }),
    }
  );

  const result = await response.json();

  if (!result.success) {
    throw new Error(result.errors[0]?.message || 'Failed to create hostname');
  }

  // 2. Store in database
  await env.DB.prepare(
    `INSERT INTO custom_hostnames (id, tenant_id, hostname, status, cf_id)
     VALUES (?, ?, ?, ?, ?)`
  ).bind(
    crypto.randomUUID(),
    tenantId,
    hostname,
    'pending',
    result.result.id
  ).run();

  // 3. Return verification instructions
  return {
    id: result.result.id,
    hostname,
    status: result.result.status,
    verification: {
      type: result.result.ssl.method,
      // For HTTP validation
      http_url: result.result.ssl.http_url,
      http_body: result.result.ssl.http_body,
      // For CNAME/TXT validation
      cname_target: result.result.ssl.cname_target,
      txt_name: result.result.ssl.txt_name,
      txt_value: result.result.ssl.txt_value,
    },
    instructions: generateInstructions(result.result),
  };
}

function generateInstructions(hostname: any): string {
  return `
## Setup Instructions for ${hostname.hostname}

### Step 1: Add DNS Record
Add a CNAME record pointing to your SaaS proxy:

| Type  | Name                | Target                |
|-------|---------------------|----------------------|
| CNAME | ${hostname.hostname} | proxy.your-saas.com |

### Step 2: Verify Ownership (if required)
${hostname.ssl.method === 'txt' ? `
Add this TXT record:
| Type | Name | Value |
|------|------|-------|
| TXT  | ${hostname.ssl.txt_name} | ${hostname.ssl.txt_value} |
` : ''}

### Step 3: Wait for SSL
SSL certificate will be issued automatically once DNS propagates (usually 5-15 minutes).

You can check status at: /api/hostnames/${hostname.id}/status
  `;
}

Pattern 3: Hostname Status Webhook

// api/webhooks/hostname-status.ts
export async function handleHostnameWebhook(
  request: Request,
  env: Env
): Promise<Response> {
  const payload = await request.json();

  // Cloudflare webhook payload
  const { data } = payload;
  const { hostname, status, ssl } = data;

  // Update database
  await env.DB.prepare(
    `UPDATE custom_hostnames SET status = ?, ssl_status = ?, updated_at = ?
     WHERE hostname = ?`
  ).bind(status, ssl?.status, new Date().toISOString(), hostname).run();

  // Clear cache
  await env.KV_TENANTS.delete(`host:${hostname}`);

  // Notify tenant if status changed to active
  if (status === 'active' && ssl?.status === 'active') {
    await notifyTenant(env, hostname, 'Your custom domain is now active!');
  }

  return new Response('OK');
}

SSL Certificate Options

Validation Methods

Method	Description	Best For
http	HTTP file validation	Most automated; works behind proxies
cname	CNAME delegation	When customer controls DNS
txt	TXT record validation	One-time verification
email	Domain admin email	Legacy; not recommended

SSL Types

Type	Certificate Authority	Cost	Use Case
dv	Let's Encrypt / Google Trust	Free	Standard SaaS
ev	DigiCert	$$$	Enterprise (rare)

Recommended SSL Configuration

{
  "ssl": {
    "method": "http",
    "type": "dv",
    "settings": {
      "http2": "on",
      "min_tls_version": "1.2",
      "tls_1_3": "on",
      "early_hints": "on"
    },
    "bundle_method": "ubiquitous",
    "wildcard": false
  }
}

Troubleshooting Guide

Common Issues

Issue	Cause	Fix
pending forever	DNS not configured	Verify CNAME record exists
pending_validation	TXT/HTTP validation failing	Check validation path accessibility
SSL errors	CAA records blocking	Add 0 issue "letsencrypt.org"
522 errors	Origin not reachable	Check fallback origin configuration
403 Forbidden	Origin hostname mismatch	Set Host header override

Debugging Workflow

// Check hostname status via MCP
mcp__cloudflare-bindings__custom_hostname_get({
  zone_id: "...",
  hostname_id: "..."
})

// List all custom hostnames
mcp__cloudflare-bindings__custom_hostnames_list({
  zone_id: "..."
})

CAA Record Requirements

If customer has CAA records, they need:

0 issue "letsencrypt.org"
0 issue "pki.goog"
0 issue "digicert.com"
0 issuewild "letsencrypt.org"

Database Schema

-- D1 schema for custom hostnames
CREATE TABLE tenants (
  id TEXT PRIMARY KEY,
  name TEXT NOT NULL,
  hostname TEXT NOT NULL,  -- Default hostname
  custom_hostname TEXT,    -- Customer's domain
  plan TEXT DEFAULT 'free',
  created_at TEXT DEFAULT (datetime('now'))
);

CREATE TABLE custom_hostnames (
  id TEXT PRIMARY KEY,
  tenant_id TEXT NOT NULL,
  hostname TEXT NOT NULL UNIQUE,
  status TEXT DEFAULT 'pending',
  ssl_status TEXT DEFAULT 'pending',
  cf_id TEXT,  -- Cloudflare custom hostname ID
  verified_at TEXT,
  expires_at TEXT,
  created_at TEXT DEFAULT (datetime('now')),
  updated_at TEXT,
  FOREIGN KEY (tenant_id) REFERENCES tenants(id)
);

CREATE INDEX idx_hostnames_tenant ON custom_hostnames(tenant_id);
CREATE INDEX idx_hostnames_hostname ON custom_hostnames(hostname);
CREATE INDEX idx_hostnames_status ON custom_hostnames(status);

Wrangler Configuration

{
  "name": "saas-platform",
  "main": "src/index.ts",
  "compatibility_date": "2025-01-01",
  "compatibility_flags": ["nodejs_compat_v2"],

  "d1_databases": [
    { "binding": "DB", "database_name": "saas-db", "database_id": "..." }
  ],
  "kv_namespaces": [
    { "binding": "KV_TENANTS", "id": "..." }
  ],

  "vars": {
    "ZONE_ID": "your-zone-id"
  },

  // Fallback origin for custom hostnames
  "routes": [
    { "pattern": "app.your-saas.com/*", "zone_name": "your-saas.com" }
  ]
}

Cost Considerations

Feature	Cost	Included With
Custom Hostnames	$2/hostname/month	SSL for SaaS
Wildcard Hostnames	$2/hostname/month	SSL for SaaS
SSL Certificates	Free (DV)	All plans
SSL for SaaS Plan	$200/month base	100 hostnames included
Additional Hostnames	$0.10/hostname/month	After included quota

Cost Optimization Tips

• Batch hostname creation: Create during off-peak hours
• Use wildcards: *.customer.example.com for subdomains
• Monitor usage: Track active vs inactive hostnames
• Clean up: Remove hostnames for churned customers
• Consider enterprise: 10K+ hostnames? Contact CF sales

Security Considerations

• Hostname takeover: Validate customer owns domain before creating
• Certificate transparency: Monitor CT logs for unauthorized certs
• Origin protection: Only allow traffic from Cloudflare IPs
• Tenant isolation: Ensure hostname-to-tenant mapping is secure
• Rate limiting: Limit hostname creation per tenant

Output Format

# Custom Hostname Report

**Tenant**: [Tenant Name]
**Total Hostnames**: X

## Active Hostnames

| Hostname | SSL Status | Expires | Traffic (30d) |
|----------|------------|---------|---------------|
| app.customer.com | Active | 2025-03-15 | 1.2M requests |

## Pending Hostnames

| Hostname | Status | Action Required |
|----------|--------|-----------------|
| new.customer.com | pending_validation | Add TXT record |

## Issues Detected

### [CH001] Hostname approaching SSL expiry
- **Hostname**: old.customer.com
- **Expires**: 2025-01-10
- **Fix**: Renew or remove if unused

Tips

• Wildcard support: Use *.example.com for unlimited subdomains
• Fallback handling: Always have a catch-all route for unknown hostnames
• Status polling: Implement webhook or poll every 30s during setup
• Customer communication: Send email when hostname becomes active
• Monitoring: Track hostname verification success rates
• API token scope: Use minimal permissions (Zone:Custom Hostnames:Edit)