Domain management: DNS and SSL configuration requirements

Introduction

A domain is a human-readable internet address such as learn.mycompany.com that can be used, for example, to access websites and email services. 

In Docebo, domains may be used in the following ways: 

• A custom domain that lets you replace the docebosaas.com URL of your platform with a domain of your choice
• A secondary domain that lets you similarly replace the subfolder-based URL of an extended enterprise client (for example, https://<yourcompany>.docebosaas.com/sales with a domain of your choice)
• An email sender domain such as mysender.net that allows you to send out platform emails from sender addresses ending in @mysender.net.

Before you can configure a domain in the platform for one of these purposes, the domain that you use must be registered in your company’s name. Typically this is done through a registration provider, or it may be handled by your corporate IT department or a trusted vendor.

After acquiring the domain, you will also need to appropriately configure its DNS settings. Typically DNS servers are provided by your domain registrar, your hosting provider or they are self-hosted on your corporate network. If you are unsure how to edit DNS records you may need to contact your provider for further assistance.

In addition, the domain must be protected by an SSL certificate.

This article details the DNS and SSL configuration requirements for the different types of domains used in the platform.

Please note: Docebo does not provide domain registration or DNS services and cannot provide support for a domain registered with a third party.

Remember that DNS cannot be configured directly from the platform. To make DNS configuration changes we recommend contacting your IT department. On the Docebo platform you can only check or validate that the settings you have configured with your DNS provider correspond to those required by the platform itself.

Email domains (SPF, DKIM, MX)

For an email sender domain, the following DNS records are needed:

• SPF (Sender Policy Framework) - ensures that only authorized servers can send emails from your domain
• DKIM (DomainKeys Identified Mail) - used to verify that messages have not been tampered with in transit
• MX (Mail Exchanger) - specifies the mail server responsible for accepting email messages on behalf of a domain name

Without these DNS records, emails may still appear to be sent but could end up marked as spam, or be rejected by the recipient server altogether.

v=spf1 mx include:docebosaas.com ~all

include:docebosaas.com

When configuring an email domain:

• If you choose to use the Built in email service then the user interface will display the SPF and DKIM records that you must use in the DNS settings for that domain. You can then use the Test DNS configuration button to check that the DNS configuration is correct. Make sure to allow for the DNS record propagation time first. 
• If you instead choose the Custom SMPT option, then you must contact your SMTP provider to verify that the necessary DNS records are in place.

Tip for Amazon Route 53 hosting: The Route53 DNS service doesn’t allow values to be longer than 255 characters. As a result, you may encounter an error when attempting to paste in the DKIM value copied from the platform into the Route 53 console. This can be resolved by splitting the record string as described in the AWS article Resolve DKIM text record error (opens in a new tab).

Custom domains and secondary domains (CNAME, CAA)

CNAME record

For both a custom domain and a secondary domain, the domain name you have procured must be configured so that it points to your main docebosaas.com platform URL.

To accomplish this redirect, you must update the DNS records of your domain, providing a CNAME record that resolves to the desired target platform address.

Please note: The target will be the same for all the custom or secondary domains you configure: they must all resolve to your main docebosaas.com platform URL.

Tip: The CNAME record links a domain name with an alias; another domain name under which the same offering can be reached. This is different from an A or AAA record, which instead maps a domain name directly to a numeric IP address.

You can check the CNAME record of a custom or secondary domain directly from Domain management, by clicking the Test configuration button. Be sure to allow for the DNS record propagation time first. 

CAA record

Some DNS providers support a CAA (Certification Authority Authorization) record that specifies which certificate authorities (CAs) can issue SSL certificates for a domain. If no CAA record is present, any CA can issue a certificate for the domain.

If your domain has a CAA record set, make sure that it includes the certificate authority that you plan to use to generate the domain’s SSL certificate. If you plan to use a certificate managed by the platform, see the chapter Let’s Encrypt SSL certificates (Managed by the platform).

Conflict between SPF and CNAME records

Do not reuse an email domain as a custom or secondary domain, as the required DNS configurations may conflict: most DNS services do not allow for a CNAME and SPF record to coexist for the same domain.

DNS record propagation time

When adding a DNS record, please allow for adequate time to pass in order for the record to properly propagate before testing your domain. Also, if you are changing an existing record, please allow the TTL (Time to Live) of the old record to pass before attempting to use the updated record.

Let’s Encrypt SSL certificates (Managed by the platform)

Each custom domain or secondary domain must be fully protected by an SSL certificate. This is mandatory for configuring the domain in the platform. You can opt to procure your own SSL certificate from a CA (certification authority), or you can choose to use a certificate managed by the platform.

The platform-managed certificates are generated via an external service, Let’s Encrypt (opens in a new tab).

Please note:

• If the DNS configuration for a domain is not met, because the CNAME record is missing or not visible, then the platform cannot create a Let’s Encrypt certificate for that domain.
• Some providers such as Cloudflare may perform CNAME flattening by default. This prevents the CNAME record from being returned as expected, which in turn blocks creation of the Let’s Encrypt certificate. See the chapter Cloudflare compatibility.
• If your domain’s DNS configuration has a CAA record set that does not allow letsencrypt.org, or if no CAA record is set but the DNS provider responds incorrectly to CAA queries, then creation of a Let’s Encrypt certificate will fail. More information about Let’s Encrypt and CAA (opens in a new tab)

In all these cases, the creation of a certificate Managed by the platform will fail.

SSL certificates and Cloudfront CDN

For customers using the Cloudfront CDN signed cookie feature on their platform, please note that:

• The Managed by the platform (Let’s encrypt) certificate option is not supported for Cloudfront CDN. Even if certificate generation apparently succeeds, when visitors go to the domain URL they will encounter an error indicating that the SSL certificate is invalid or expired.

You can instead use a custom SSL certificate, although an additional procedure is required to correctly set it up for your domain: After uploading the SSL certificate and associating the domain in the normal way (see the article Domain management: Custom SSL certificates), you need to contact Docebo support to have it served

Cloudflare compatibility

Domains registered via Cloudflare and certificates issued by Cloudflare may work but we cannot guarantee support or provide troubleshooting for their configuration. Docebo recommends that you contact your Cloudflare representative for any troubleshooting.

• In particular, a known issue is “CNAME flattening” (opens in a new tab) which can prevent validation of a domain’s CNAME record by third party services. This in turn may prevent Let’s Encrypt or other CAs from generating a certificate for that domain.
  Consequently the creation of a certificate Managed by the platform will fail.
• The incorrectly returned CNAME record also interferes with Domain management, causing an SSL certificate different from the one registered in the platform to be served. This may result in server errors when attempting to load certain widget pages.