Summary

This document will guide you through the steps to enable multi-factor authentication and Single-Sign On for any web-based resource, using PhenixID Authentication Services in combination with Nginx as HTTP reverse proxy.

Overview

User experience

This video showcases the user experience, where Apache Guacamole is the proxied resource . Please note that the MyApps portal can be protected with any sign-in method support by PhenixID Authentication Services.

Architecture

Components

The solution involves several components:

• Nginx (external open source software)
  Provides http proxy functionality.
  • PhenixID Nginx plugin
    Scripts and config needed to provide acccess control and sso
• PhenixID Authentication Services
  Provider of the app portal (Myapps) and the sign-in method(s). Controls the end user authenticated session.
• Proxied resource. The target resource, sitting behind the proxy. The target resource can reside on the same server or on an external server.

Sequence flow

1. End user points browser to PhenixID Authentication Services (PAS) MyApps application (myapps).
   The http requests from the browser to PAS passes through Nginx HTTP reverse proxy.
2. PhenixID Authentication Services request user authentication.
3. The user authenticates (please note that depending on the sign-in method, this might include multiple requests from the browser to PhenixID Authentication Services. This can also be a federated (external) sign-in).
   The http requests from the browser to PAS passes through Nginx HTTP reverse proxy.
4. The PAS Myapps portal generates link(s) to the proxied resources. These links are dynamic for security reasons. (Using the pattern /myapps/sso/x-y-w-z)
5. The user clicks on the proxied resource link.
6. Nginx PhenixID plugin performs backend callback to verify user access to requested resource (=is the session authenticated?)
7. If authenticated -> 8.
8. Browser displays the proxied resource through the dynamic link (/myapps/sso/x-y-w-z).

System Requirements

• Linux server with 2 CPUs and =>8GB RAM
• Internet access from the server (at least during the installation / setup)
• PhenixID Authentication Services installation media (4.0.2 or higher)
• The web resource(s) to be proxied must use relative paths.
  Using absolute paths, proxy rewrite rules must be written and deployed to the Nginx proxy. Please consult the Nginx online documentation for additional assistance.

Instruction

Overview

This document will guide you through the steps to enable multi-factor authentication and Single-Sign on for a web resource protected by a HTTP Reverse Proxy, using PhenixID Authentication Services in combination with Nginx.

The installation instruction below is based on a Linux Ubuntu OS where PAS and Nginx are installed on the same machine.

Please adjust your configuration if you run another Linux distribution and/or run the components on different machines.

PhenixID Authentication Services

Installation

1. Install PhenixID Authentication Services in /opt/phenixid/server/ using these commands:
   sudo apt update
   sudo apt install fonts-dejavu fontconfig
   chmod +x phxid_server_linux_x64_4_0_2.sh
   sudo ./phxid_server_linux_x64_4_0_2.sh
2. Open the file /opt/phenixid/server//bin/start-PhenixID.sh
3. Change the com.phenixidentity.operatingPlattform parameter to appliance:
   JAVA_OPTS=”${JAVA_OPTS} -Dcom.phenixidentity.operatingPlattform=appliance”
