Skip to content
Swingback, home

BlogEngineering

Custom domains for SaaS customers: DNS, TLS and routing

Let customers serve your SaaS on their own domain: a TXT record proves control, then Caddy's on-demand TLS or a Gateway API ListenerSet serves it over HTTPS.

By Elie Baier · · Updated · 5 min read

Before customers can serve your SaaS on a domain of their own, you need proof that they control the name, a certificate for it, and a route that sends its requests to the right tenant. Ask for a TXT record to prove control, issue a certificate only for a name that passed, and route by the request's host. On one server, Caddy's on-demand TLS gets each certificate once an endpoint of yours approves the name. On Kubernetes, the Gateway API now has a clean way to serve each name with its own certificate: three objects per domain. Either way, your application finds the tenant by the host. Here are both, as Swingback runs its customers' feedback portals.

What the customer does#

They choose a subdomain, such as feedback.example.com, and publish two records at their DNS provider:

Text
_swingback-verify.feedback.example.com.  TXT    "swingback-verify=k3jx7…"
feedback.example.com.                    CNAME  <the target the dashboard shows>.

The TXT record proves the name is theirs: its value is a random token made for this domain alone. The CNAME points the name at the service. It must be a subdomain: an apex like example.com can't take a CNAME, so Swingback refuses one. Where a DNS provider flattens the CNAME into addresses, A and AAAA records whose addresses are all the target's pass too.

1. Prove control, and keep proving it#

A check looks up both records, every minute for the first hour, then less often for a week. Two details matter more than the lookup itself.

A resolver failure proves nothing. A timeout or a SERVFAIL says nothing about the records, so it never counts against the domain. The check just runs again later.

Typing a name must block nobody. If the first workspace to enter feedback.example.com owned it, anyone could squat a customer's name before they sign up. So unverified claims can coexist, and only verified ones are unique:

SQL
CREATE UNIQUE INDEX custom_domains_verified_idx ON custom_domains (hostname) WHERE verified_at IS NOT NULL;

Whoever proves control first holds the name. When two workspaces verify at the same moment, the index lets one through, and the other's check fails as "taken".

The proof also has to last. Domains expire and get registered again by someone else, who then controls where that name points. An active domain is checked every day, and three failures in a row stop it: the portal goes back to its usual address, and the name is free again.

2. A certificate, only for names that passed#

Anyone can point a name at your server. If your edge asks for a certificate for every name it receives, strangers fill your disk and your certificate authority's rate limits with names you never agreed to serve. So the edge asks your application first.

On one server: Caddy's on-demand TLS#

Caddy can get a certificate during a name's first TLS handshake. Its docs insist on an ask endpoint that approves each name first:

Caddyfile
{
	on_demand_tls {
		ask http://api:8080/v1/portal/tls-ask
	}
}

# Every name not listed elsewhere: the customers' own domains.
https:// {
	tls {
		on_demand
	}
	reverse_proxy web:3000
}

Caddy calls the endpoint with ?domain=feedback.example.com. It answers 200 for a name a portal serves and 404 for anything else, with one indexed read. Keep it that cheap: it runs before the handshake can finish.

Your own names are a different case. The portals' default addresses live under one wildcard, which Caddy gets by a DNS-01 challenge. A certificate for each of them would run into Let's Encrypt's limit of 50 new certificates per registered domain every 7 days, since they all share yours. Customers' domains are each their own registered domain, so on-demand certificates suit them.

On Kubernetes: three objects per domain#

On a cluster, the gateway terminates TLS, and its listeners are part of the Gateway object. You could add one listener per customer, but a Gateway takes at most 64, and an object that your deployment applies and your application patches gets fought over. One certificate for every domain is worse: each customer's name shows in everyone else's certificate, and a single name that stops answering blocks every renewal.

Gateway API v1.5 made the answer standard: a ListenerSet gives a Gateway a listener from outside its own object. The Gateway opts in once:

YAML
# The Gateway's spec: it takes the ListenerSets of its own namespace.
allowedListeners:
  namespaces:
    from: Same

Then each verified domain is three objects of one name, applied by the worker:

YAML
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: domain-feedback-example-com-1f2e3d4c5b
spec:
  dnsNames: [feedback.example.com]
  secretName: domain-feedback-example-com-1f2e3d4c5b
  issuerRef: { group: cert-manager.io, kind: ClusterIssuer, name: letsencrypt }
---
apiVersion: gateway.networking.k8s.io/v1
kind: ListenerSet
metadata:
  name: domain-feedback-example-com-1f2e3d4c5b
spec:
  parentRef: { group: gateway.networking.k8s.io, kind: Gateway, name: main }
  listeners:
    - name: https
      hostname: feedback.example.com
      port: 443
      protocol: HTTPS
      tls:
        mode: Terminate
        certificateRefs: [{ kind: Secret, name: domain-feedback-example-com-1f2e3d4c5b }]
      allowedRoutes: { namespaces: { from: Same } }
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: domain-feedback-example-com-1f2e3d4c5b
spec:
  hostnames: [feedback.example.com]
  parentRefs:
    - {
        group: gateway.networking.k8s.io,
        kind: ListenerSet,
        name: domain-feedback-example-com-1f2e3d4c5b,
        sectionName: https,
      }
  rules:
    - backendRefs: [{ name: web, port: 3000 }]

The name has a listener of its own with its own certificate, and the route attaches to that listener alone. The Gateway's own HTTPS listener has no hostname, so it catches the default addresses.

The order matters. The worker applies the certificate first and the other two once it is issued, so the gateway never gets a listener whose certificate is missing. The domain is active, and becomes the portal's address, when the gateway reports that it serves the listener and its route.

The certificate is issued by an HTTP-01 challenge: Let's Encrypt asks for a file at the name itself, which reaches the gateway because the customer's record points there. A challenge nobody answers doesn't fail, it waits. So a domain that isn't ready a day after it was verified is marked as failed, and its owner can ask again.

The least rights that work#

Only the worker talks to the cluster, and its Role is three kinds and three verbs:

YAML
rules:
  - apiGroups: [cert-manager.io]
    resources: [certificates]
    verbs: [create, patch, delete]
  - apiGroups: [gateway.networking.k8s.io]
    resources: [listenersets, httproutes]
    verbs: [create, patch, delete]

It reads nothing, lists nothing, and has no access to Secrets. A server-side apply answers with the object and its status, which is all it needs to read back. The certificate's private key is cert-manager's to write and the gateway's to read. It is deleted with its certificate, because cert-manager owns it (--enable-certificate-owner-ref). The alternative was the right to delete Secrets, which RBAC can't limit to names not known in advance. No other pod of the application mounts a service account token.

3. Route by host#

With TLS done, the application reads the request's host and finds the workspace: by its slug's address, by an old slug's (after a rename), or by its active domain. A page asked for on any address other than the canonical one gets a 308 redirect to it, with the same path; other requests go on, since a sign-in may have started on either host. And every link the product sends, in emails, sign-in links and webhooks, is built from the canonical address, never from the slug alone.

One thing changes for people when a domain goes active: sessions are per host, so a visitor signed in at the old address signs in again at the new one.

In Swingback, owners on Pro add their domain under Settings → Custom domain: Custom domain and branding walks through the two records and what each state means.