How to Build Tenant Routing and Subdomain Resolution in Cloud Architecture

When building a modern cloud software application, one of your earliest architectural milestones is giving each customer an isolated workspace experience. Whether an enterprise accesses your platform via a branded subdomain like acme.yourproduct.com or maps their own corporate vanity domain like portal.acme.com, your infrastructure must parse the incoming HTTP request, identify the associated customer tenant, and securely propagate that tenant context to backend handlers and database transactions.

If you handle tenant routing incorrectly, you risk severe vulnerabilities: HTTP Host Header Injection, cache poisoning, subdomain takeover, or routing cross-tenant traffic to the wrong database schema. This comprehensive guide walks you through building an industrial-grade tenant routing and subdomain resolution pipeline, from reverse-proxy TLS termination down to context-bound database queries.

Understanding the Three Tenant Routing Models

cloud software architectures typically support three different URL routing schemes:

1. Subdomain-per-Tenant (acme.app.io): Each registered organization receives a unique subdomain under your primary domain. This is the gold standard for usability, session separation, and cookie security.
2. Custom Vanity Domains (portal.customer.com): High-paying enterprise customers map their corporate DNS to your application using a CNAME record, providing a white-labeled experience.
3. Path-Based Multi-Tenancy (app.io/org/acme/): All tenants share the root domain, with tenant slugs placed in the URL path. While easier to configure in DNS, path-based routing shares browser cookies across all organizations, complicating SSO and increasing cross-site scripting (XSS) blast radius.

The recommended architectural approach is supporting subdomains as the default, while allowing an opt-in upgrade to custom vanity domains for enterprise contracts.

TLS Termination and Certificate Provisioning

Routing subdomains begins at the network perimeter. Your edge proxy must terminate TLS connections securely before forwarding traffic to your backend application cluster.

1. Wildcard Certificates for Subdomains

For your primary platform subdomains (*.yourproduct.com), you should provision a wildcard TLS certificate using the ACME protocol via Let's Encrypt or your cloud provider. Wildcard certificates require a DNS-01 challenge, where your automation system creates a temporary _acme-challenge.yourproduct.com TXT record in your DNS provider.

Once issued, the single wildcard certificate covers every current and future customer subdomain without runtime latency or certificate issuance delays.

2. Dynamic SNI for Custom Customer Domains

Custom vanity domains (app.customer.com) cannot be included in your wildcard certificate because you do not own the customer's root domain. When a customer points a CNAME record to your ingress router (custom.yourproduct.io), your edge proxy (such as Envoy, Caddy, or edge ingress controllers) must:

1. Intercept the incoming TLS Server Name Indication (SNI) handshake.
2. Query your routing database to verify that app.customer.com is an authorized, active tenant domain.
3. Dynamically obtain and cache a single-domain certificate via an ACME HTTP-01 challenge.

[ Browser Client ]
        |
   (TLS SNI: portal.customer.com)
        v
[ Edge Proxy (Envoy / Caddy) ]
        |
        +---> [ Verify Domain in Tenant DB ]
        |
        +---> [ Serve Cached Dynamic TLS Cert ]
        |
(X-Tenant-ID: tnt_8819 + X-Forwarded-Host)
        v
[ Application Core ]

Designing the Tenant Resolution Middleware

Once TLS is terminated, the request hits your origin web server. Your application must extract the host, sanitize the input, look up the tenant in a fast cache, and store the validated tenant entity inside the request context.

Here is a battle-tested middleware implementation:

package middleware

import (
	"context"
	"errors"
	"net/http"
	"strings"
	"sync"
	"time"
)

type contextKey string

const TenantContextKey contextKey = "current_tenant"

type Tenant struct {
	ID        string    `json:"id"`
	Slug      string    `json:"slug"`
	Name      string    `json:"name"`
	Tier      string    `json:"tier"`
	Status    string    `json:"status"` // "active", "suspended"
	CreatedAt time.Time `json:"createdAt"`
}

type TenantStore interface {
	FindByHostname(ctx context.Context, host string) (*Tenant, error)
}