4. Save the file
5. Start the server
6. (On PAS 4.0.2, you must patch the system after starting by following this procedure:
   1. Stop the server
   2. Download https://files.phenixid.se/s/iWkMtjTYFdqSfYW/download and unzip it in the /opt/phenixid/server/mods/*pipes*/ folder
   3. Verify that the file /opt/phenixid/server/mods/*pipes*/com/phenixidentity/pipes/valves/jwt/VerifyJWTTokenValve.class was replaced
   4. Start the server

Configuration

Setup the sign-in method(s)

Authentication to MyApps is based on federation (SAML).

1. Login to Configuration Manager.
2. Setup PhenixID Authentication Services as a SAML IdP using one of the Federation scenarios described here. (If the desired authentication method is not provided by a scenario, use the documentation for the SAML authenticator here)
   (If the sign-in methods are hosted on an external SAML Identity Provider, import the SAML Identity Provider metadata to establish trust).

Setup MyApps

1. Login to Configuration Manager.
2. Use Scenarios->Applications->Myapps to configure MyApps.
3. Select which IdP MyApps should use for authentication.
4. (If the sign-in methods are hosted on an external SAML Identity Provider, export the SAML Service Provider metadata for Myapps and send to SAML Identity Provider admin to establish trust).
5. Go to Myapps->Application list
6. Click Add valve
7. Add CreateProxyApplicationValve.
8. Add necessary parameters to the config.
   Example:

Nginx with PhenixID plugin

Installation

1. Connect to the server via SSH
2. Execute these commands to install Nginx
   sudo apt install curl gnupg2 ca-certificates lsb-release
   echo “deb http://nginx.org/packages/ubuntu `lsb_release -cs` nginx” | sudo tee /etc/apt/sources.list.d/nginx.list
   curl -fsSL https://nginx.org/keys/nginx_signing.key | sudo apt-key add –
   sudo apt-key fingerprint ABF5BD827BD9BF62
   sudo apt update
   sudo apt install nginx
   sudo apt-get install nginx-module-njs

Configuration

SSL

1. Setup SSL for https using these commands:
2. sudo mkdir /etc/nginx/ssl
3. openssl req -x509 -nodes -days 730 -newkey rsa:2048 -keyout /etc/nginx/ssl/helios.key -out /etc/nginx/ssl/helios.crt -subj “/CN=myapps.phenixid.se”
   Change myapps.phenixid.se to your domain.
4. cd /etc/nginx/conf.d
5. Download helios.conf file from https://files.phenixid.se/s/cLBWMJxnKoDT82Q/download
   wget https://files.phenixid.se/s/cLBWMJxnKoDT82Q/download
6. mv download helios.conf

Proxy configuration

1. cd /etc/nginx/
2. sudo mkdir locations.d
3. cd locations.d
   
4. Download tar from https://files.phenixid.se/s/cGWDzcRK5PArQfj/download
   wget https://files.phenixid.se/s/cGWDzcRK5PArQfj/download
5. mv download locations.conf.tar
6. tar -xvf locations.conf.tar
7. (If Nginx is running on another machine than PAS, modify the IP-adress value in pas.conf and sso.conf)

Modules and PhenixID plugin

1. cd /etc/nginx/
2. vi /nginx.conf
3. Add this line to the top of the file:
   include /etc/nginx/modules.d/*.conf;
4. Save the file
5. mkdir modules.d
6. cd modules.d
7. Create file ngx_http_js_module.conf
   vi ngx_http_js_module.conf
8. Add this line to the file:
   load_module modules/ngx_http_js_module.so;
9. Save the file
10. sudo mkdir /etc/nginx/scripts
11. cd /etc/nginx/scripts
12. Download file from https://files.phenixid.se/s/GFy5dsfZ8jg83Gd/download.
    wget https://files.phenixid.se/s/GFy5dsfZ8jg83Gd/download
13. mv download sso.js
14. Restart nginx service.
    sudo service nginx restart

Test

1. Browse to your PAS MyApps application
2. Authenticate
3. Click on the link to the proxied resource. Example:
   
4. The proxied web resource should now be displayed in the browser.
   Example:
   

Nginx – tips and tricks

• If the proxied resource is hosted on a separate machine, please make sure that the Nginx server can reach the machine on the configured port (443 for example).
• If the proxied resource is hosted on a separate machine and is targeted with a domain name (for example http://example.org), please verify that Nginx resolves DNS names properly. If not, add a resolver parameter according to: http://nginx.org/en/docs/http/ngx_http_core_module.html#resolver

Troubleshooting

Re-testing

Make sure to logout from PAS and restart the browser before testing again.

Configuration changes

Changing Nginx configuration requires a restart of service.

No response when addressing Myapps

1. Check the nginx configuration and logs (/var/logs/nginx/)
2. Check the PAS configuration (ports) and log (/opt/phenixid/server/logs/server.log)

Unable to login to MyApps

1. Check the federation setup between MyApps and the SAML Identity Provider.
2. Check the PAS log (/opt/phenixid/server/logs/server.log)

Proxied resource displays strange GUI

The web resource probably uses absolute paths for css and links. Change the html code or add rewrite rules to Nginx (https://www.nginx.com/blog/creating-nginx-rewrite-rules/) for proper behavior.