Domain types

To use SaaS Custom Domains effectively, you need to know about 3 different types of custom domains supported at SaaS Custom Domains: subdomains, apex domains, and wildcard domains.

Subdomains

A subdomain is a part of a larger domain. It's a way to organize and navigate the hierarchy of a website, and it typically reflects specific content or functions of the site.

For example, in the domain blog.example.com, blog is the subdomain of the main domain example.com. Subdomains can be used to separate different areas of a website, such as a blog, shop, or support section. They are helpful in organizing content and can be managed separately, allowing for different hosting, security settings, or even branding.

How to add a custom subdomain?

Suppose you want to create a custom subdomain like custom-subdomain.example.com.

  1. Select the Upstream: Choose the upstream for which you wish to create a custom domain.
  2. Create the Custom Domain: Navigate to the dashboard and create the custom domain.
  3. Configure a CNAME Record: Create a CNAME record at custom-subdomain.example.com that points to in.saascustomdomains.com.
  4. Verify and Access: That's it! You're all set. Visit custom-subdomain.example.com, and you should see your app.

Apex Domains

An apex domain, also known as a root domain or naked domain, is the primary address of a site without any subdomains or prefixes. It's the core domain name that users type into their browser to access a website.

For example, example.com is an apex domain. It's the fundamental, top-level domain that doesn't include www or any other subdomains.

How to add a custom apex domain?

Suppose you want to create a custom apex domain like example.com.

  1. Select the Upstream: Choose the upstream for which you wish to create a custom domain.
  2. Create the Custom Domain: Navigate to the dashboard and create the custom domain.
  3. Configure A Records: Create two A record at example.com that point to 99.83.186.151 and 75.2.96.173. It's important to create both A records for your custom domain to work. This is because we use two different IP addresses for high availability.
  4. Verify and Access: That's it! You're all set. Visit example.com, and you should see your app.

Wildcard Domains

Wildcard domains are used to match requests for non-existent subdomains. They are specified by using an asterisk * as part of the domain name, usually at the subdomain level.

A wildcard domain might look like *.example.com, and it will match requests for any subdomain that hasn't been specifically defined within example.com. This is useful in scenarios where you want to dynamically generate subdomains or have a catch-all routing for various subdomains.

For example, you might use wildcard domains to create personalized URLs for users, like john.example.com or sarah.example.com, without having to create a custom domain and DNS record for each user. You'd just need to create a CNAME record *.example.com and point to in.saascustomdomains.com and then handle the routing within your application.

Another use-case for wildcard domains is that they can be used to create a catch-all routing for subdomains. For example, you might want to redirect all requests for non-existent subdomains to a specific page or URL. You can do this by creating a wildcard domain and then handling the routing within your application.

Certificate types for wildcard domains

Custom wildcard domains can be set up to use either a single TLS certificate or multiple TLS certificates. The type of certificate you use will depend on your use-case and requirements.

On Demand certificates

This option is useful if you want to have a separate certificate for each subdomain, e.g. john.example.com and sarah.example.com would receive their own TLS certificates.

Suppose you want to create a custom wildcard domain like *.example.com.

  1. Select the Upstream: Choose the upstream for which you wish to create a custom wildcard domain.
  2. Create the Custom Domain: Navigate to the dashboard and create the wildcard domain *.example.com — make sure to choose the On Demand certificate type option.
  3. Configure a CNAME Record: Create a CNAME record at *.example.com that points to in.saascustomdomains.com.
  4. Verify and Access: That's it! You're all set. Visit john.example.com or sarah.example.com, and you should see your app. Notice how each subdomain has its own TLS certificate.

Alternatively, instead of creating a single CNAME record for *.example.com, you can create a CNAME record for each subdomain, e.g. john.example.com and sarah.example.com, and point them to in.saascustomdomains.com. Use this approach if you are adding custom domains for your users and you don't have access to their DNS management and they have to create the CNAME records themselves.

Wildcard certificates

Use this option if you want to have a single certificate for all subdomains, e.g. john.example.com and sarah.example.com would receive the same TLS certificate.

This option requires a bit more work upfront because you have to add an additional DNS record for the DNS-01 challenge.

Suppose you want to create a custom wildcard domain like *.example.com.

  1. Select the Upstream: Choose the upstream for which you wish to create a custom wildcard domain.
  2. Create the Custom Domain: Navigate to the dashboard and create the wildcard domain *.example.com — make sure to choose the Wildcard certificate type option.
  3. Configure a CNAME Record: Create a CNAME record at *.example.com that points to in.saascustomdomains.com.
  4. Configure a second CNAME Record: Create a CNAME record at _acme-challenge.example.com that points to _acme-challenge.example.com.challenges.saascustomdomains.com — this CNAME record lets certificate authorities verify that you own the domain.
  5. Verify and Access: That's it! You're all set. Visit john.example.com or sarah.example.com, and you should see your app. Notice how the TLS certificate is issued for *.example.com and not john.example.com or sarah.example.com.

Similarly to the On Demand option, you can replace step 3 by creating a CNAME record for each subdomain, e.g. john.example.com and sarah.example.com, and point them to in.saascustomdomains.com if you cannot add the *.example.com -> in.saascustomdomains.com CNAME record for any reason.

Note: When using wildcard custom domains, every subdomain that is used to access wildcard domain is counted towards your plan limit for the month.