Important Information:
If you are switching from a legacy custom domain (with no SSL), please contact our support team at support@litmos.com first to perform a migration to Custom Domain with SSL. Failure to do so will require Support to reset your domain and may result in some downtime.
Custom domains need to be configured by an Account Owner with access to the Account –> Features tab. This is where the Account Owner will find the “Custom Domain with SSL” feature.
Important Note: This is a premium feature that must be enabled on your Litmos account before an Account Owner can access the custom domain configuration and complete the custom domain setup. Please contact your Account Manager to purchase this feature.
Once the feature has been enabled on your account, clicking into the Custom Domain feature will route the Account Owner to the custom domain setup:
Please follow the steps as listed in Litmos to register your custom domain with your hosting provider, and return to Litmos to complete the custom domain SSL validation:
“Custom domains allow you to customize your Litmos URL (i.e. companyname.litmos.com can become mysite.com). An SSL certificate will be generated for this new domain once it has been registered and activated. Please follow the steps below to complete the custom domain setup:
Step 1: Register a domain with a Domain Name Registrar (such as Namecheap, Bluehost, HostGator, Hostinger, Google Domains, GoDaddy, etc.).
Step 2: Follow the registrar’s instructions to create a CNAME for your domain that points to:
- customer.litmos.com if your account is hosted on litmos.com
- customer.litmos.com.au if your account is hosted on litmos.com.au
- customer.litmoseu.com if your account is hosted on litmoseu.com
Note: The value to use is the actual word ‘customer‘ and not your Litmos client/domain name.
Please also take a moment to review the CAA records for your domain, if you have preexisting records you will need to add one for Digicert as shown:
$ORIGIN yourdomain.com . CAA 0 issue “digicert.com”
Failure to do so will result in the certificate process being stuck in the “Pending_issuance” status. If there are no CAA records, you can proceed as normal.
If you require assistance configuring CAA records, please reach out to your domain registrar.
Step 3: In Litmos (Account Settings > Litmos Features > Custom Domain with SSL), enter the custom domain into the text field and click “Add”. This step is to ensure that the domain is available on Litmos.
Step 4: If the domain is available, click on “Generate SSL” to generate an SSL certificate for the domain you have chosen. Please note that it can take several minutes for the certificate to be issued. The certificate issuance status can transition from “Initializing” to “Pending Validation” to “Pending Issuance” to “Pending Deployment” as it goes through the SSL validation phase, before it is finally “Active”.
Step 5: Check back on the certificate status. Once the domain shows as “Active”, proceed to click enable. Now your Litmos custom domain can be used.
When a domain is available to use in Litmos, it will say “available for use in Litmos”:
After Litmos verifies that the custom domain is available to register and use, proceed to click “Generate SSL” if that is the domain your organization desires. If this is not the domain your organization wants to register, select “change” and enter a new domain. Litmos may limit the number of times you “change” your domain, so proceed to validate and “change” domains with care.
Once you’ve chosen to validate a custom domain, the domain name will be pending SSL certificate validation. This can take several minutes or longer, so please be sure to check back on the status of the SSL certification. Once the SSL certification has been validated, your custom domain will be available for use.
Troubleshooting
If the Certificate Status is stuck on ‘pending validation’, it could be that the CNAME value has not propagated yet or has been entered incorrectly.
You can use external websites such as MX Toolbox to lookup the CNAME value of your domain. This will help verify if the CNAME value has been setup correctly.
https://mxtoolbox.com/CnameLookup.aspx
When entering your domain, the Canonical Name should display as either customer.litmos.com / customer.litmos.com.au / customer.litmoseu.com (depending on where your Litmos instance is hosted).
If the value is anything other than this, this would need to be corrected. If you have entered the value correctly, you may need to wait a little longer for the changes to propagate.