Whitelabel Domain with TLS

by Sebastien Mirolo on Mon, 24 Aug 2015

The first and easiest thing to do to start a business on the Internet is to register a domain name. There are a few gotchas to be aware of before you select a DNS provider and hand over the domain name to your technical team. This post is a little bit more technical than usual but reading through it will avoid a lot of headaches and frustration later on.

Checklist for whitelabel sites

There are three parties that must work in concert to bring an online product: The DNS provider, The SSL/TLS Certificate provider and the hosting provider. We can't just randomly pick any three and hope they miraculously all work out together. For the impatient, let's start with the checklist of questions to ask ourselves and the provider we would like to use.

  1. Does the DNS provider support top level ALIAS or ANAME?
  2. What is the maximum key size (in bits) allowed by the SSL/TLS Certificate provider?
  3. Will the SSL/TLS Certificate provider sign both, the top level domain name and www. subdomain?
  4. Does the hosting provider guarentees a fixed IP address or does it provide a subdomain URL?
  5. Does the hosting provider support upload of our own SSL/TLS certificates?

The remainder of the post will go through the rationale behind this checklist.

Domain Name association

The first and easiest thing to do to start a business on the Internet is to register a domain name. GoDaddy, DynDNS and other DNS providers offer to rent any available .com domain. For more fancy domains such as .it, .io, etc. we might have to search longer for an appropriate retailer but it is definitely possible.

Armed with a domain name, we need to associate the machine that will answer to that name. Imagine, in the physical world, we registered the AwesomePetFood brand. The first thing we will do is rent a space or a mail box so that customers can walk in or mail their orders to AwesomePetFood. On the Internet we need a machine to "pick up the phone" whenever a customer types AwesomePetFood.com in their web browser.

