Installation

Overview

Plug-Back is a prerequsite for Plug-Front and therefore have to be installed first.
For load balancing and failover we may install more then one Plug-Back and Plug-Front.
The first Plug-Back installation must be started with -init argument for generating encryption key, additional Plug-Back installations should be started having environments variables for connection setup to download configuration from an already running Plug-Back (cluster_nodes).

Nginx is a prerequisite for Plug-Front and having both running on the same server will give best performance. In general, any reverse proxy server (nginx, traefik, ambassador, istio, envoy, etc) that supports forward/external authentication could be used by Plug-Front.

Plug-Front and Plug-Back could be running on the same server, but the preferred setup is having Plug-Front in the DMZ and Plug-Back in the internal zone.

In terms of firewall openings, default ports are:

Nginx ==TCP/9090==> Plug-Front
Plug-Front ==TCP/9091==> Plug-Back
Plug-Back <==TCP/9092==> Plug-Back (cluster_nodes)

Plug-Back Primary

Plug-Back primary installation must use the -init argument for regenerating encryption key. Also note that passwords and secrets in configuration file must be clear text and will become encypted on startup.

  • mkdir /opt/plugsso
  • mkdir /opt/plugsso/plug-back
  • copy the plug-back binary to /opt/plugsso/plug-back
  • chmod 755 /opt/plugsso/plug-back/plug-back
  • cd /opt/plugsso/plug-back
  • If we do have a configuration file to be used, this file could now be copied to /opt/plugsso/plug-back/config/config.yaml
  • Start the Plug-Back primary installation: ./plug-back -init
  • Enter “y” on the Continue warning for regenerating new encryption key in database db/plugsso.db
  • If no configuration file found, a default example configuration config/config.yaml will be created, but startup fails because of missing plugback.password
  • Configure the config/config.yaml file according to your needs. plugback.password and plugback.username must be defined and will be used by Plug-Front and Plug-Back cluster nodes for connection. plugback.cluster_nodes configuration must contain the ip-address or fqdn of this plug-back server (note, all remote plug-front and plug-back servers must be able to connect hosts defined in cluster_nodes). Plug-Front and other Plug-Back servers will be using this ip/fqdn for connections on port 9091/9092.
  • Start Plug-Back: /opt/plugsso/plug-back/plug-back

Note, configuration in provided config/config.yaml is just an example that can be used if we are using the nginx example shown in the Configuration description for Nginx (or found at plugin-front in the file config/examples/nginx.conf). plugback password and cluster_nodes must be set. Misc oauth.config.client_id and client_secret cannot be empty and must be set to something to avoid plug-front startup failure. For been able to authenticate misc fqdn/hostnames needs to be corrected. Azure, Google and SCIM Gateway to be configured. smtp also needs to be configured for sending mail e.g. mfa user registration. There are a lot of PlugSSO configurations not included in this example file (using defaults). For full configuration overview, please see the Configuration document.

See simular use case testing at: Test PlugSSO online

Plug-Back Failover

Follow these steps if we already have a runnig Plug-Back primary server and want to install additional Plug-Back servers for load balancing and failover.

  • mkdir /opt/plugsso
  • mkdir /opt/plugsso/plug-back
  • copy the plug-back binary to /opt/plugsso/plug-back
  • chmod 755 /opt/plugsso/plug-back/plug-back
  • cd /opt/plugsso/plug-back
  • export PLUGSSO_PLUGBACK_USERNAME=plugadm
  • export PLUGSSO_PLUGBACK_PASSWORD=password
  • export PLUGSSO_PLUGBACK_CLUSTERNODES=ip-address-to-primary-plug-back-or-fqdn
  • Start Plug-Back: ./plug-back
  • plug-back will now be started, but configuration (config/config.yaml) and database (db/plugsso.db) can’t be found and will therefore be be downloaded from primary Plug-Back according to environment setting PLUGSSO_PLUGBACK_CLUSTERNODES. Note, environment for username, password and cluster_nodes must be correct according to primary plug-back configuration. In case startup fails, check log/plug-back.log for fatal/error messages. When we later on change configuration (and required restart), the version configuration should be increased e.g. from 0 to 0.1 to ensure new configuration will be automatically synchronized to plug-front and plug-back cluster nodes.

Plug-Front

