HTTPS¶

Alation server can be configured to use HTTPS. This requires shell access to the Alation server.

Requirements for HTTPS¶

Create a DNS record for your server
Create a PEM encoded, SSL Private Key
Configure SSL on the Alation side:
- Obtain the SSL certificate
- Configure SSL
- Handle redirection of HTTP requests to HTTPS
- Set base URL
- Redeploy the configuration
- Restart the services

Obtain the SSL Certificate¶

Alation requires:

A PEM encoded, SSL Private Key. The file should begin with one of:

BEGIN PRIVATE KEY

BEGIN RSA PRIVATE KEY

BEGIN ECDSA PRIVATE KEY

A PEM encoded, X509 format SSL certificate signed by the Private Key

The file should begin with BEGIN CERTIFICATE

The file should include the full certificate chain to validate the SSL certificate.

There are two ways to get a certificate:

Have a certificate issued by the Certification Authority used at your company. Work with your IT department to get one.
Use a self-signed certificate. Note that in this case the browser may still display an “insecure connection” warning.

Note

To generate a self-signed certificate, you can use the following command (requires openssl to be installed):

openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout ssl.key -out ssl.crt
See How To Create a Self-Signed SSL Certificate for Apache in Ubuntu 16.04 for details.

To verify that the Subject in the SSL certificate matches the server name, you can run the following command (requires openssl):

openssl x509 -in <path to certificate> -text | grep Subject:

Certificate Chain¶

If the certificate is signed by intermediate CAs, make sure that the SSL certificate you provide to Alation includes the full certificate chain. This step will not be required if the certificate is self-signed as in self-signed certificates the intermediate CA is not present.

If you have separate certificates from each signing authority, you need to create a certificate chain. To concatenate certificates, you can run the following command:

cat <mydomain.crt> <trustedCA1.crt> <trustedCA2.crt> <CARoot.crt> > PublicSSL_cert.crt

For example, an ssl.crt file with intermediate certificate information concatenated into it has the following structure:

-----BEGIN CERTIFICATE-----

<encrypted certificate here>

-----END CERTIFICATE-----

Intermediate CA

-----BEGIN CERTIFICATE-----

<encrypted intermediate CA here>

-----END CERTIFICATE-----

Converting SSL Certificates¶

This section provides information on converting SSL certificate packages to formats that are accepted by Alation. There are several different formats based on the platform you may be using.

Note

For more information about SSL certificates, see:

SSL Shopper

Global Sign

Convert .pem file to a ssl.crt and ssl.key¶

To convert .pem to ssl.crt and ssl.key files, run the following:

openssl x509 -in <your_file>.pem -out ssl.crt
openssl rsa -in <your_file>.pem -out ssl.key

Convert p7b to ssl.crt¶

To convert p7b to ssl.crt:

openssl pkcs7 -print_certs -in <certificate.p7b> -out ssl.crt

Validate the SSL Certificate (Optional)¶

To validate that the format works, you can run the following set of commands:

openssl rsa -in ssl.key -check
openssl x509 -in ssl.crt -check
openssl x509 -in ssl.crt -text -noout | less

Enable SSL¶

Have the SSL certificates prepared. To enable HTTPS on the Alation server:

Confirm that Alation is started:
sudo service alation status

Copy the certificate and the key to the Data disk.

# copy certs to your server
rsync -i <path_to_ssl_dir>/ssl.* <your_instance_ip>:/tmp/
# log in to the Alation server
ssh <your_instance_ip>
# move ssl key and cert to its location on the Alation server
sudo mv /tmp/ssl* /opt/alation/alation/data1/site_data/ssl/

Change ownership to alation and protect the files with permissions:

sudo chown alation:alation /opt/alation/alation/data1/site_data/ssl/ssl.*
sudo chmod 600 /opt/alation/alation/data1/site_data/ssl/ssl.*

To test:

sudo /etc/init.d/alation shell
ls -l /opt/alation/site/ssl/ssl.*

The output will look like:

-rw------- 1 alation alation 8536 Sep 28 17:23 <path_to_ssl_dir>/ssl.crt
-rw------- 1 alation alation 1708 Sep 28 17:22 <path_to_ssl_dir>/ssl.key

