Domain Management: Configuring secondary domains

Introduction

Secondary domains are used on extended enterprise platforms. They allow an extended enterprise client to be accessed through a domain name of your choice, eg https://www.companysales.com, rather than through a subfolder-based URL such as  https://<yourcompany>.docebosaas.com/sales.

You can associate a different, descriptively-named secondary domain to each of your extended enterprise clients. 

This article sets out how to configure a secondary domain for an extended enterprise client. The process comprises some preliminary steps that must be completed outside the platform, such as purchasing/registering the domain, configuring its DNS records, and procuring an SSL certificate. After that, you can configure the secondary domain in the domain management area of the platform. The final step is to associate the secondary domain to your extended enterprise client.

Prerequisites

Extended enterprise app

The extended enterprise feature must be activated on your platform, as this is where you create the extended enterprise clients that will be associated with secondary domains. See the article Managing the extended enterprise app. 

Custom domain app (optional)

This is needed only if you want to have a custom domain for accessing your main platform, and then use subdomains of that custom domain for your extended enterprise clients. 

Domain name:

You must own the secondary domain that you want to associate to your extended enterprise client. Typically this is done through your registration provider or corporate IT department. 

• A secondary domain can be between 3rd and 5th level. 
• An example of a 3rd level domain is sales.yourcompany.com. An example of a 4th level domain is learning.support.mybrand.com.
• If you have a 5th level custom domain, you won’t be able to create a subdomain of it (6th level) as a secondary domain.  But you can still use any other domain name of the allowed levels (3rd to 5th) as your secondary domain. 
• Do not reuse an email domain as your 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 settings:

The domain you have procured must be configured so that it points to the main docebosaas URL of your platform (eg → mycompany.docebosaas.com). This requires updating the DNS records of your domain, and is typically done through your domain registrar, hosting provider, or corporate IT if you have a self-hosted DNS server. 

➢ For more information see the article on Domain management: DNS configuration requirements > Custom domains and secondary domains.

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 

Remember that a correct DNS configuration must be in place before you can procure an SSL certificate for the domain or configure the secondary domain in Domain management.

SSL certificate:

The secondary domain will need to be protected by an SSL certificate. You have two options for this: 

• Use a certificate managed by the platform. For this you do not need to prepare anything at this stage.
• Use a certificate that you have procured yourself from a CA authority or vendor. In this case you will need to upload this to the platform before configuring the domain.
  → Follow the instructions in Domain management: custom SSL certificates to Add an SSL certificate to the platform.
  → Alternatively, you can begin configuring the domain with a platform-managed certificate as an interim measure, and subsequently replace it with a certificate that you procure yourself

Configure the secondary domain

Once you have completed all the steps in Prerequisites you can move on to configure the secondary domain in the platform. 

1. Select Navigation menu > Configuration (spanner icon) > Platform setup and tools > Domain management.
2. Select the Secondary domains tab. This area shows a list of the secondary domains already configured in the platform. 
3. Click the plus icon (New domains and certificates) in the top right corner and select New secondary domain. 
4. In the configuration panel that opens, in the Name field enter the domain name you previously set up with your registration provider.
   
5. Click Test configuration to check that it points to the URL of your platform, as expected.
   → If the validation fails, check the DNS settings of your domain and make sure you have allowed enough time for those settings to propagate.
6. Scroll down to the SSL certificate section. Here you need to set whether to use a certificate Managed by the platform, or a Custom SSL certificate.
7. In case of a custom ssl certificate, select the certificate which you previously added to the platform from the drop-down list.
   → the list will only show the certificates that match the domain name
8. In the case of Managed by the platform, no further action is needed. The platform will create, upload and ensure proper serving of the SSL certificate, as well as automatically manage its renewal.
9. Click Create.

In case of an error with the Managed by the platform certificate, check that the DNS settings of your domain are correct, as set out in the article DNS configuration requirements > Let’s encrypt certificates (managed by the platform). 

Associate a secondary domain to an extended enterprise client

Once you have configured a secondary domain in domain management, you can go to the extended enterprise page and associate it to either a new or existing client. 

Tip: You can initially configure an extended enterprise client of the subfolder type. Then when everything is in place you can edit the client and link it to a secondary domain. 

Select Navigation menu > Configuration (spanner icon) > Platform setup and tools > Extended enterprise management to access the Extended enterprise page. Here you will see a list of all the existing clients. 

To create a new client click New client in the top left corner of the page. To edit an existing client click the Edit icon on that client’s row. 

In the Create/Edit client window enter the Name for the client if necessary. Then, select the option corresponding to the kind of secondary domain you have configured in Domain management:

• Subdomain : This option appears if you have a custom domain configured for your main platform URL. If the secondary domain you configured is a subdomain of your custom domain, it will appear here.   
• New domain: Otherwise the previously configured secondary domain will appear here. 

After selecting the secondary domain from the drop-down list, click Next and continue the configuration of the client as described in the article Managing the extended enterprise app > Creating clients for your extended enterprise. 

Managing secondary domains

To view the list of already-configured secondary domains, select Navigation menu > Configuration (spanner icon) > Platform setup and tools > Domain management and then select the Secondary domains tab. 

The domains listed here are those that are available for or already associated with extended enterprise clients.
→ To check which domains are still available you need to go to the extended enterprise page and, in the Create/Edit client window, see which ones appear in the New domain or Subdomain drop-down lists. 

You can filter the secondary domains by SSL certificate management type, or enter text into the search box to find a specific domain quickly. 

On the row of a domain, click the ellipsis button to access the available actions:

• Edit: A configuration panel opens where you can modify  the configuration of this secondary domain. For example, here you can replace a domain’s custom SSL certificate or generate one Managed by the platform. For full details see the chapter Configure the secondary domain.
  Note that if you rename the domain, the new name must have a valid DNS configuration and you will need to upload or generate a matching SSL certificate, as set out in the chapter Prerequisites. 
• Delete: If your domain is linked to an extended enterprise client you will receive a message to first remove the association before you can delete the domain.  When you delete a domain, the association with its SSL certificate is removed. In the case of a custom SSL certificate, you will see in the SSL certificates tab that the domain is no longer assigned to the certificate. In the case of a Managed by the platform certificate, the certificate is revoked.