View Categories

Custom Service Domains

2 min read

What is a Service Domain? #

Each Cyclr Partner Console is given a unique host name called the Service Domain.

The default Service Domain is typically {YourCompany}-h.cyclr.com.

The Service Domain is used by Cyclr in its OAuth Callback URLs and webhook URLs.

Because these can be seen by your customers, you may wish to use a “custom” Service Domain by using a host at your own domain.

Using your own domain as a Cyclr Service Domain #

To use your own domain as Cyclr Service Domain, follow these steps:

  • You must provide us with an SSL certificate and its Private Key for the domain you wish to use with Cyclr, e.g. integration.mydomain.com, which we will install on our web servers. Ensure your certificate meets our requirements.
  • You must create a CNAME DNS record pointing integration.mydomain.com to the Cyclr Instance your Console is hosted on. If you’re on the US Instance for example, that will be my.cyclr.com. Get in touch if you’re not sure.
  • Contact Cyclr Support once the above tasks have been completed and we’ll perform the necessary setup on your Cyclr Console.
  • You will need to provide details of a new SSL certificate before the existing one expires (we plan to make this less manual in future).

Warning: Changing your Service Domain will change the domain used in Callback URLs and webhook URLs so should be updated in any external OAuth apps and third-party systems.
Your “default” Service Domain will continue to function for inbound webhook requests and the User Login Page, if enabled.

If you have a custom Service Domain enabled, it will show in your Console under Settings > General Settings along with your “default” Service Domain:

Benefits of a custom Service Domain #

Google verification #

Google doesn’t verify third party domains so you need to set up a custom domain for Google to verify your application.

Removes “cyclr” from Webhook and Callback/Redirect URLs #

The domain set as your Cyclr Console’s Service Domain is used for Webhook URLs as well as Callback/Redirect URLs for Connectors using OAuth authentication. It may therefore be seen by your own customers. Because of this you may wish to change it to your own domain to remove mentions of Cyclr.

Avoids issues with how some web browsers handle third party cookies #

The Safari web browser and Chrome Incognito windows restrict access to third party cookies, causing errors when displaying Cyclr in an iframe to your users.

You can avoid these by using a Service Domain which is a subdomain of the domain hosting your web application.

SSL Certificate Requirements #

When creating a new custom Service Domain, or updating the SSL Certificate for an existing one, we require ALL of the following 3 files:

DescriptionFile
The SSL Certificate itselfFile extension .cer
Example: mydomain.com.cer
The Private Key used to generate the SSL CertificateFile extension .key
Example: mydomain.com.key
A Certificate Authority “bundle” relating to the provider of your SSL CertificateFile extension .ca-bundle
Example: mydomain.com.ca-bundle

Note: If possible, please confirm the .cer and .key files are related before sending to ensure what you’re providing is correct.
This can be done by using the command line openssl tool as follows:

  • openssl x509 -noout -modulus -in mydomain.com.cer | openssl md5
  • openssl rsa -noout -modulus -in mydomain-com.key | openssl md5

The output from these 2 commands should be the same.

Your SSL Certificate and supporting files must have been issued by a recognised Certificate Authority (CA). Examples of some well known CAs are Comodo and RapidSSL.

They typically provide certificates that are valid for 12 months and can be provisioned from DNS providers such as GoDaddy and Name.com.

Warning: We do not support SSL certificates issued by Let’s Encrypt as they expire after only 3 months.