How to: Customize a Vanity URL

Estimated Reading Time:  5 minutes

Overview

Your company might have a domain that reflects its marketing vision. When end-users End-users, also known as Express Users, are the individuals accessing an application through Express View. In most cases, end-users are the customers using the product. 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. If you want end-users to access your Unqork environment through a custom domain, you can create 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 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.

IMPORTANT  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 (Secure Sockets Layer) 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:

  • ACM (AWS Certificate Manager). ACM can be used for AWS only.

    TIP  This process is highly recommended.

  • PFX (Personal Information Exchange). PFX can be used for AWS and Azure.

Setting Up a Vanity URL with ACM

Unqork supports configuring SSL certificates by way of ACM for customer environments in AWS only. AWS is a Root CA (certificate authority) that 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.

IMPORTANT  Once the ACM DNS validation record is provided, you have 72 hours to add the CNAME.

1. Contact your Unqork representative and let them know you need to generate an ACM certificate. You or your CA will then submit a Zendesk ticket requesting a vanity URL.

IMPORTANT  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. Create a CNAME DNS record pointing from your vanity domain or subdomain to the Unqork environment URL. Consult with your DNS registrar’s documentation if you need help configuring the CNAME DNS record.

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 _000000000xxxxxxxxx.mycompany.com
c. The record value is returned.
Copy 
_xxxxxxxxx0000000.acm-validations.aws

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.

IMPORTANT  Your vanity URL will not be functional until your Unqork representative confirms the configuration is complete.

Setting Up a Vanity URL with PFX

Unqork supports configuring SSL certificates by way of a PFX file for customer environments in AWS and Azure. AWS and Azure are Root CAs that 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.

IMPORTANT  Avoid providing a certificate with wildcards included. For example, *.clientdomain. Please provide the certificate for your specific domain. Also include the certificate chain of the PFX file.

PFX 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.

1. Contact your Unqork representative and let them know you need to generate a PFX certificate. You or your CA will then submit a Zendesk ticket requesting a vanity URL.
NOTE  

If your CA makes the request, they need to provide a PFX file (including the password) containing the following information:

  • Certificate

  • Chain

  • Key

IMPORTANT  Do NOT attach the PFX file to the Zendesk ticket. The file and password should be sent securely using SendSafely.

2. Create a CNAME DNS record pointing from your vanity domain or subdomain to the Unqork environment URL. Consult with your DNS registrar’s documentation if you need help configuring the CNAME DNS record.

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.

3. Unqork confirms the PFX file and password were sent using SendSafely. Once received, Unqork applies the certificate to AWS or Azure.
4. After the records are created, contact your Unqork representative to update your validated PFX certificate for custom domain use.

IMPORTANT  Your vanity URL will not be functional until your Unqork representative confirms the configuration is complete.

Renewal Process

Certificates must be renewed annually. Depending on your certificate, certain actions might be necessary to renew it. ACM certificates renew automatically, so no action is needed. However, PFX certificates require a specific renewal process.

NOTE  An Unqork representative will contact you 30 days before certificate expiration to assist with renewal.

To renew your PFX certificate:

1. Your CA must submit a Zendesk request with a PFX file (including the password) containing the following information:

  • Certificate

  • Chain

  • Key

IMPORTANT  Do NOT attach the PFX file to the Zendesk ticket. The file and password should be sent securely using SendSafely.

2. Create a CNAME DNS record pointing from your vanity domain or subdomain to the Unqork environment URL. Consult with your DNS registrar’s documentation if you need help configuring the CNAME DNS record.
3. Unqork confirms the PFX file and password were sent using SendSafely. Once received, Unqork applies the certificate in AWS or Azure.
4. Test the validation entries.