Plug-Front installation sequence:

  • mkdir /opt/plugsso
  • mkdir /opt/plugsso/plug-front
  • copy the plug-front binary to /opt/plugsso/plug-front
  • chmod 755 /opt/plugsso/plug-back/plug-front
  • cd /opt/plugsso/plug-front
  • export PLUGSSO_PLUGFRONT_BACKEND_USERNAME=plugadm
  • export PLUGSSO_PLUGFRONT_BACKEND_PASSWORD=password
  • export PLUGSSO_PLUGFRONT_BACKEND_BASEURLS=https://ip-address-to-primary-plug-back-or-fqdn:9091
  • Start Plug-Back: ./plug-front
  • Plug-Front will now be started, configuration will be downloaded from Plug-Back according to environment setting PLUGSSO_PLUGFRONT_BACKEND_BASEURLS. Note, environment for username, password and baseurls must be correct according to plug-back configuration. In case startup fails, check log/plug-front.log for fatal/error messages. Configuration file config/config.yaml may also be edited/corrected regarding base_urls, password, username and log.level (but will be overridden by any environment settings). After successful startup and download, the config/config.yaml base_urls and version will be updated based on plug-back configuration. When configuration file is in place, environments are not needed unless we want to override what is defined in the file. Plug-Front configuration will be automatically updated when configuration becomes updated on one of the plug-back servers. The version number in this file will correspond with version number defined at plug-back configuration and we then can verify that Plug-Front is up-to-date. username, password and log.level will not be overwritten by plug-back configuration.

Note, installation creates static and templates folders having files used by the pre-logion authentication user interface. These files and templates may be modified according to your need, and existing files will not be overwritten by plug-front startup.

Nginx

Nginx reverse proxy needs to be installed preferably on the same server as Plug-Front.
For download and installation of Nginx please see: Linux and Windows

Example Ubuntu installation:

sudo apt update
sudo apt install nginx

Basics linux:

sudo systemctl status nginx
sudo systemctl start nginx
sudo systemctl stop nginx
sudo systemctl reload nginx
sudo systemctl restart nginx

Basics windows:

start nginx.exe
nginx -s stop
nginx -s reload

Configuration file:

Windows: `path-nginx`\conf\nginx.conf
Linux:  /etc/nginx/nginx.conf

Configuration example: See Configuration - Nginx

SCIM Gateway

SCIM Gateway can be used for customized authentication and authorization logic

For installation see: SCIM Gateway
For configuration see: PlugSSO SCIM Gateway

Automatic startup

Automatic Plug-Back startup on Linux

  1. create service file: vi /etc/systemd/system/plug-back.service
    content:
    [Unit]
    Description=plug-back
    After=network.target

    [Service]
    Type=simple
    ExecStart=/opt/plugsso/plug-back/plug-back

    [Install]
    WantedBy=multi-user.target
  1. Activate start on server boot:
    sudo systemctl enable plug-back

Basics plug-back:

sudo systemctl start plug-back
sudo systemctl restart plug-back
sudo systemctl stop plug-back

Automatic Plug-Back startup on Windows

Start Windows Task Scheduler (taskschd.msc), right click on “Task Scheduler Library” and choose “Create Task”

General tab:  
-----------
Name = Plug-Back
User account = SYSTEM
Run with highest privileges

Triggers tab:
-------------
Begin the task = At startup

Actions tab:
------------
Action = Start a program
Program/script = c:\plugsso\plug-back\plug-back.exe

Settings - tab:
---------------
Stop the task if runs longer than = Disabled (greyed out)

Verification:

  • Right click task - Run, verify process plug-back.exe can be found in the task manager (not the same as task scheduler). Also verify logfiles logs\plug-back.log
  • Right click task - End, verify process plug-back.exe have been terminated and disappeared from task manager
  • Reboot server and verify Plug-Back have been automatically started

Automatic Plug-Front startup on Linux

  1. create service file: vi /etc/systemd/system/plug-front.service
    content:
    [Unit]
    Description=plug-front
    After=network.target

    [Service]
    Type=simple
    ExecStart=/opt/plugsso/plug-front/plug-front

    [Install]
    WantedBy=multi-user.target
  1. Activate start on server boot:
    sudo systemctl enable plug-froont

Basics plug-front:

sudo systemctl start plug-front
sudo systemctl restart plug-front
sudo systemctl stop plug-front

Automatic Plug-Front startup on Windows

Start Windows Task Scheduler (taskschd.msc), right click on “Task Scheduler Library” and choose “Create Task”

General tab:  
-----------
Name = Plug-Front
User account = SYSTEM
Run with highest privileges

Triggers tab:
-------------
Begin the task = At startup

Actions tab:
------------
Action = Start a program
Program/script = c:\plugsso\plug-front\plug-front.exe

Settings - tab:
---------------
Stop the task if runs longer than = Disabled (greyed out)

Verification:

  • Right click task - Run, verify process plug-front.exe can be found in the task manager (not the same as task scheduler). Also verify logfiles logs\plug-front.log
  • Right click task - End, verify process plug-front.exe have been terminated and disappeared from task manager
  • Reboot server and verify Plug-Back have been automatically started