URLs, DNS, and TLS Configuration Requirements

Before you can install Advance, you must configure your DNS and TLS settings to enable access to the Advance applications. Your goal is to:

  • Configure DNS and TLS so that requests to your root application subdomain are routed to the server on which you deployed Advance. 
  • Configure DNS and TLS so that requests to your tenancies (sub-sites within Advance) subdomains are routed to the server on which you deployed Advance.
  • Configure DNS and TLS so that requests to the core assembly service are routed to the server on which you deployed the Core Assembly Service.

Prerequisites

Before you begin this topic, you should:

  • Have access to the server(s) on which Advance and Core Assembly Service are to be deployed
  • Be able to create TLS certificates; a wildcard certificate is recommended
  • Be able to edit DNS records for the domain under which Advance is to be deployed
  • Know which site on IIS that Advance and Core Assembly Service are to be deployed
  • Your TLS certificate must be accessible by the account under which the HotDocs Advance and Core Assembly Service application pools run

Quick Start

See the Configuration Requirements Checklist for an itemized list of components you must configure to get TLS and DNS working for Advance. The rest of the topic provides greater detail about configuration requirements.

Overview

There are three entities in Advance for which you need to configure DNS and TLS. These are:

Name Description Example URL
Advance root application The backend interface of Advance where root administrators manage tenancies. https://hdroot.yourorganization.com/HdaRoot  In the example URL above, hdroot is the root subdomain, and yourorganization.com is the AppDomain.
Advance tenancies The individual sites within Advance, created by you using the root application. Tenancies have their own subdomain, named using the tenancy moniker (see below) that you specified during tenancy creation. You can create tenancies after Advance is installed. Advance tenancies require that TLS and DNS is configured for their subdomain. https://yourtenancy.yourorganization.com/hdaui   In the example URL above, yourtenancy is the tenancy moniker, and yourorganization.com is the AppDomain.
Core Assembly Service The Core Assembly Service provides document assembly services via a web Application Programming Interface (API). https://core.yourorganization.com/AssemblyService  In this example URL above, core is the subdomain allocated to the Core Assembly Service, and yourorganization.com is the AppDomain.

The URLs for the applications and tenancies have the following relationship:

 

You will need to set up TLS and DNS for these three entities as below.

TLS Configuration

Advance requires you to set up an https binding in IIS. To do this requires TLS certificates. You can use one of the following certificate options:

  • A single wildcard certificate, which secures everything deployed under your AppDomain, including the root application, tenancies, and Core Assembly Service; or
  • A single multi-domain certificate with a Subject Alternative Name (SAN) field, to which root, tenancies sub-domains, and Core Assembly Service can be added; or
  • Individual certificates for:
    • The root application
    • Each tenancy you create within Advance
    • The Core Assembly Service

Using a wildcard certificate

A wildcard certificate secures all subdomains under a specified domain, meaning that you only need a single certificate for multiple subdomains. When using a wildcard certificate, it is important to consider that they only secure the subdomains at one level below the domain for which your certificate is configured. 

For example, imagine your wildcard certificate is configured to secure your domain at *.yourorganization.com. When you use this domain as the Advance AppDomain, the following subdomains will be secured by your certificate:

  • The root application (e.g. hdroot.yourorganization.com/hdaroot)
  • All Advance tenancies (e.g. site1.yourorganization.com/hdaui) 
  • The Core Assembly Service (e.g. core.yourorganization.com/hdaAssemblyService)

Using a multi-domain certificate

If you have a multi-domain certificate—a certificate that provides a Subject Alternative Name field—you can associate additional DNS names with your certificate. This enables you to secure Advance, the root application, its tenancies and the Core Assembly Service when it is located under a subdomain without having to create a new wildcard certificate. Whenever you add a new tenancy, you must add the subdomain for the new tenancy to the subject alternative name field of your certificate.

Using individual certificates with tenancies

If you decide to use individual certificates, there are some items that must be set up for each new tenancy you create. These are:

  • TLS certificates
  • DNS records
  • IIS bindings
  • Require Server Name Indication setting – you must ensure that this setting is enabled for your IIS bindings

App Domain

The AppDomain is the full domain under which Advance is installed. In most cases, the AppDomain will have the format:

