Vanity URL Customization

Overview

Your company probably has a domain that reflects the company’s marketing vision. When end-users interact with your website, they visit your company’s top-level domain (or subdomains). But when end-users interact with an Unqork application, they visit an Unqork-owned subdomain. For example, yourcompany.unqork.io. What if you want end-users to access your Unqork environment through a custom domain? You can do this by using a vanity URL. Vanity URLs give end-users a seamless experience when they interact with your applications.

In this article, you’ll learn about vanity URLs and how to set one up with Unqork.

What You'll Learn

In this article, you'll learn:

What Is a Vanity URL?

A vanity URL is a custom web address. It can point to your Unqork application using a new naming structure. For example, you can redirect mycompany.unqork.io to myapp.mycompany.com. This allows end-users to interact with your application by way of a branded URL. To map traffic from one domain to another, you'll use a CNAME.

NOTE  Unqork doesn't support DNS A Records.

Setting Up a Vanity URL with Unqork

By default, Unqork runs your production applications using an Unqork subdomain. For example, mycompany.unqork.io. To use a different domain or subdomain, you'll need an SSL certificate. This certificate authorizes your Unqork application to serve traffic on that domain.

There are two ways for Unqork to apply a SSL certificate to the site. The first is using AWS Certificate Manager (ACM).

NOTE  Your target environment must be on AWS to use ACM. It is highly recommended that you use ACM to apply a SSL certificate to the site if you are using AWS.

The second way is to use a certificate signing request (CSR). Both of these methods require creating a CNAME from the requested domain name to your Unqork environment URL. Also, the fully qualified domain name (FQDN) must be able to be resolved publicly. Before you set up a vanity URL with Unqork, you'll need the vanity URL and the Unqork environment domains.

Setting Up a Vanity URL with ACM

Unqork supports configuring SSL certificates by way of ACM for customer environments in AWS. AWS is a Root CA and can generate SSL certificates on behalf of any domain. This method requires Unqork to validate that each SSL request for a domain is a legitimate request. ACM provides Unqork with a CNAME to add to the DNS record for the requested domain. Follow your DNS provider’s procedures to add the CNAME to your domain.

NOTE  ACM DNS validation times out in 72 hours. Don’t start this procedure unless you can complete it in 72 hours.

1. Contact your Unqork representative and tell them you need to generate an ACM Certificate.

NOTE  You'll need to provide your Unqork representative with the vanity URL and Unqork environment URL.

2. Your Unqork representative provides you with validation entries to create in your DNS record. Here's an example of the validation entries your Unqork representative provides:
Domain Name Record Name Record Type Record Value
mycompany.com _000000000xxxxxxxxx.mycompany.com

CNAME

_xxxxxxxxx0000000.acm-validations.aws
3. Update your DNS record with the validation entries.

NOTE  Validation entries include your domain name. Your DNS provider might auto-append your top-level domain. If your DNS provider auto-appends your top-level domain, do not include it when you update your DNS record.

4. When the DNS entries propagate, the certificate automatically validates.
5. Test the validation entries.
a. Open a Terminal window.
b. Enter the following:
Copy 
nslookup <your_validation_record_name>
c. The record value is returned.
Copy 
<your_validation_record_value>

NOTE  If the terminal does not return the record value, verify the domain name is not auto-appended to the record name.

  
6. After the records are created, contact your Unqork representative to update your validated ACM certificate for custom domain use.
7. Create a CNAME DNS record pointing from your vanity domain or subdomain to the Unqork environment URL.

NOTE  Consult with your DNS registrar’s documentation if you need help configuring the CNAME DNS record.

Setting Up a Vanity URL with a Certificate Signing Request

A CSR is a message sent from an applicant to a registration authority. This message contains all the information a registration authority needs to identify, validate, and produce a certificate for a vanity URL. If you use a CSR, you'll purchase a certificate from a CA, return the certificate to Unqork, and Unqork updates your environment with the certificate.

NOTE  The CSR process is very manual, prone to errors, and requires an annual renewal. Unqork recommends that you use ACM to create your vanity URL if possible.

1. Contact your Unqork representative and tell them you need to generate a CSR. You'll need to provide your Unqork representative with the following:

  • FQDN for your vanity URL. For example, myapp.mycompany.com.

  • 2-digit country code.

  • Full state or locality name. For example, California or Barcelona.

  • Organization name. This is the full legal company or personal name registered in your locality.

  • Organization unit. This is the department in your organization that is requesting the certificate.

  • Unqork environment URL. For example, mycompany.unqork.io.

2. When the CSR is complete, your Unqork representative provides you with the CSR file.
3. Submit the CSR file to a public CA for signature.
4. After the public CA signs the CSR file, send it to your Unqork representative.
5. Create a CNAME DNS record pointing from your vanity domain or subdomain to the Unqork environment URL.

NOTE  Consult with your DNS registrar’s documentation if you need help configuring the CNAME DNS record.