From the Alation shell, enable SSL:

#if not in the Alation shell yet
sudo /etc/init.d/alation shell
# enable SSL
alation_conf nginx.use_ssl -s True

Still from the shell, redirect HTTP requests to HTTPS :

alation_conf nginx.redirect_http_to_https -s True
alation_conf nginx.redirect_load_balancer_http_to_https -s False

Update the base URL to reflect SSL:

alation_conf alation.install.base_url -s https://<base_url>

Redeploy the configuration:
alation_action deploy_conf_nginx

Restart NGINX and uWSGI:

alation_action stop_nginx
alation_action start_nginx
alation_supervisor restart web:uwsgi

Disable HTTPS¶

To disable HTTPS:

On the Alation host, enter the Alation shell:
sudo /etc/init.d/alation shell
Disable SSL using alation_conf:
alation_conf nginx.use_ssl -s False

Disable the redirect of HTTP requests to HTTPS:

alation_conf nginx.redirect_load_balancer_http_to_https -s False
alation_conf nginx.redirect_http_to_https -s False

Update the base URL to reflect the change:

alation_conf alation.install.base_url -s http://<base_url>

To apply the changes, redeploy the configuration:
alation_action deploy_conf_nginx

Restart uWSGI and NGINX:

# Restart uWSGI
alation_supervisor restart web:uwsgi
# Restart NGINX
alation_action stop_nginx
alation_action start_nginx

Use Load Balancer¶

Terminate SSL at Load Balancer¶

To use Alation behind load balancer:

On the Alation host server, enter the Alation shell:
sudo /etc/init.d/alation shell

Disable SSL on the Alation server:
alation_conf nginx.use_ssl -s False
Configure the load balancer to forward the following header to Alation: X-Forwarded-Proto: https
Note

If X-Forwarded-Proto header is not set to https, then to avoid the HTTPS redirection loop, set the following flag to True:
alation_conf nginx.redirect_load_balancer_http_to_https -s True
Because SSL gets terminated at load balancer, Alation server is not required to redirect the HTTP request. Set:
alation_conf nginx.redirect_http_to_https -s False

Update the base URL to use https:

alation_conf alation.install.base_url -s https://<base_url>

To apply the changes, redeploy the configuration:
alation_action deploy_conf_nginx

Restart uWSGI and NGINX:

# Restart uwsgi
alation_supervisor restart web:uwsgi
# Restart NGINX
alation_action stop_nginx
alation_action start_nginx

While terminating SSL at load balancer, forward port 443 to 80 on the Alation server.

Note

When using a load balancer, you may want to use <your-alation-instance-URL>/monitor/i_am_alive as a health check. This URL doesn’t require authentication and it returns an http 200 as long as you can hit it.

Terminate SSL at Alation¶

Terminating SSL at Alation while using load balancer is not a recommended practice.

To terminate SSL at Alation,

On the Alation host, enter the Alation shell:
sudo /etc/init.d/alation shell

Enable SSL:
alation_conf nginx.use_ssl -s True
To avoid the HTTPS redirection loop, set the following flag to True if X-Forwarded-Proto header is not set to https:
alation_conf nginx.redirect_load_balancer_http_to_https -s True
Because SSL is not terminated at load balancer, set the Alation server to redirect the HTTP request:
alation_conf nginx.redirect_http_to_https -s True

Update the base URL to include HTTPS:

alation_conf alation.install.base_url -s https://<base_url>

To apply the changes, redeploy the conf:
alation_action deploy_conf_nginx
Restart uWSGI:
alation_supervisor restart web:uwsgi

Restart NGINX

alation_action stop_nginx
alation_action start_nginx

HTTPS¶

Requirements for HTTPS¶

Obtain the SSL Certificate¶

Certificate Chain¶

Converting SSL Certificates¶

Convert .pem file to a ssl.crt and ssl.key¶

Convert p7b to ssl.crt¶

Validate the SSL Certificate (Optional)¶

Enable SSL¶

Disable HTTPS¶

Use Load Balancer¶

Terminate SSL at Load Balancer¶

Terminate SSL at Alation¶

Alation User Documentation PDFs