If we have a physical machine sitting in a data-center and it has a fixed IP address (ex:, for all intended purposes we can consider browsing to AwesomePetFood.com or browsing to directly (no DNS resolution) equivalent - a bit like 1-800-PET-FOOD and 1-800-738-3663 are the same number, the first one just easier to remember.

How do we associate our domain name (AwesomePetFood.com) with the machine hosting our product? We create an "A RECORD" into the domain name service "Zone File".

AwesomePetFood.com. IN A

Renting a bare bone cloud machine from Amazon, Rackspace or DigitalOcean works almost the same way. Technically you get a machine with a dynamic IP address but that address does not change as long as the machine is running. Now your business looks more like a food truck than a physical retail store. Every time we shut down and re-open, customers find us at a new address. That is a bit inconvenient. Most cloud providers thus give you a way to also rent an "Elastic IP", lingo to mean a fixed IP you can associate to a cloud server.

What to do if I do not have a fixed IP?

We have decided that maintaining our own bare bone server is not worth the trouble. We would rather leverage platforms like Heroku, Shopify, or DjaoDjin. The awesome thing about those platforms is that we don't need to know about DNS or SSL to bring our business on the Internet. After we register, we will get a subdomain reachable from any browser (ex: AwesomePetFood.djaodjin.com). Bonus, the subdomain will be available through https, which means secure encrypted connection to our service.

None-the-less, we still want our customers to reach us through AwesomePetFood.com, use the platform as a full whitelabel solution (meaning their brand does not show on our site).

The platform does not guarantee AwesomePetFood.djaodjin.com will always be associated to the same (fixed) IP address. We can't just look it up and create an A RECORD. We will instead insert an alias or C(NAME) RECORD (Nobody knows what happened to the "B" records).

With aliases, there is a potential issue of running in circles. For example we configure our DNS records as such:

AwesomePetFood.com.     IN CNAME    www.AwesomePetFood.com
www.AwesomePetFood.com. IN CNAME    AwesomePetFood.com

When a browser calls the DNS server and ask for the machine on the other side of AwesomePetFood.com, the DNS server happily returns www.AwesomePetFood.com. The browser then ask the DNS server for the machine on the other side of www.AwesomePetFood.com. The browser then ask the DNS server... There is a little problem here. In technical terms, it is called a DNS redirect loop.

To prevent this, and other kinds of related issues, DNS providers generally prohibit top level aliases. This means we cannot create a CNAME for AwesomePetFood.com pointing to AwesomePetFood.djaodjin.com. We can though create a CNAME record for a subdomain of AwesomePetFood.com, so we will do so.

www.AwesomePetFood.com. IN CNAME    AwesomePetFood.djaodjin.com

When a customer types http://www.AwesomePetFood.com in her browser, she reaches our site, while http://www.AwesomePetFood.com shows in her browser URL bar. Unfortunately, when she types http://AwesomePetFood.com (no www.) an error occurs. Most DNS providers Today have a feature called "URL redirect". We use that feature to redirect http://AwesomePetFood.com to http://www.AwesomePetFood.com, directly at the DNS provider level.

URL redirect http://AwesomePetFood.com to http://www.AwesomePetFood.com

SSL/TLS Certificate

We are asking customers to enter their password in order to login. We might even ask them to enter their credit card to pay for our product. Both requires a certain level of trust that we are who we say we are and that the information customers hand to us is handled with care.

AwesomePetFood.djaodjin.com is already HTTPS enabled. A customer can type either http:// or https:// and it will be connected securely to https://AwesomePetFood.djaodjin.com. A green bar https:// means both that the identity of AwesomePetFood.djaodjin.com was verified and the communication to AwesomePetFood.djaodjin.com is encrypted between the customer browser and our server.

Since we are interested customers see https://www.AwesomePetFood.com in their URL bar, we must insure browsers can verify the identity of www.AwesomePetFood.com itself.

There is a lot of math involved. We need to generate a private key, then send a certificate signing request to a SSL provider like DigiCert or GoDaddy, and finally install the resulting public certificate on our server.

Let's decompose those steps in the context of getting a Driver's license after marriage. Alice has been married for a year, it is time to renew her driver license. She will take this opportunity to change her maiden name to her new family name.

Driver LicenseSSL Certificate
Alice goes to the DMVAlice logins into her GoDaddy account
The clerk asks for Alice Social Security NumberGoDaddy asks for www.AwesomePetFood.com Certificate Signing Request
The clerk checks Alice identityGoDaddy verifies the ownership of www.AwesomePetFood.com
The DMV delivers Alice's driver licenseGoDaddy delivers www.AwesomePetFood.com public certificate
Later at a store checkout, an attendent asks Alice her driver license to verify her identityLater, a customer's browser asks for www.AwesomePetFood.com public certificate
Alice presents her recent driver license with her family name matching the name on her recent credit card.Our server returns the public certificate for www.AwesomePetFood.com.
The store attendent accepts payment from AliceOur customer browser displays a green URL bar and secure the communication to our server.

To generate a private key and a certificate signing request for it on a Mac OSX machine, we just open the Terminal.app application and type:

$ openssl req -new -sha256 -newkey rsa:2048 -nodes \
    -keyout AwesomePetFood.com.key -out AwesomePetFood.com.csr

Here we are asked a few questions about the business, website and contact information. The only important thing to remember is to enter the www prefixed domain name (i.e. www.AwesomePetFood.com) when asked for the Common Name.

Country Name (2 letter code) [XX]:
State or Province Name (full name) []:
Locality Name (eg, city) [Default City]:
Organization Name (eg, company) [Default Company Ltd]:
Organizational Unit Name (eg, section) []:
Common Name (eg, your name or your server's hostname) []: www.AwesomePetFood.com
Email Address []:

Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:
An optional company name []:

Remember AwesomePetFood.com and www.AwesomePetFood.com are different names as far as the certification authority is concerned. Technically you would need to get two certificates, one for AwesomePetFood.com and one for www.AwesomePetFood.com. Since a domain name and its www prefixed version are so common, most certificate authorities will generate both public certificates in a single file for a single payment, purely on a business rationale.

Armed with our private key and certificate signing request (CSR), we can go through the certificate authority flow, copy/paste the content of the CSR file when asked, and download the resulting public certificate when available.

In the middle of this process, the certificate authority will verify our identity in different ways. It can range from an e-mail to the administrator, a request to do some changes in the DNS record, put an HTML file on the server, or even a phone call.

The different price level and features for certification (EV / Premium Certificate, etc.) only have to do with the number and complexity of the checks done by the Certificate Authority before delivering a signed public certificate. This might show up differently in the browser URL bar. The underlying cryptography and security remains unchanged between all types of certificates. None-the-less if you want that "Green bar" look, a Certificate Authority will require to verify your business street address. This usually involved registering with Google Business and a verification code sent by physical mail.

Typically the Certificate Authority will generate a zip package that contains two files: the actual signed public certificate and a certificate chain. We drop the chain file and just copy the public certificate in place. Many times our site works after that, until someone complains the iPhone is not happy with our secure site. Why is that?

That is where the certificate chain comes in. There is a whole tree, a whole forest, of Certificate Authorities. Any hacker that manages to steal a Certificate Authority master key could impersonate any sites that authority signed, including our AwesomePetFood.com site. Getting a Certificate Authority master key is the holly grail of web hackers. It is like getting your hands on the machine making government issued driving license. Better there would be no way to tell a real from a fake driving license. Both would be as legitimate even though one was issued by the government, the other manufactured by a hacker.

Certificate Authorities create trees to mitigate the risks if something would go horribly wrong. Our freshly baked AwesomePetFood.com public certificate is a leaf in that tree. A browser will need to walk all the way up the chain from our AwesomePetFood.com to the root, verifying signature along the way before assuring AwesomePetFood.com is legitimate.

Some browser cache the most common trees and some don't. It is better to assume our server will have to send the whole chain from the AwesomePetFood.com leaf to the root. We thus run the following command to create the final AwesomePetFood.com.crt file we will upload to the service.

$ cat fe03ea125cd0493b.crt gd_bundle-g2-g1.crt > AwesomePetFood.com.crt

fe03ea125cd0493b.crt is our public certificate, gd_bundle-g2-g1.crt is the certificate chain provided to us, by GoDaddy in this case, as part of the zip file.

The private key (AwesomePetFood.com.key) and public certificate (AwesomePetFood.com.crt) must make it to the server responding to our domain name so they can be used.

Each service has a different way to import keys and certificates. On DjaoDjin, it is as simple as drag-n-drop the files on the domain configuration page. Services like Heroku enable developers to upload both keys and certificates through command line tools.

Once the key and certificates are in place, we then test various configuration. At our surprise we get the following results:


The browser is not happy with https://AwesomePetFood.com. We configured the DNS service to do an URL forward on AwesomePetFood.com. As a URL forward, the browser expects the DNS service to send AwesomePetFood.com public certificate back but it is not there. It is solely on our server which never saw that request.

How do we fix that? It depends. If we are lucky to have chosen a DNS provider that support ALIAS or ANAME, we should replace the URL forward by an ALIAS or ANAME configuration depending on the DNS service provider. Otherwise we should switch DNS provider or learn to live with the constraint.

More to read

If you are looking for more posts about what it is like to build a boutique subscription product on the Internet, you might enjoy How to bring your own service online and Back to school: lessons learned this summer.

More business lessons we learned running a SaaS application hosting platform are also available on the DjaoDjin blog. For our fellow engineers, there are in-depth technical posts available.

by Sebastien Mirolo on Mon, 24 Aug 2015

Bring fully-featured SaaS products to production faster.

Follow us on