KB-1536 How to configure a custom domain in Appian Cloud sites

Purpose

Appian Cloud customers can request to customize site URLs to provide a personalized experience to end users. Upon creation, Appian Cloud sites are assigned a subdomain under the appiancloud.com domain. This guide outlines the steps required to change the Fully Qualified Domain Name (FQDN) of Appian Cloud sites to a custom domain.

Use Case

Let’s follow the setup with an example. Let’s say your domain is “mycorp.org” and you have a site, namely, “production-acme” currently using appiancloud domain as “production-acme.appiancloud.com”. You want to customize this sites to use “mycorp.org” so that the end users can access the site using URL using “production-acme.mycorp.org”.

Here are some facts about customizing domains:

Currently, your Appian Cloud site uses 3 FQDNs:

  • “<your site>.appiancloud.com”
  • “<your site>.appiancloud-static.com” - Referred to as “Static FQDN” in this article from this point onwards.
  • “<your site>.appiancloud-dynamic.com” - Referred to as “Dynamic FQDN” in this article from this point onwards.

Only the first FQDN is visible to end users.  You can decide to customize:

  • All 3 FQDNs listed above.
  • Just the FQDN “<your site>.appiancloud.com”. If you are accessing your site over VPN (as described in KB-1541) or dual access i.e. over VPN and HTTPS (as described in KB-1537), you need to customize all 3 FQDNs.

Let’s come back to our example now:

  1. You can decide to customize ALL 3 FQDNs, “production-acme.appiancloud.com” to “production-acme.mycorp.org”, “production-acme.appiancloud-static.com” to “production-acme.mycorp-static.org” and “production-acme.appiancloud-static.com” to “production-acme.mycorp-dynamic.org”. Remember, you can acquire any domains you prefer for Static FQDN and Dynamic FQDN, it doesn’t need to have the words “static” and “dynamic” in them.
  2. You can decide to customize only FQDN “production-acme.appiancloud.com” to “production-acme.mycorp.org”. In this case, your site will be setup with “production-acme.mycorp.org”, “production_acme_mycorp_org.appiancloud-static.com” and “production_acme_mycorp_org.appiancloud-dynamic.com”. As you can see, Appian Cloud will take care of handling the remaining 2 domains.

Why do I need to setup 3 domains?

These new FQDNs are used for background web requests to support features such as Document Component Viewer, Custom SAIL extensions, etc. and are needed for security purposes. Please review the Appian product documentation on these features for more details.

Instructions

Now that you understand the use case, here are the steps.

Generate Certificates for HTTPS Traffic

  1. Decide on FQDN(s) for sites using above considerations in mind.
  2. Submit a new support case for your organization.
  3. Provide Certificate Authority (CA) signed certificate.
    1. Fill out the following worksheet with the values to be present in the certificate for each site that you wish to customize: AppianCloud_Worksheet_DomainNameChange.docx. Please see limitations specific to certificates in the attached worksheet.
    2. Appian generates a Certificate Signing Request (CSR) for each site with the information provided in the worksheet.
    3. Use the CSR provided by Appian to have a signed certificate issued by your organization's CA.
    4. Provide PEM-formatted signed certificate(s) and PEM-formatted chain of trust to Appian Support. The chain of trust file should contain the chain of CA certificates starting with the CA that issued the certificate and ending with the root CA.

Steps to take when an existing certificate is close to expiration:

When the certificate is close to expiration, submit a new support case to notify Appian. Appian will generate a Certificate Signing Request (CSR) which can be used to have a new certificate issued from a Certificate Authority (CA). Do NOT generate a separate key. Provide Appian the new certificate in PEM format. On receiving the renewed certificate, Appian will update the certificates for the respective sites. This action does not require any downtime/maintenance window.

Enable Access with Custom Domain

  1. Set up name resolution in your DNS infrastructure.
    • Appian provisions a load balancer that will serve as an entry point for incoming web requests to your site(s). Note that this load balancer will be used to access all of your Appian Cloud sites (i.e. development, test, and production sites).
    • Create CNAME record(s) in your DNS servers mapping the site(s) FQDN to the public load balancer DNS name.
  2. Update your firewall configuration if you have rules that would block traffic to any requested FQDNs.
  3. Schedule maintenance window to rename the site(s)
    • Confirm that the site(s) FQDN resolve to the intended CNAME record when querying your DNS servers. If this is not configured properly, the site will not be accessible following the maintenance window. For example, run the command nslookup <site>.<customdomain.com> to confirm that the DNS servers return the expected CNAME record.
    • Appian Support schedules a maintenance window to restart the site(s) and enable public traffic to flow through the load balancer.

Notes:

  • Customers are not required to change the subdomain portion of the site FQDN assigned when the site was first created.
  • The subdomain portion of the site FQDN must comply with the following requirements:
    • Subdomains must be representative of the customer organization
    • Subdomains should be unique (i.e. each subdomain must be different across environments)
    • Subdomains cannot be generic or include the word "appian" in their name.

Affected Versions

This article applies to all versions of Appian Cloud.

Last Reviewed: March 2019

Related
Recommended