Manage your knowledge base

Setting up a custom domain for your branded knowledge base can be a useful tool to help your customers self-serve and find answers for their most common questions. Setting up a knowledge base with your custom domain can usually be completed in a few short steps. However, if you encounter issues with this process, this article will demonstrate how to troubleshoot the domain validation flow.

In this article

• Terms to know
• Obtain your SSL certificate
  • Stuck in pending validation
  • Certificate Authority Authentication (CAA) errors
• Update your DNS

Terms to know

• DNS: Domain Name System. Maps a domain name (URL) to the IP address a website is hosted on.
• SSL certificate: Secure Sockets Layer certificate. This is a security certificate that Kustomer gives so that we have access to create a redirect record.
• CNAME: Canonical Name. Maps one domain name to another. In the context of a Kustomer implementation, this maps a redirect record to the Kustomer organization's custom domain.

Obtain your SSL certificate

First, open the Kustomer settings to access your Knowledge Base configuration. This article will walk through an example of CNAME setup using an example domain support.charlottekustomer.com.

1. Go to Settings and select Knowledge Base > Configuration.
2. In the General tab, go to the Knowledge Base Domains section.
3. Add your domain to the field provided, and select Add.
4. When the CNAME record appears in the Certificate Approval table, a new CNAME record will need to be added to the domain, with the Host and Record matching what is in the UI. This step generates an SSL certificate, which lets AWS know it has permission to create a new redirect URL. Once the CNAME has been added, the DNS Activation step is started.

The following statuses can show in step 1 with a description of what they mean:

• Pending Validation - Our system is creating the proper CNAME information for your Knowledge Base brand.

• Issued - Our system has provisioned the proper CNAME information and it is now available to you.

• Failed - Our system was unable to provision the information for you. You will need to delete your domain and try again.

• Inactive - the CNAME has been added to an inactive domain.

• Expired - The CNAME record from step 1 was deleted, or the expiration emails from AWS were never acted upon.

• Validation Timed out - The CNAME record was not added within 72 hours of being created in Kustomer.

• Revoked - Access was revoked on the Kustomer engineering side.

Stuck in pending validation

If issuing an SSL certificate gets stuck in Pending Validation, or it has failed entirely, a good place to start troubleshooting is to use this website: DNS Lookup Tool

On the DNS Lookup Tool site, select CNAME and paste the Host name from the Certificate Approval table. Following the example shown in the earlier screenshot, this Host name would be _9c2150d1d150f609dc24cf4de9b7112b.support.charlottekustomer.com. Check that the Canonical Name column matches the Record listed in the Kustomer settings: _73e9b4c32e2f7647874cfd6d7690d51e.btkxpdzscj.acm-validations.aws.

If the CNAME does not match, then a new CNAME record needs to be created that matches exactly what is shown in the Kustomer settings.

If the CNAME doesn't exist, then you'll need to create a CNAME record using the information from the Certificate Approval table.

Certificate Authority Authentication (CAA) errors

Validation errors can also occur if your domain provider has strict guidelines around Certificate Authority Authentication (CAA). If this is the case, your settings will need to be updated to allow Amazon Web Services (AWS) to create an SSL certificate for you. Learn more in AWS: How do I resolve CAA errors for issuing or renewing an ACM certificate?

Update your DNS

When the DNS Activation is deployed, you will need to create another CNAME record that matches the Host and Record shown in the Kustomer settings.

In the example shown above, this step acts as the bridge between https://zzz-charlotte-lesly-women.kustomer.help/ and support.charlottekustomer.com. When a user navigates to support.charlottekustomer.com in their address bar, they are taken to the record link d24d8jmqqm5dv2.cloudfront.net which points to https://zzz-charlotte-lesly-women.kustomer.help/.

If there are issues with DNS activation, you can use the same  DNS Lookup Tool to help troubleshoot.

Select CNAME and then paste in the Host name shown in DNS Activation, which in this case is support.charlottekustomer.com. Make sure the record matches what is shown in the UI, d24d8jmqqm5dv2.cloudfront.net.

If the Canonical Name does not match the URL in the UI, then you will need to delete the CNAME record you already have for your support domain and create a new one with the information listed in the Kustomer settings.

The most common problem with DNS Activation is that users already have a CNAME mapped from another service, which hasn't been deleted yet. Since CNAME records can only point to one URL, you will need to delete the previous one before moving forward.

After DNS Activation has been completed and deployed, the changes may take a few hours to take effect. Once this propagates, your knowledge base will show up on your custom domain.