How to Configure a Reverse Proxy in Front of SAS Viya Web Applications
You may have noticed that the SAS Viya 3.4 administration guide has been recently updated with new information about how to configure an external reverse proxy in front of SAS Viya web applications. Maybe you already deployed a reverse proxy to access Viya, and are wondering why this recent addition. Given the right conditions, maybe yes, your existing setup is already fine. But if you want to be in a supported environment, it's better to verify that all requirements are met.
A previous article describes how Apache HTTP Server is used to route both external and internal connections to active microservices ( including web applications), using SAS Configuration Server for service discovery. Here, we dig deeper into how that relates to an external reverse proxy and what changes are required to get a fully functional environment.
Internal and external routes
When the sas-httpproxy microservice starts, it registers two "logical services" in the SAS Configuration Server:
- viya - this is the "external facing" route
- httpd - this is the "internal facing" route
Select any image to see a larger version.
Mobile users: To view the images, select the "Full" version at the bottom of the page.
The picture above shows an external connection (red arrows) from a browser proxied through the Apache HTTP Server to reach SAS Studio 5. SAS Studio itself then opens an internal connection (blue arrows), for example to talk to the SASLogon microservice, and this connection is proxied as well.
By default sas-httpproxy registers both services with the same address - using "hostname -f" of the machine where it is running. It also configures the SAS Configuration Server to perform health checks for both services.
You can verify the addresses registered for these services with the following code on any machine part of the Viya deployment:
. /opt/sas/viya/config/consul.conf
export CONSUL_TOKEN=$(sudo cat /opt/sas/viya/config/etc/SASSecurityCertificateFramework/tokens/consul/default/client.token)
/opt/sas/viya/home/bin/sas-bootstrap-config catalog serviceurl viya
/opt/sas/viya/home/bin/sas-bootstrap-config catalog serviceurl httpd
Let's expand the previous view to include the backend servers that talk to microservices: CAS and the Launcher Server.
- Services that create external links, such as Report Distribution, use the URL associated with viya. (red dotted line)
- Services that need an internal connection use the URL registered for httpd. (blue line)
- The Launcher Server uses the URL registered in another property, sas-services-url; if that is undefined, it defaults to httpd. (black dotted line)
- CAS does not use any of that: it relies on its own set of properties, which, by default, also correspond to the same URL registered for httpd. (black dotted line)
Adding an external proxy
After deploying an external proxy in front of the Viya environment, the view changes again:
The good news is that Viya uses relative URLs. This means that, when end-users enter the address of the front-end proxy in their browser, it is preserved for all browser navigation and all their connections use that route. Many times, this simply works. To be sure that it always works, the administration guide provides the following additional steps:
- On the external reverse proxy, set the X-Forwarded-Proto and X-Forwarded-Port headers to the protocol and port that the client is using to connect to the external reverse proxy.
- From the SAS Viya internal Apache HTTP server machine, comment out the X-Forwarded-Proto and X-Forwarded-Port lines in the petrichor.conf file as follows:
-
a. Locate the petrichor.conf file according to the platform used:
Unix /etc/http/conf.d Suse Linux /etc/apache2/conf.d Windows C:\ProgramData\SAS\Viya\etc\httpd\conf.d - b. Make a backup copy of the petrichor.conf file.
-
c. Locate the following lines in the petrichor.conf file:
# Default the X-Forwarded-Proto header to http RequestHeader set X-Forwarded-Proto http # Set the X-Forwarded-Proto header if request is over HTTPS RewriteCond "%{HTTPS}" "on" RewriteRule ^.*$ - [ENV=HTTPS:true] RequestHeader set X-Forwarded-Proto https env=HTTPS RequestHeader set X-Forwarded-Port 443 env=HTTPS -
d. Comment out these lines so that they appear as follows:
# Default the X-Forwarded-Proto header to http #RequestHeader set X-Forwarded-Proto http # Set the X-Forwarded-Proto header if request is over HTTPS #RewriteCond "%{HTTPS}" "on" #RewriteRule ^.*$ - [ENV=HTTPS:true] #RequestHeader set X-Forwarded-Proto https env=HTTPS #RequestHeader set X-Forwarded-Port 443 env=HTTPS
-
- Start (or restart) the SAS Viya internal Apache HTTP Server.
Some requirements for this to work are:
- The external reverse proxy must use HTTPS (just like the internal one).
- The external reverse proxy must forward requests through the SAS Viya internal Apache HTTP Server without changing the URL path.
Additional configuration
With this first change, end-users routes should be OK, but that may not be enough. Viya components may not be aware of the front-end proxy: addresses that are created by the platform may keep pointing to the Viya Apache HTTP server, bypassing the front-end proxy (see for example the red dotted line in the above picture).
To have all external connection come through the external proxy, an additional step may be required : the viya service registration should be modified to point to the external proxy.
As a side effect, the SAS Configuration Server will start monitoring the external proxy. After the change, impacted services should be restarted.
To point the viya service to the external proxy, set the following properties in the SAS Configuration Server:
config/viya/sas.httpproxy.external.hostname = 'reverseproxy.viya.customer.com'
config/viya/sas.httpproxy.external.port = '443'
This can be done :
- before the deployment, specifying the properties in the sitedefault.yml file
- post-deployment, by loading the properties with the sas-bootstrap-config CLI as follows:
. /opt/sas/viya/config/consul.conf
export CONSUL_TOKEN=$(sudo cat /opt/sas/viya/config/etc/SASSecurityCertificateFramework/tokens/consul/default/client.token)
/opt/sas/viya/home/bin/sas-bootstrap-config kv write config/viya/sas.httpproxy.external.hostname reverseproxy.viya.customer.com
/opt/sas/viya/home/bin/sas-bootstrap-config kv write config/viya/sas.httpproxy.external.port 443
After this change, restart the reportdistribution and reportalerts services. For example, on a RHEL 7 system , the commands would be:
sudo systemctl restart sas-viya-reportdistribution-default
sudo systemctl restart sas-viya-reportalerts-defaultFinal considerations
Notice how there is no need to change the configuration of any other components. CAS, the Launcher Server, and most microservices use internal connections, so they keep pointing to the original Viya httpd URL - the address of the internal Apache HTTP Server.
This may not be true for clustered environments, where there are multiple instances of Apache HTTP Server. But that will be the topic of another article.
