Custom Domains

Edit on GitHubEdit MD

FusionAuth Cloud supports custom domains across all plans. Deployments on Enterprise High Availability plans can enable the Unlimited Custom Domains experience, which includes advanced management capabilities and a modern user interface. In addition to allowing unlimited custom domains, the feature provides the following benefits:

The ability to add and remove individual custom domains
Custom domain validation and routing with a single DNS change
DNS validation status checks for custom domains
Faster provisioning of certificates

To enable the custom domains feature on one of your High Availability cloud deployments, open a support ticket.

Two Interfaces#

Customers may use one of two custom domain interfaces. To identify your interface, navigate to the Hosting page, then select Action -> Custom URL(s) for your deployment:

Custom URL(s)Add Custom URL(s) (legacy)

View Existing Custom Domains#

Custom URL(s)Add Custom URL(s) (legacy)

Add a Domain#

caution

Before adding a custom domain, you must create a CNAME record targeting the durable URL for your deployment. Additionally, if your domain has a CAA record, it must allow the Amazon certificate authority to issue certificates for your domain by including at least one of the following domains:

amazon.com
amazontrust.com
awstrust.com
amazonaws.com

tip

The ability to add multiple domains is only available on High Availability (HA) deployments.

Custom URLsAdd Custom URL(s) (legacy)

caution

The Add Custom URL(s) workflow replaces the existing configuration. Any domains not included in the form will be deleted.

tip

Adding the custom domain auth.piedpiper.com requires creating two records in your DNS provider:

A Validation Record CNAME - authorizes FusionAuth Cloud to use auth.piedpiper.com:
```
[random-value].auth.piedpiper.com. CNAME [random-value].acm-validations.aws.
```
A Vanity URL CNAME - routes traffic from https://auth.piedpiper.com to your FusionAuth deployment, https://piedpiperdeployment.fusionauth.io:
```
auth.piedpiper.com CNAME piedpiperdeployment.fusionauth.io
```

Log in to your account at account.fusionauth.io.
Navigate to Hosting .
Select Action -> Add Custom URL(s) for your deployment.
The Add Custom URL(s) page shows your current list of custom domains.
Add the domain names to Custom domains field; for example, auth.piedpiper.com. Note that the contents of this field will replace all existing domains.
Confirm you want the change by entering the text CONFIRM in the Confirm text field.
Click Submit .
You'll be sent to a verification screen, which will update as FusionAuth Cloud creates your DNS records.
Wait a few minutes. Once complete, you should see a set of records; you must add these records to your DNS.
Once validated, the status will move to Issued. No further action is required at this point.

note

A custom domain added in the account management portal will still work properly without refreshing the status as long as the DNS CNAME record exists. The validation indicators and status refresh are meant to provide additional feedback for configuring and troubleshooting a new custom domain.

Delete a Domain#

Custom URL(s)Add Custom URL(s) (legacy)

Durable FusionAuth CNAME#

If you have an existing custom domain, you might have an existing vanity URL with a CNAME similar to this:

auth.piedpiper.com CNAME piedpiper-deployment-prod.fusionauth.io

You may notice FusionAuth Cloud now supports a [uuid].durable.fusionauth.io CNAME where [uuid] is a UUID such as 3ffe6da1-e6f5-4be4-96e0-5dabdf42fd68. For instance:

auth.piedpiper.com CNAME [uuid].durable.fusionauth.io

This durable URL will not change and is functionally equivalent to the above vanity URL. Using this updated CNAME will enable use of Disaster Recovery services should you require them at a later point.

Unlimited Domains Transition (Enterprise High Availability Only)#

When unlimited domains are first enabled for a deployment, that deployment enters a transition state that lasts 30 to 60 minutes.

This allows time to perform any necessary DNS changes for existing custom domains to prevent domain resolution errors when completing the cutover to Unlimited Custom Domains. During this transition, other deployment actions such as upgrading or destroying the deployment are unavailable, but your deployment will continue to serve traffic normally.

You need to update existing custom domain DNS records pointing to the deployment's *.fusionauth.io domain name to refer to the Durable FusionAuth CNAME. Once you have updated the DNS records, you can complete the cutover to Unlimited Custom Domains from the account management portal by selecting Cutover Custom URL(s) from the Action menu at the top of the custom domains listing page and completing the form on the next page. If a deployment does not have any existing custom domains when unlimited domains are enabled, it can be cut over immediately.