// TenantResolver handles domain normalization and caching
type TenantResolver struct {
	store       TenantStore
	baseDomain  string
	cache       sync.Map // In-memory fast cache (hostname -> *cachedTenant)
	cacheTTL    time.Duration
}

type cachedTenant struct {
	tenant    *Tenant
	expiresAt time.Time
}

func NewTenantResolver(store TenantStore, baseDomain string, ttl time.Duration) *TenantResolver {
	return &TenantResolver{
		store:      store,
		baseDomain: strings.ToLower(baseDomain),
		cacheTTL:   ttl,
	}
}

func (tr *TenantResolver) Middleware(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		// 1. Extract and sanitize Host header
		host := strings.ToLower(r.Host)
		if idx := strings.Index(host, ":"); idx != -1 {
			host = host[:idx] // Strip port number if present
		}

		// 2. Bypass public marketing endpoints
		if host == tr.baseDomain || host == "www."+tr.baseDomain {
			next.ServeHTTP(w, r)
			return
		}

		// 3. Resolve tenant entity with caching
		tenant, err := tr.resolve(r.Context(), host)
		if err != nil {
			http.Error(w, "Workspace not found or domain unmapped", http.StatusNotFound)
			return
		}

		if tenant.Status != "active" {
			http.Error(w, "Workspace is suspended or inactive", http.StatusForbidden)
			return
		}

		// 4. Inject tenant into Request Context
		ctx := context.WithValue(r.Context(), TenantContextKey, tenant)
		next.ServeHTTP(w, r.WithContext(ctx))
	})
}

func (tr *TenantResolver) resolve(ctx context.Context, host string) (*Tenant, error) {
	now := time.Now()

	// Check L1 sync.Map cache
	if val, ok := tr.cache.Load(host); ok {
		cached := val.(*cachedTenant)
		if now.Before(cached.expiresAt) {
			return cached.tenant, nil
		}
		tr.cache.Delete(host)
	}

	// Query authoritative store (DB / Redis)
	tenant, err := tr.store.FindByHostname(ctx, host)
	if err != nil {
		return nil, err
	}

	tr.cache.Store(host, &cachedTenant{
		tenant:    tenant,
		expiresAt: now.Add(tr.cacheTTL),
	})

	return tenant, nil
}

Preventing Cache Stampedes with Singleflight

During peak morning hours or deployment restarts, hundreds of concurrent requests for the same tenant domain might hit your web servers simultaneously when your local cache is cold. If you query your relational database for every concurrent cache miss, your connection pool will spike, leading to database saturation.

To solve this, wrap your tenant database queries with the standard singleflight deduplication pattern:

import "golang.org/x/sync/singleflight"

type SafeTenantStore struct {
	db    Database
	group singleflight.Group
}

func (s *SafeTenantStore) FindByHostname(ctx context.Context, host string) (*Tenant, error) {
	// Deduplicate concurrent requests for the identical host
	v, err, _ := s.group.Do(host, func() (interface{}, error) {
		return s.db.LookupTenantByDomain(ctx, host)
	})

	if err != nil {
		return nil, err
	}
	return v.(*Tenant), nil
}

singleflight ensures that if 500 requests arrive for acme.app.io at the same microsecond, only one SQL query executes against your database. The other 499 requests block and share the single result, protecting your database from sudden traffic spikes.

Security Considerations: Host Header Poisoning and Hijacking

Tenant routing introduces distinct security risks that must be defended against in code:

Practical Next Steps

1. Configure Wildcard DNS: Set an A or CNAME record for *.yourdomain.io pointing to your ingress load balancer.
2. Deploy Tenant Resolution Middleware: Integrate the middleware above into your HTTP router pipeline, ensuring it executes before session authentication and database transactions.
3. Establish Subdomain Blacklists: Prevent users from registering administrative or system subdomains (api, admin, billing, status, mail, auth, support).
4. Enforce Context Type Safety: Use an internal helper function (e.g. tenant.FromContext(ctx)) rather than raw string keys to retrieve the tenant model in downstream handlers.