Domain management: Custom SSL certificates

Introduction

This article covers the configuration of custom SSL certificates in the Domain management area of the platform. 

SSL certificates are required on the platform to secure your custom and secondary domains.
When you configure a custom domain or a secondary domain in the platform, you will have the option to use either a certificate managed by the platform or a custom SSL certificate that you have procured yourself:

• If you plan to choose a certificate managed by the platform, you do not need to do the configurations described in this article. The platform will directly handle the creation, uploading, serving, and renewal of your domain’s certificate.
• If you instead want to use a custom SSL certificate, you will have to go through the steps described in this article to add your certificate to the platform.
  Once you have done this, when you go to configure your custom or secondary domain, you will be able to select the previously added certificate from a drop-down list.
   

Prerequisites

The configuration of SSL certificates is available if you have either the custom domain or the extended enterprise features active on your platform. 

If you do not have either of these you do not need to configure SSL certificates.

Prepare an SSL certificate for a domain 

This chapter covers all the steps you need to complete before you can upload an SSL certificate to the platform. 

Domain name to protect with the certificate:

You must have already procured ownership of the domain name that you want to protect with an SSL certificate. Typically this is done through your registration provider or corporate IT department.
→ The domain name you use can be between 3rd and 5th level, and should not be the same as any email sender domain that you are using. For more information see the corresponding articles on custom domains or secondary domains. 

DNS configuration of the domain:

Before you request an SSL certificate, the domain’s DNS configuration must be properly completed, with a correct CNAME record, and CAA record if applicable.
➢ See the article on Domain management: DNS configuration requirements.

Otherwise the certificate authority (CA) will not be able to issue an SSL certificate for the domain.

Purchase SSL certificate for the domain:

Next you need to purchase, from a certificate authority (CA) such as Digicert or Comodo, an SSL certificate issued to your domain (or to a matching wildcard domain). 

Please note: This is a technical functionality. Contact your certificate vendor, corporate IT department, or trusted partner for assistance if you are unfamiliar with this process.  

When purchasing a certificate, you will generally be required to submit a Certificate Signing Request (CSR) file, which contains the common name(s) you want your certificate to secure, information about your company, and your public key. 

→ Note that the platform does not offer a facility to generate a CSR file for you. However you can generate your CSR using tools such as OpenSSL. 

When generating the CSR, you are required to specify the common name : this is the fully-qualified domain name you want to secure with your certificate.  For example, learning.mycompany.com. If you are requesting a wildcard certificate, add an asterisk * to the left of the common name where you want the wildcard. For example, *.mydomain.com.

Some registrars and certificate providers require you to choose the type of web server your site is hosted on in order to proceed through their registration process. In those cases choose or enter Apache as the hosting server type. 

Note on self-signed certificates:

Using self-signed certificates causes errors on the platform’s features. Docebo recommends purchasing an SSL certificate from a CA authority as outlined previously, to provide an optimal user experience.

Prepare .PEM certificate files for upload:

When you purchase an SSL certificate you will receive from the Certificate Authority one or more files that may be in CRT, DER, PEM or some other format:

• A primary certificate file, that contains the public key and domain validation information: For example, <yourdomain_name>.crt
• Intermediate certificate file(s), containing the intermediate certificates required for chain of trust: For example, <Intermediate>.crt 

You will also require: 

•  A private key file, eg <Your_Domain_Name>.key. This is not provided by the CA but is generated on your server when you create the Certificate Signing Request (CSR)

These files must be converted to PEM format before they can be uploaded to the platform.
→ You can do this using OpenSSL, or some other tool.

Specifically, the required format is: PEM format only, with a .pem file extension, and included in a text file. This means the file can be opened in any plain text editor such as Notepad (for Windows) and TextEdit (for MacOS), to check that it is in the correct format:

The PEM certificate file should begin and end with the following tags, and not have any text outside those tags:

-----BEGIN CERTIFICATE-----

-----END CERTIFICATE-----

Similarly, the PEM private key file should begin and end with the following tags:

-----BEGIN RSA PRIVATE KEY-----

-----END RSA PRIVATE KEY-----

The text between these start and end tags should consist of lines of exactly 64 characters, with the final line containing 64 or fewer characters (this is according to the PEM format specifications (opens in a new tab))

Add an SSL certificate to the platform

Before you can assign a certificate to a domain you have to add it to the Domain management area of the platform.

After preparing the certificate files as in the chapter Prepare an SSL certificate for a domain, select Navigation menu > Configuration (spanner icon) > Platform setup and tools > Domain management. Then click the plus icon in the top right corner of the window, and select the option New SSL certificate.

In the panel that opens, enter a Name for your certificate. Please note that this name has no connection to the certificate, it is merely for your reference. Then in the Parameters section upload the upload the PEM format files with .pem extension that you prepared previously:

• The required SSL certificate file and the Private key file
• And optionally the Intermediate CA file.

Once you have added the files, click Create and Edit to continue. In the page that opens, the Properties tab summarizes the certificate that you uploaded. All the information here is read-only apart from the certificate Name. 

• In the General section, you can review the Name and certificate files.
• In the Details section, you can check the certificate Issuer, Validity dates, and DNS names for which the certificate can be used. These properties all depend on the PEM files that you uploaded.