{internal Active Directory domain}

For example, where your internal Active Directory domain is yourorganization.com, the AppDomain will be yourorganization.com.

Root Sub Domain

The root subdomain is the unique moniker for the root application that you specify during installation, with a default value of hdroot. The root moniker defines the subdomain that is used as the URL for the root application. This has the format:

{rootsubdomain}.{appDomain}

For example, where your root application has the moniker hdroot, and your AppDomain is yourorganization.com, the URL for the root application will be https://hdroot.yourorganization.com/hdaroot.

You will need to know the root subdomain if you are creating individual TLS certificates and HTTPS bindings for each sub-domain.

Tenancy Moniker

The tenancy moniker is the unique name for the tenancy that you specify during tenancy creation. The moniker defines the subdomain that is used as the URL for the tenancy. This has the format:

{moniker}.{appDomain}

For example, where your tenancy has the moniker site1, and your AppDomain is yourorganization.com, the URL for the tenancy will be https://site1.yourorganization.com.

You will need to know the moniker if you are creating individual TLS certificates and HTTPS bindings for each tenancy.

Core Assembly Service Sub Domain

The Core Assembly Service subdomain is the unique moniker for the Core Assembly Service that you specify during installation, with a default value of core. The Core Assembly Service moniker defines the subdomain that is used as the URL for the Core Assembly Service. This has the format:

{coresubdomain}.{appDomain}

For example, where your Core Assembly Service has the sub-domain core, and your AppDomain is yourorganization.com, the URL for the Core Assembly Service will be https://core.yourorganization.com/AssemblyService.

You will need to know the core subdomain if you are creating individual TLS certificates and HTTPS bindings for each subdomain.

The moniker must be between 3 and 32 characters, and include a combination of lowercase letters, numbers, and dashes only.

Configuration

Configuration for Root application

The root application is the backend interface where root administrators manage tenancies within Advance. The root application requires its own TLS and DNS configuration. The requirements are:

  • DNS records — you must route the subdomains for your root application to the IP Address of the server on which Advance is deployed.
  • TLS — you must configure IIS with an https binding using a TLS certificate that routes requests for the root subdomain to the IIS site on which the Advance applications are deployed.

Configuration for Advance tenancies

Tenancies are individual sites under an Advance deployment, created by you through the root application UI. You use tenancies to organize and separate the data for different areas of an organization. These tenancies require their own TLS and DNS configuration. Generally, the requirements are:

  • DNS records — you must route the subdomains for your tenancies to the IP Address of the server on which Advance is deployed
  • TLS — you must configure IIS with an https binding, using a TLS certificate that routes requests for the tenancies' subdomains to the IIS site on which the Advance applications are deployed

Configuration for Core Assembly Service

The Core Assembly Service is a web API that provides HotDocs. The Core Assembly Service require its own TLS and DNS configuration. The requirements are:

  • DNS records — you must route the subdomains for your Core Assembly Service to the IP Address of the server on which the Core Assembly Service is deployed.
  • TLS — you must configure IIS with an https binding using a TLS certificate that routes requests for the core assembly service subdomain to the IIS site on which the Core Assembly Service is deployed.

Configuration Requirements Checklist

Requirements checklist

The following checklist lists all the requirements you require to configure TLS and DNS for Advance.

  Name Type Description
1 TLS certificate TLS Either a wildcard certificate, a multi-domain certificate, or individual certificates for your Root application, each tenancy and the Core Assembly Service.
2 Application pool(s) access to TLS certificate TLS The account under which the HotDocs Advance application pool runs must be able to read the TLS certificate.
3 DNS record for Root application DNS You must route the Root application to the IP Address of the server on which Advance is deployed.
4 DNS record for tenancy DNS You must route the subdomains for your tenancies to the IP Address of the server on which Advance is deployed.
5 DNS record for Core Assembly Service DNS You must route the subdomain for your Core Assembly Service to the IP Address of the server on which the Core Assembly Service is deployed.
6 HTTPS binding for Root application IIS configuration An HTTPS binding for your Root application. This must be created using your TLS certificate, added to the IIS site to which Advance will be deployed.
7 HTTPS binding for tenancy IIS configuration An HTTPS binding for your tenancies' subdomains. This must be created using your TLS certificate, on the IIS site to which Advance will be deployed.
8 HTTPS binding for Core Assembly Service IIS configuration An HTTPS binding for your Core Assembly Service subdomain. This must be created using your TLS certificate, on the IIS site to which the Core Assembly Service will be deployed.

