Configure HTTPS (Recommended)

Last Updated: September 2022

SSL and TLS are the standard technologies for establishing a secured connection between a web server and a browser. In order to create a secured connection, a certificate and key are needed.

Important

You will need to have assigned a domain name to the server_name field in the NGINX config.

Certbot

Certbot is a tool that automatically administers certificates on websites using Let's Encrypt, a free certificate authority. We recommend using Certbot because it automatically retrieves certificates and updates them regularly. It can also automatically configure NGINX to use the certificates.

1. Install the Snapcraft (CentOS and Ubuntu < 20 only):

   Certbot is distributed with Snapcraft, a universal Linux package manager. Find instructions for installing the Snapcrafed daemon (snapd) on your distribution here: Installing snapd.

2. Update snapd to make sure you have the latest version:

   python

   sudo snap install core
   sudo snap refresh core
   

3. Install Certbot:

   python

   sudo snap install --classic certbot
   

4. Run the certbot command using the NGINX plugin:

   python

   sudo certbot --nginx
   

   Note

   If the certbot command is not recognized as a command, you'll need to link it to /usr/bin:

   python

   sudo ln -s /snap/bin/certbot /usr/bin/certbot
   

5. Follow the on-screen prompts to complete the process of setting up certbot.

6. Review the tethys_nginx.conf to see the changes that certbot made:

   Ubuntu:

   python

   cat /etc/nginx/sites-enabled/tethys_nginx.conf
   

   CentOS:

   python

   cat /etc/nginx/conf.d/tethys_nginx.conf
   

7. Verify that auto-renewal works:

   python

   sudo certbot renew --dry-run
   

That's it! Certbot will take care of automatically updating the certificates from now on. You shouldn't need to run the certbot command again. For additional help with installing and setting up Certbot, see: certbot instructions. Choose Nginx for the first field and either Ubuntu 20 or CentOS 8 for the second field.

Important

If you are using Single Sign On (e.g. Google, Facebook, LinkedIn), there is an additional configuration step that needs to be performed after setting up HTTPS. See Single Sign On and HTTPS.

Manually

Alternatively, you can manually configure HTTPS as follows:

1. Obtain a Certificate

   An SSL certificate can be self-signed for testing but should be obtained from a Certificate Authority for a production installation. Search ssl certificate authorities for a list of providers. Most certificate authorities charge a fee for their services, however you can obtain free certificates from Let's Encrypt. If your instance of Tethys Portal is part of a larger organization website, contact your IT department to determine if an agreement with one of these authorities already exists.

2. Modify NGINX Configuration

   Once a certificate is obtained, it needs to be referenced in the NGINX configuration. The configuration file can be found at <TETHYS_HOME>/tethys_nginx.conf.

   Change the listen port to 443 and enable SSL with the following options:

   python

   server {
       listen   443 ssl;
   
       ssl_certificate    /<path_to_your_ssl_certs>/your_domain_name.pem; # (or bundle.crt)
       ssl_certificate_key    /<path_to_your_ssl_certs>/your_domain_name.key;
       ...
   }
   

   Tip

   If you need your site to be accessible through both secured (https) and non-secured (http) connections, you will need a server block for each type of connection. Simply copy the the server block and paste it below the original server block. Then modify one as show above.

   Important

   HTTPS traffic is expected to go through port 443 instead of port 80. hence the server block above listens on 443 instead of 80. Be sure to update your firewall accordingly if applicable (see: Firewall Configuration).

Single Sign On and HTTPS

If you are using Single Sign On, there is an additional setting you will need to set for Python Social Auth to allow the redirect after login to work properly:

python

tethys settings --set SOCIAL_AUTH_REDIRECT_IS_HTTPS True