URL Registration for GRAX

Registering, delegating, and securing

The GRAX application must be reachable by end-users and Salesforce to provide backup, archive, and restore functionality. To achieve reachability without an overreliance on underlying resources that may change or be replaced during the lifetime of the application, a registered domain name is utilized. We'll refer to this as the "Application URL"/"URL" below. As GRAX can be installed in many ways, the manner by which this URL is managed varies by environment.

GRAX Legacy Heroku Apps

For older GRAX environments that run on Heroku, URLs are decided and managed by Heroku. These URLs include "herokuapp" in the path. Secure custom URLs may be used on a case-by-case basis via the Heroku management interface. Please contact support for assistance if interested.

GRAX Hosted Apps

For hosted GRAX applications, GRAX creates URLs via a standard template and handles registering, renewing, and/or destroying it if no longer needed. URLs will be registered as subdomains under a GRAX-owned second-level domain. Your URL will be provided by a GRAX team member once provisioning is complete and the app is ready for use.

GRAX Templated Apps

Application URLs for apps both running in AWS and based on GRAX templates must be registered within Route53 and related to a hosted zone. Registering a domain manually in AWS automatically creates a related hosted zone. Registering a new domain within AWS is the recommended path for simplicity, but will mean that any potential corporate domain registrations will not be used. Check with your network management/IT teams prior to making this decision. If you are interested in utilizing an already-registered URL and a GRAX template, you will need to delegate DNS for the new subdomain into Route53 from your registrar.

  • Guidance on domain registration in AWS can be found here.
  • Guidance on DNS delegation in Route53 can be found here.

Self-Managed GRAX Apps

Self-managed applications built without utilizing a GRAX template may achieve usage of URLs in any reasonable fashion. Equivalent functionality to Route53 exists in every public cloud. Domains may be registered and handled with your registrar of choice and delegated as required.

TLS/SSL Certificates

The GRAX backend supports TLS encryption by default using a self-signed certificate. This ensures all traffic is encrypted no matter the source (e.g. from a load balancer or public internet). Optionally, users may want to provide their own certificates for a custom domain. In that case, GRAX supports the following two environment variables:

TLS_CERT_FILE
TLS_KEY_FILE

These environment variables tell GRAX where the custom certificate and key are located. Standard GRAX installs include a /home/grax/.env file where these variables can be added. For example:

# .env file containing full paths to the files
TLS_CERT_FILE=/home/grax/certs/grax-example.com.cer
TLS_KEY_FILE=/home/grax/certs/grax-example.com.key

TLS/SSL Certificate File and Password Management

Installing SSL certificate files and supplying a SSL key password (if any) is supported on self-managed GRAX, but is a customization you are responsible for in your cloud instance provisioning or OS service management config.

A simple pattern is to use a wrapper script to download and decrypt a certificate file before starting the grax web server. However this example is insecure with respect to security accessing the SSL keys and storing the password in plaintext in the shell script.

# download certificates from a keystore
curl -O https://10.0.2.1/grax-example.com.cer
curl -O https://10.0.2.1/grax-example.com.key

# remove the passphrase from the SSL key
openssl rsa -passin pass:EXAMPLEPASSWORD -in grax-example.com.key -out plain.key

# provide plaintext key to grax web server
export TLS_CERT_FILE=grax-example.com.cer
export TLS_KEY_FILE=plain.key
grax 

Instead you should integrate with your certificate and secret management systems that authenticate requests, don't expose passwords in plaintext, and rotate certificates and passwords perodically.

See these references to tools and services for certificate and password management:

Support

If you require assistance or have any remaining questions after reviewing the above, send an email to [email protected] with any available details.