Requirements checklist for individual tenancy certificates

Note: this section only applies if you are using individual TLS certificates for each of your tenancies. Each item below must be configured separately for each tenancy.

  Name Type Description
1 TLS certificate TLS An individual certificate for your tenancy.
2 Application pool access to TLS certificate TLS The account under which the HotDocs Advance application pool runs must be able to read the TLS certificate.
3 DNS records DNS You must route the subdomains for your tenancies to the IP Address of the server on which Advance is deployed.
4 HTTPS binding IIS configuration An HTTPS binding for your tenancies' subdomains. This must be created using your TLS certificate, on the IIS site to which Advance will be deployed.
5 Require Server Name indication IIS configuration An IIS setting, configured when adding a new HTTPS binding to your site. You must select this option when adding bindings for each tenancy.

Example Configuration

In this example, we will use a wild card certificate to configure https on your appDomain, yourorganization.com. You should substitute this example value for your own appDomain where necessary.

1. Create your DNS records

The process for configuring DNS records will depend on the service you use to manage your DNS. However, you should meet the criteria specified in the Configuration for Advance Applications and Configuration for Advance tenancies sections above.

2. Test your DNS routing

Assuming you know the IP address of your server, you can test that your changes to DNS routing were successful using the ping command.

  1. Open the Windows Command Prompt.
  2. Type ping yourorganization.com
  3. Press Enter; you should receive a 'Reply from' response that matches the IP address of your server.

Once you have finished the Advance installation process and created a tenancy, you can also perform this check to test routing to your tenancy subdomain. For example, if you have a tenancy named tenancy1, you can use the command ping tenancy1.yourorganization.com.

3. Create your TLS certificate

In this example, we require a wild card certificate. The TLS certificate you use to configure your site bindings must allow requests to the subdomains of your AppDomain (i.e. yourorganization.com, which covers the root application, any tenancies you create in Advance and the Core Assembly Service). The account under which the HotDocs AdvanceAdvance and the Core Assembly Service application pools run must have read access to the TLS certificate.

4. Create your site bindings

  1. Open Internet Information Services (IIS) Manager on the server to which you will deploy Advance.
  2. Expand the top-level server node.
  3. Expand the Sites folder.
  4. Select the site to which you will deploy Advance (in this example, we will assume you are using Default Web Site).
  5. Click the Bindings link in the Actions panel (right column).
  6. Click the Add button.
  7. Select https from the Type drop-down list.
  8. In the hostname field, type your full AppDomain, adding an asterisk wild card for the subdomain; for example, *.yourorganization.com.
  9. Click the Select button.
  10. In the Select Certificate dialog, select the certificate you want to use; for this example, the certificate should be a wild card certificate
  11. Click OK.
  12. Click OK; you have now added a site binding for your tenancies.

You are now ready to start installation of HotDocs Advance.

Testing your Configuration

After you have finished configuring your environment, you can test it with the following steps:

Load the IIS root page

To test that TLS is correctly configured in IIS, open the IIS root page in a web browser:

  1. Open Internet Information Services (IIS) Manager on the server to which you will deploy Advance.
  2. Expand the top-level server node.
  3. Expand the Sites folder.
  4. Select the site to which you will deploy Advance and have configured TLS (for example, Default Web Site)
  5. In the Manage Website pane, click the Browse link for your wildcard HTTP certificate; for example, Browse *.yourorganization.com on *:443 (https)

Your web browser opens and displays the IIS root landing page, loaded under HTTPS.

Run nslookup tests

To test that DNS is correctly configured, run the following test using the Windows nslookup tool:

  1. Open the Windows Command Prompt.
  2. Type the following command:
    nslookup {URL}
    Where you replace the {URL} placeholder with the domain on which you configured TLS. For example:
    nslookup yourorganization.com
  3. Press Enter; the command prompt displays the name and IP address of the server to which your URL points

Next step