Custom Domain

The Custom Domain page lets your workspace serve concorbit on your own URL (e.g. app.acmeit.co.uk) over HTTPS, with your brand on the login page and every other surface. Customers see your domain and your branding; they never know concorbit is the platform underneath.

URL: /settings/custom-domain
Required permission: settings.tenant

App domain vs mail domain

This page controls the URL where concorbit serves your workspace. It does not control the address your outbound emails come from; that is configured separately at Email Domain.

The two can be the same domain or different, and most workspaces keep them split:

If you want both, configure each page separately. Pointing one DNS record at us is not enough for the other.

How to get there

1. Go to Settings from the sidebar.

2. Open the Custom Domain card.

Or navigate directly to /settings/custom-domain.

The lifecycle

A domain moves through a small number of states. The page shows you exactly what's needed at each step.

Setting up the domain

1. Pick a hostname like app.your-company.com. Use a subdomain: concorbit doesn't serve apex domains (no your-company.com).

2. In your DNS provider, create a CNAME record pointing to the target concorbit shows you (typically concorbit.com). This tells the world "this hostname runs on concorbit's infrastructure."

3. In your DNS provider, create a TXT record at _concorbit-verify.<your-hostname> with the verification token concorbit shows you. This proves you control the domain.

4. Click Verify.

DNS changes can take a few minutes to propagate. If verification fails, wait 60 seconds and click again.

Picking a certificate option

Once your domain is verified, you have two choices.

Let's Encrypt (recommended)

Free, automatically renewed every 60 days, no upkeep. This is what most workspaces should pick. Click Issue & activate and your domain comes online in 10 to 30 seconds.

Bring Your Own Certificate

Upload a certificate + private key you obtain from your own CA (e.g. a wildcard cert for your whole domain, an EV cert, or a corporate-managed cert). Useful if:

• You already have a wildcard cert that covers the hostname.

• You have compliance requirements that demand a specific CA.

• Your IT team has a process for cert procurement and you want to keep that process.

When you click Upload certificate, a modal opens with two text-areas:

• Full-chain certificate (PEM): paste the entire cert chain here. Most CAs ship this as fullchain.pem. It must include the leaf cert AND at least one intermediate; leaf-only certs are rejected (modern browsers don't trust them).

• Private key (PEM): paste the unencrypted private key. If your key has a passphrase, decrypt it first (concorbit can't store passphrases, and nginx needs the key readable on every restart).

Click Upload & activate. Validation happens on the server before anything is installed. If the cert fails validation, you'll see a precise reason (e.g. "Certificate does not cover hostname X", "Private key does not match the certificate", or "Certificate has already expired").

What we validate before activating:

• Cert and key parse as valid PEM.

• Cert's Subject Alternative Name (SAN) covers your hostname (exact match or *.your-domain wildcard).

• The private key matches the certificate.

• Cert is not expired AND has at least 7 more days of validity.

• The chain includes intermediates (not leaf-only).

• RSA keys are at least 2048 bits.

• EC keys are P-256, P-384, or P-521.

• Signature algorithm is SHA-256 or stronger (no SHA-1).

What we DON'T do:

• We don't auto-renew BYO certs. You are on the hook for renewal. We email you 30 days before expiry to remind you.

• We don't store passphrases. The private key must be unencrypted.

• We don't accept SHA-1 signed certs or RSA keys < 2048 bits, as modern browsers reject these.

Switching between Let's Encrypt and BYO

If you've activated with one and want to switch to the other, remove the custom domain and re-add it. The DNS records can stay; you'll just need to re-verify the TXT token (5 to 10 seconds).

Renewal

Let's Encrypt

Auto-renewed by certbot every ~60 days. You don't need to do anything. If renewal fails, the domain status flips to "degraded": your site keeps serving the old cert until expiry, but you'll see a warning on this page.

BYO

You renew with your CA on whatever schedule they impose. 30 days before expiry, we email you with the hostname, expiry date, days remaining, and a one-click link back to this page. Re-upload the new cert + key the same way you uploaded the first one. The rotation is atomic, so customers never see a broken handshake. Your previous version is kept for one rotation as a rollback safety net.

Removing a domain

Click Remove custom domain on the active card. We:

1. Disable the domain in the database (your custom URL stops resolving immediately).

2. Remove the nginx vhost (so requests to your hostname 404 cleanly).

3. Revoke + delete the certificate material.

4. Release the hostname from our registry so anyone else can claim it later.

Customers using your custom URL will get a 404 immediately. The fallback is your <slug>.concorbit.com subdomain, which keeps working.

Security model (engineer-focused detail)

The full security architecture (host allowlist for redirect URLs, atomic versioned-dir cert rotation, sudoers wrapper hardening, audit-event metadata) is documented in docs/internal-guide/byo-cert-plan-2026-04.md and docs/internal-guide/custom-domain-plan-2026-04.md. The short version:

• Cert + key bytes never hit logs or the database (they live on disk under /etc/concorbit-certs/<hostname>/ with mode 0600 on the key, 0644 on the cert, root-owned).

• Validation errors carry classification text only, never a prefix of your PEM bytes.

• The cert install runs through a privileged wrapper script that re-validates every input (hostname pattern, tmp-path canonical prefix, regular file, ownership, size cap) before touching anything.

• Cert rotation is atomic across the cert+key pair via versioned-dir plus symlink swap, so an nginx reload mid-rotation can never see a mismatched generation.