Please Note: Wildcard certificates are supported by the Domain Management feature. A wildcard certificate can be added and used for all domains that match the pattern without having to reload the certificate for every domain needed.

→ Once a certificate has been added, it will be listed in the SSL certificates tab of the Domain management page, and you can assign it to a domain.

View the SSL certificates

To view the list of certificates, select Navigation menu > Configuration (spanner icon) > Platform setup and tools > Domain management, then in the Domain management page select the SSL certificates tab.

You can filter the list of certificates to show only those that are not assigned to any domain:

• In the top left corner of the list, click the filter icon and select the check box Without assigned domains.
• Click Clear active filters to revert to showing all the certificates.

You can also enter text into the Search… box to find a specific certificate quickly.

To customize which columns are displayed, in the top left corner of the list click the columns icon and select which columns you want to show. Unchecking a box will hide the associated column from view.

Each certificate in the list shows the status (valid, expired, expiring soon), validity information, and the number of domains to which it is assigned. You can view all the information about a certificate by clicking its name in the list.

• The Properties tab contains two sections, General and Details. These fields are all read-only apart from the certificate Name.
• The Assigned domains tab lists the domains to which the certificate is currently assigned.

Assign an SSL certificate to a domain

Once you have added an SSL certificate, you can assign it to a domain as follows: 

1. In the list of SSL certificates, locate the certificate you want to use and, in the Assigned domains column, click the globe icon.
2. Now in the Assigned domains tab you will see the list of domains, if any, that are currently using this certificate.
3. To add a domain, click the plus icon in the top right corner and select Assign domain. Then select the domain and click Assign.
   → You will be able to select only domains that match this certificate and do not already have another certificate assigned.

An alternative method is to assign the certificate from the domains tab:

1. In the Domain management page: 
   - for the main domain go to the Main domain tab
   - for a secondary domain go to the Secondary domains tab, and on the row of the domain click ellipsis icon > Edit  
2. Scroll down to the SSL certificate section, select the Custom SSL certificate option and then from the drop-down list select the certificate you want to assign.
   → You will be able to select only from certificates that match the domain.

Please note: a certificate is eligible to be assigned to a domain if the common name in the certificate file–or one of its subject alternative names (SANs)--matches the domain, either exactly or with a wildcard pattern.
The same certificate can be assigned to multiple domains, however each domain can have only one assigned certificate.

Once you have assigned the SSL certificate, we suggest checking your custom domain encryption using a tool, like the examples listed, to confirm that the process has been completed successfully:

• Digicert TLS/SSL certificate tools (opens in a new tab)
• Namecheap SSL Checker (opens in a new tab)

In order to have a correct training material tracking when using a custom domain, make sure that your custom domain is fully secured using HTTPS. Please note that Docebo supports HTTP/2 (opens in a new tab) over TLS 1.2 (opens in a new tab).

Unassign a certificate from a domain

You can remove a self-managed SSL certificate from a domain. Note that, when you do so, a platform-managed certificate will be automatically issued to be used in its place.  

1. In the list of SSL certificates, click the name of the certificate you want to unassign and then select the Assigned domains tab.
2. On the row of the domain you want to unassign, click ellipsis icon > unassign from certificate.
   → You will see a warning that a certificate managed by the platform will be issued to replace the one you are removing.
3. Click Unassign to confirm.

Please note: The platform-managed SSL certificates are created through the external Let’s Encrypt service, and there is a limit of 5 certificates per domain per week. If you have already reached this limit, you will receive an error message “An error occurred while generating the SSL certificate managed by the platform”, and will be unable to proceed with the Unassign.

Replace a domain’s SSL certificate

You will need to replace your custom SSL certificate, for example, when it is expired.  

Also, if you want to change any properties of a certificate other than its Name, for example to add an Intermediate CA file, you cannot do so on the existing certificate. You will need to replace the certificate: 

1. Follow the procedure described in the chapter Add an SSL certificate to add a new certificate, uploading for it certificate files that incorporate any changes you need.
2. Now to replace the old certificate with the new one:
   - for the main domain go to the Main domain tab
   - for a secondary domain go to the Secondary domains tab, and on the row of the domain click ellipsis icon > Edit  
3. Scroll down to the SSL certificate section and from the SSL certificate drop-down list, select the new certificate you just added. Then click Save changes.  

Repeat this procedure for any other domains that were using the same certificate.

Please note: It is not recommended to replace the certificate by doing an Unassign of the old one, followed by an Assign of the new certificate. This because the unassign will automatically trigger the issuing of a platform-managed certificate for the domain, with the risk of incurring in the 5-certificate limit.

Delete an SSL certificate

You can only delete an SSL certificate if it is not assigned to any domains.

1. In the list of SSL certificates, locate the certificate you want to delete.
   → If the certificate has associated domains, you will need to either unassign it from each domain, or alternatively replace it with a different certificate.
2. Hover over the certificate’s row and click ellipsis icon > Delete. Then in the dialog box click Delete again to confirm.

Frequently asked questions about domain management

For information about frequently asked questions, please see the article Domain Management: Questions and Answers.