Aller au contenu principal

Custom Domains

Custom domains allow organizations to access ProBeya through their own domain (e.g., obeya.yourcompany.com) instead of the default tenant.probeya.com subdomain. This provides a seamless branded experience for all users.

Overview​

For organizations that need their digital transformation platform to appear as an internal tool, custom domains provide:

  • Branded URLs: Users access the platform at your own domain
  • CNAME-based routing: Simple DNS configuration without IP address management
  • SSL/TLS certificates: Automatic certificate provisioning for secure connections
  • Verification workflow: Domain ownership verification before activation

Getting Started​

  1. Navigate to Settings > Custom Domains.
  2. Click Add Domain and enter your desired domain (e.g., obeya.yourcompany.com).
  3. Copy the CNAME record instructions and configure them in your DNS provider.
  4. Wait for DNS propagation and verification (typically 5-30 minutes).
  5. Click Verify to trigger a server-side DNS check.
  6. Once DNS is verified, click Provision SSL to start certificate issuance.
  7. The domain becomes active when the SSL certificate is issued (typically 1-5 minutes).

How It Works​

Domain Lifecycle​

Custom domains progress through a strict status sequence:

StatusDescription
pending_dnsDomain registered, CNAME configuration needed
dns_verifiedServer-side DNS lookup confirmed the CNAME is correct
ssl_provisioningSSL certificate issuance in progress via ACME/Let's Encrypt
activeDomain is fully configured and serving traffic with HTTPS

DNS Configuration​

When an administrator adds a custom domain, the system generates a CNAME target following the pattern {orgSlug}.custom.probeya.com. The administrator must create a DNS record:

Record TypeHostTarget
CNAMEobeya.yourcompany.comacme-corp.custom.probeya.com

DNS changes may take anywhere from 5 minutes to 48 hours to propagate, depending on the DNS provider and TTL settings.

Server-Side DNS Verification​

ProBeya performs its own DNS CNAME lookup using Node.js dns.promises.resolveCname rather than trusting client-reported results. The verification checks whether any returned CNAME records match the expected target (case-insensitive, per RFC 4343). If the CNAME points to the wrong target, the system returns a descriptive error message explaining the mismatch.

SSL Certificate Provisioning​

After DNS verification, administrators can trigger SSL certificate provisioning. The system uses the ACME protocol (Let's Encrypt) to issue certificates automatically. The provisioning workflow:

  1. Creates an ACME order for the domain
  2. Completes the HTTP-01 or DNS-01 challenge
  3. Downloads the issued certificate
  4. Stores the certificate in the reverse proxy layer
  5. Updates the domain status to active

Routing​

The middleware layer in apps/web/src/middleware.ts resolves incoming requests by checking:

  1. Standard subdomain pattern ({tenant}.probeya.com)
  2. Custom domain lookup in the custom_domains table
  3. If a custom domain matches, the request is routed to the correct organization context

Tenant Isolation​

Custom domain records are scoped to organizationId. Each organization can only manage their own domains. The API enforces:

  • Platform-wide domain uniqueness: no two organizations can claim the same domain
  • Ownership verification before activation
  • Activity logging for all domain operations (creation, verification, SSL provisioning, deletion)
  • Cascading cleanup when domains are removed

API Reference​

ProcedureTypeDescription
customDomains.listQueryList all custom domains for the organization
customDomains.createMutationRegister a new custom domain with CNAME instructions
customDomains.verifyMutationTrigger server-side DNS CNAME verification
customDomains.provisionSslMutationInitiate SSL certificate provisioning
customDomains.deleteMutationRemove a custom domain registration

Permissions​

ActionRequired Role
View domainsAny authenticated member
Add domainAdmin or Owner
Verify domainAny authenticated member
Provision SSLAny authenticated member
Remove domainOwner only (stricter due to traffic disruption risk)

Troubleshooting​

DNS verification fails with ENOTFOUND​

The CNAME record has not been configured or has not propagated yet. Wait up to 48 hours and retry. Verify the record exists using nslookup or dig from your own machine.

DNS verification shows wrong target​

The CNAME record exists but points to a different hostname. Update the DNS record to point to the target shown in the ProBeya UI and retry.

SSL provisioning takes longer than expected​

Certificate issuance typically completes within 5 minutes. If it takes longer, check that the ACME challenge can reach the domain (no firewall blocking HTTP-01 on port 80).

Domain shows "pending_dns" after creating CNAME​

DNS propagation can take up to 48 hours in some cases, though most providers complete within 30 minutes. Verify the record exists using command-line tools:

# Check CNAME record
dig CNAME obeya.yourcompany.com +short

# Or using nslookup
nslookup -type=CNAME obeya.yourcompany.com

If the record resolves correctly from your machine but ProBeya verification still fails, try again in a few minutes. The ProBeya server may be using a different DNS resolver with longer cache TTLs.