Skip to main content
Version: 24.3

Enabling SSL/TLS for Agility Connect

Overview​

This article describes the process of configuring the Nginx web server as front end proxy for Agility Connect to serve as a SSL termination endpoint.

Even though Agility Connect supports SSL termination, Digital.ai Agility now recommends using Nginx for SSL termination because of the widely documented options and supported features.

Install Nginx​

Install Nginx at least version 1.4. The following directions can be used as an example but may differ depending on your flavor and version of Linux.

Then install Nginx for RHEL...

sudo yum install -y nginx

Or Ubuntu...

sudoapt-get install -y nginx

Configure SSL Certificate and Key Files​

Gather the required SSL certificate and key files as needed. Place these files in the following directories.

For Ubuntu, place under the /etc/ssl/certs and /etc/ssl/private directories respectively. For RHEL these directories are /etc/pki/tls/certs and /etc/pki/tls/private. Take note of the paths and update the example Nginx config file below.

In the sample Nginx config file below, these files are named agilitysync.crt and agilitysync.key.

Update the Nginx Config File​

The code below will create an Nginx config file in the proper directory for RHEL, /etc/nginx/conf.d/default.conf. This directory is different for other flavors or Linux. For example in Ubuntu this file would be /etc/nginx/sites-enabled/default. Change in the script below as appropriate.

Make note the places in the example where the outward facing IP address 54.210.180.147 is used. This should be replaced with the address (FQDN or IP address) that the user web client uses to access Agility Connect.

The ssl_ciphers and ssl_protocols settings below can be customized to enable (or disable) as necessary to meet the needs of internal IT security requirements.

The following will serve both the Agility Connect web server and websocket server on the same port (443). Customize as appropriate.

sudo tee /etc/nginx/conf.d/default.conf > /dev/null << 'EOF'
server {
listen 443 default_server;
listen [::]:443 default_server ipv6only=on;
server_name localhost;
ssl on;
ssl_certificate /etc/pki/tls/certs/agilitysync.crt;
ssl_certificate_key /etc/pki/tls/private/agilitysync.key;
ssl_session_timeout 15m;
ssl_protocols TLSv1.2;
ssl_ciphers 'EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH';
ssl_prefer_server_ciphers on;
location /sub {
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $remote_addr;
proxy_set_header Host $host;
proxy_pass http://127.0.0.1:8083;
proxy_redirect ws://54.210.180.147/ wss://54.210.180.147/;
# WebSocket support (nginx 1.4)
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_send_timeout 3600;
proxy_read_timeout 3600;
}
location / {
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $remote_addr;
proxy_set_header Host $host;
proxy_pass http://127.0.0.1:8080;
proxy_redirect http://54.210.180.147/ https://54.210.180.147/;
proxy_redirect http://localhost/ http://localhost:8080/;
}
location ~ /\.ht {
deny all;
}
}
server {
listen 80 default_server;
server_name localhost;
return 301 https://$host$request_uri;
}

EOF

Bind Agility Connect to Local Ports Only​

In this setup, Nginx will act as the SSL / TLS termination point and will serve as a proxy forwarding service to the Agility Connect webserver and websocket server. This will be transparent to the end user. However, to make sure that Agility Connect is unable to serve external requests without them first passing through Nginx, the follow setting need to further be made.

Make sure to disable SSL on both the Agility Connect webserver and websocket (messagehub) server. This is either done in the System Settings web config interface in Agility Connect setting "UI SSL" and "MessageHub SSL" to "false". If these settings were made in the /etc/agilitysync/agilitysync.yaml file, they can be turned off there. The local yaml file overrides like settings in the UI / database. The specific config file settings are as follows: ui_use_ssl, msghub_use_ssl

ui_use_ssl: false
msghub_use_ssl: false

The msghub_external_url and ui_external_url will need to be set either in the system settings or yaml file in the following format:

msghub_external_url:wss://54.210.180.147
ui_external_url:https://54.210.180.147

These corresponding settings in the System Settings are "UI URL (External)" and "MessageHub URL (External)".

To force Agility Connect to serve only to local requests and not listen to the outward facing socket, set the following settings to 127.0.0.1: MessageHub Bind Address, UI Bind Address or in the yaml file: msghub_bind_address, ui_bind_address

ui_bind_address: 127.0.0.1
msghub_bind_address: 127.0.0.1

Once the settings are made, restart the Agility Connect services:

as-restart-services

and reload Nginx configurations:

sudo nginx -s reload

or restart the service:

Ubuntu
sudo service nginx restart

RHEL
sudo /etc/init.d/nginx restart

Now test logging into Agility Connect on port 443.

Troubleshooting​

First make sure Agility Connect is serving locally on ports 8080 and 8083:

curl -vvLk http://127.0.0.1:8080

(should response with html)

curl -vvLk http://127.0.0.1:8083

(should respond with text " Agility Connect Message Hub")

If either of those do not respond, check the Agility Connect log files in /var/agilitysync/log.

Next, check the nginx log files in /var/log/nginx, starting with error.log.

If the following line shows in the error.log, try disabling SELinux or check the local firewall.

2017/01/18 13:07:31 [crit] 27231#27231: *13 connect() to 127.0.0.1:8080 failed (13: Permission denied) while connecting to upstream, client: 98.118.251.108, server: localhost, request: "GET / HTTP/1.1", upstream: "http://127.0.0.1:8080/", host: "54.210.180.147"

Any other services that send webhooks or commit data into Agility Connect will also need to be changed. Typical systems that will need to change their Agility Connect urls would be source code management solutions (Example: GitLab, Bitbucket, GitHub, and so on) and ALM solutions (Example: Digital.ai Agility, Jira, and so on).