logo fenix

FURMS architecture overview

FURMS system consists of two services:

  • Unity-IdM: an existing open source software which covers:

    • authentication

    • user provisioning

    • groups management (with persistence)

    • user management including user attributes and group memberships (with persistence)

    • notifications functionality

  • The FURMS service

    • a complete UI for the FURMS users (only sign-in and sign-up views will be hosted on Unity)

    • communities, projects and sites management,

    • control and assignment of budgets

    • accounting

    • external REST API

The administrative control of the FURMS system is available via the dedicated FURMS service UI, however some rarely used system administration actions will require the use of Unity-IdM administrative UI. An example of such action is the modification of email message templates used for notifications sent by FURMS. Note that only the FURMS administrators will need to use Unity-IdM administrative UI, other types of users (e.g. site admins or community admins) will not have to use it.

The following figure shows high level overview of the interactions between FURMS system and FENIX infrastructure.

High level overview of the interactions between FURMS system and FENIX infrastructure

Unity-IdM

Unity-IdM is an existing software providing authentication and user management service. Unity-IdM allows its users to enable authentication to their web services using various protocols, with different configurations for many relaying parties. The actual authentication can be performed using the built-in, feature-rich users database or can be delegated to one of supported upstream identity providers.

The information obtained from upstream IdPs can be flexibly translated and merged with the local database (if needed) and re-exported using other protocols. Unity-IdM can authenticate both locally and using SAML and Oauth authentication protocols. Authentication can be performed against locally stored credentials or delegated to external service.

The following figure shows the high level Unity-IdM architecture

High level Unity-IdM architecture

More of the general information on Unity can be found at https://unity-idm.eu web page, while the reference documentation is available at the https://www.unity-idm.eu/support/ sub-page.

FURMS installation from scratch

This section describes how to install the FURMS system from scratch. The installation is done through Ansible scripts and covers installation of FURMS service as well as Unity-IdM service. Both services work closely together.

Prerequisites

Hardware requirements

Both services can be installed on a single machine, or on two separate ones. As the communication between the servers is intensive a single host installation may be preferred.

  • Disk space: installation of both services together requires less than 1GB of disk space. It is advised to reserve significantly more in order to preserve log files and multiple updates (each is installed in separate directory by default).

  • RAM: minimum of 1GB of free memory per each service must be reserved. It is advised to provide 4GB per service in order to handle heavy load.

  • CPU: there are no strict restrictions, however at least 2 cores per service are advised. Production environment with many users may make good use of a more powerful machine.

Java

FURMS system requires Java Runtime Environment. The version 11 is the supported Java version. Install JRE on host(s) where services are going to be run.

Ansible

Install Ansible tooling on the host which will control FURMS system through scripts. Follow the Ansible installation guide.

Database

Install any recent version of PostgreSQL on the host of your choice. The setup of database requires creation of two databases each with a separate role (user) which is able to connect to the database. One database is utilized by FURMS service and the other for Unity-IdM. This information will be used later on in the Ansible group variable file to setup databases configuration during installation.

Broker

Install any recent RabbitMQ broker with support for AMPQ 0.9.1. The broker setup requires:

  • configuration of the TLS in order to enable encryption on the protocol level,

  • definition of the RabbitMQ virtual host utilized for the FURMS purposes,

  • definition of the client user name and password with a connection rights to FURMS virtual host, and privileges to provision queues within this virtual host.

The virtual host name, privileged client user name and a password, as well as public CA certificate which was used to sign credential for the broker are used later on in the Ansible group variable file to setup broker connection during installation.

The broker service is considered as the infrastructure resource, however for demonstration purposes and ease of configuration, below is an example of rabbitmq.conf file with TLS support turned on. 
listeners.ssl.default = 5671

ssl_options.cacertfile = /etc/rabbitmq/certs/ca_certificate.pem
ssl_options.certfile = /etc/rabbitmq/certs/server_certificate.pem
ssl_options.keyfile = /etc/rabbitmq/certs/server_key.pem
ssl_options.password = <put-keyfile-password>
ssl_options.fail_if_no_peer_cert = false
ssl_options.verify = verify_none
ssl_options.versions.1 = tlsv1.2

Please refer to the RabbitMQ TLS Support guide for more informations.

Connection setup for site’s local agent

The communication between FURMS and particular site is done through two queues which are declared by FURMS when FENIX administrator creates a site. Dedicated queue names consists of site’s identifier and a special suffix:

  • <siteid>-site-pub - queue is used by site to publish messages to FURMS

  • <siteid>-furms-pub - queue is used by FURMS to publish message to the site

The site’s identifier is visible on Site administrator’s Settings page as 'Site Id'. When the Site Id is e.g. ygmr6, then the created queues names are:

  • ygmr6-site-pub

  • ygmr6-furms-pub

From Site’s point of view, broker administrator must define the client user name and password with a connection rights to FURMS virtual host, and privileges to:

  • write messages to <siteid>-site-pub queue,

  • read messages from <siteid>-furms-pub queue,

In order to setup a connection from site agent to broker, the aforementioned user name and password is required as well as the public CA certificate which was used to sign credential for the broker. This information needs to be handed over to the local site administrator in order to setup encrypted and authorized connection to FURMS through the broker.

Installation best practices

There are two recommended configurations of FURMS system that can be used to install the services:

  • behind HTTP proxy

  • exposed directly

Depending upon which is selected, there are some ramifications on the configuration to be made.

HTTP proxy configuration

It is assumed that in this configuration the proxy has installed the certificates signed by legitimate authorities. In this case the FURMS system can be equipped with self-signed certificates. One pair of PKI credential for Unity-IdM and the other for FURMS Service.

Note that for such configuration the truststore needs to be carefully prepared. The general rule of a thumb is that it must contain at least:

  • the public CA certificate which is at the top of the certificates chain used to sign Unity-IdM credential,

  • the public CA certificate which is at the top of the certificates chain used to sign Central IdP credential.

Services exposed directly

In this configuration, both Unity-IdM as well as a FURMS service must be equipped with PKI credentials signed by legitimate authorities. The truststore can be configured to use the system one. On RHEL like system the default place of a trustore is /etc/pki/java/cacerts, and on Ubuntu like systems /etc/ssl/certs/java/cacerts.

In both setup cases, there are configuration options in the Ansible group variables file, that need to be properly filled according to your infrastructure setup *.advertisedHost, unity.proxyCount. Please refer to the description of the variables in the following sections.

FURMS devops tools installation utility

In order to install the latest released FURMS devops tooling, use the FURMS devops tools installation utility. Enter to the directory of your choice and run the following commands:

> export FURMS_ROOT_DIR=/home/furms-app/staging
> curl -L https://raw.githubusercontent.com/unity-idm/furms-devops/main/install-tooling/install_furms_devops_tooling.py -o $FURMS_ROOT_DIR/install_furms_devops_tooling.py
> chmod +x $FURMS_ROOT_DIR/install_furms_devops_tooling.py

FURMS Ansible scripts

Use the FURMS devops tools installation utility to install the latest Ansible scripts. Enter to the directory where the utility was installed, and execute the following:

> cd $FURMS_ROOT_DIR
> ./install_furms_devops_tooling.py
Installation of latest FURMS devops tools into /home/furms-app/staging
Command finished successfully
> ls -l
lrwxrwxrwx. 1 furms-app furms-app   32 01-16 12:27 furms-devops-tooling -> furms-devops-tooling-1.0.0
drwxr-xr-x. 5 furms-app furms-app 4096 10-28 15:36 furms-devops-tooling-1.0.0
-rwxr-x---. 1 furms-app furms-app 3057 01-16 12:25 install_furms_devops_tooling.py

The aforementioned tool can be run at will, and the consecutive executions will update the FURMS Ansible scripts to the latest version.

Setup Ansible configuration files

Create the inventory and group variables files in the $FURMS_ROOT_DIR directory (where FURMS devops tooling was installed). You can base on the example files that are delivered with the Ansible tooling.

With regards to the inventory file, depending upon whether you are going to install FURMS system components on local machine, or on remote hosts, there are two different example files prepared. If you intend to install components on a local machine, then use inventory.local file in the example below, otherwise use inventory.remote to have installation performed on remote hosts.

> cd $FURMS_ROOT_DIR
> cp furms-devops-tooling/local-cfg-sample/inventory.local inventory  # or inventory.remote
> mkdir -p group_vars
> cp furms-devops-tooling/local-cfg-sample/group_vars/all.yml group_vars/

The following files should be copied to the current directory:

  • inventory

  • group_vars/all.yml

Inventory

Ansible can work against multiple machines in your infrastructure. It does this by selecting systems listed in Ansible’s inventory file. Make appropriate changes to the copied example of inventory file.

Group vars

All of the FURMS deployment settings are configured in the all.yml Ansible group file. The example of this file can be found now in $FURMS_ROOT_DIR/group_vars/all.yml file.

The devops tooling provides also a file that is filled out with example values. A file sample demonstrates the configuration of FURMS system behind a proxy, please see $FURMS_ROOT_DIR/furms-devops-tooling/local-cfg-sample/group_vars/all.yml.behind-proxy for a reference.

The following table provides description of all configuration options.

Property name Type Description

installDir

string

Directory name where FURMS services will be installed e.g. "{{inventory_dir}}/services"

furmsVersion

string

Version of released FURMS software e.g. "1.0.0"

trustStore

FURMS system trustrore used by FURMS service as well as Unity-IdM. It must contain at least:

  • the public CA certificate which is at the top of the certificates chain used to sign Unity-IdM credential.

  • the public CA certificate which is at the top of the certificates chain used to sign Central IdP credential.

  • the public CA certificate which is at the top of the certificates chain used to sign Broker credential.

trustStore.file

filesystem path on Ansible management host

The JKS format keystore path.

trustStore.password

string

The password of the keystore type truststore

--- Unity-IdM configuration ---

unity.host

string

The hostname or IP address for HTTP connections.

unity.port

integer [0-65535]

The HTTP port to be used.

unity.advertisedHost

string

The hostname or IP address (optionally with port), which is advertised externally. Examples: login.unity.com or login.unity.com:8443. If host is not advertised externally this value must be set to the unity.host:unity.port setting.

unity.initialAdminUsername

string

Username of the FENIX administrator to be installed in the system upon first installation. This is also the initial Unity-IdM administrator.

unity.initialAdminPassword

string

Password of the FENIX & Unity-IdM administrator to be installed to the empty database.

unity.proxyCount

integer [0 - 32]

If set to 0 then it is assumed then Unity-IdM server is not behind a proxy. Otherwise the number should specify the number of (local, trusted) proxies that are protecting the server from the actual clients. In effect the assumed client IP will be taken from the X-Forwarded-For header, stripping the trailing ones from intermediary proxies. Note that only proxy servers setting X-Forwarded-For are supported.

unity.pki.keyStore.file

filesystem path on Ansible management host

Credential location.

unity.pki.keyStore.type

[jks, pkcs12]

Format of the credential.

unity.pki.keyStore.password

string

Password required to load the credential. Keystore must use the same key password as the keystore password.

unity.db.host

string

The hostname or IP address (optionally with port) that points to the PostgreSQL instance e.g. localhost:5432

unity.db.dbName

string

PostgreSQL database name used by Unity-IdM instance.

unity.db.username

string

Unity-IdM database username.

unity.db.password

string

Unity-IdM database password.

unity.cIdP

Configuration that contains the Central IdP OAuth client’s credentials used on Unity-IdM side for authentication via Central IdP.

The redirect URL configured at Central IdP OAuth client side should be set to https://{unity.advertisedHost}/unitygw/oauth2ResponseConsumer

unity.cIdP.clientId

string

Client identifier, obtained during Unity’s registration at the Central IdP.

unity.cIdP.clientSecret

string

Client secret, obtained during Unity’s registration at the Central IdP.

unity.cIdP.discoveryEndpoint

string

Central IdP OpenID Connect Discovery endpoint address, for production environment https://central-proxy.fenix-ri.eu/.well-known/openid-configuration and for the acceptance environment https://proxy.acc.fenix.eduteams.org/.well-known/openid-configuration

--- FURMS service configuration ---

furmsServer.host

string

The hostname or IP address for HTTP connections.

furmsServer.port

integer [0 - 65535]

The HTTP port to be used.

furmsServer.advertisedHost

string

The hostname or IP address (optionally with port), which is advertised externally. Examples: login.unity.com or login.unity.com:8443. If host is not advertised externally this value must be set to the furmsServer.host:furmsServer.port setting.

furmsServer.pki.keyStore.file

filesystem path on Ansible management host

Credential location.

furmsServer.pki.keyStore.type

[jks, pkcs12]

Format of the credential.

furmsServer.pki.keyStore.password

string

Password required to load the credential. Keystore must use the same key password as the keystore password.

furmsServer.db.host

string

The hostname or IP address (optionally with port) that points to the PostgreSQL instance e.g. localhost:5432

furmsServer.db.dbName

string

PostgreSQL database name used by FURMS service instance.

furmsServer.db.username

string

FURMS service database username

furmsServer.db.password

string

FURMS service database password

furmsServer.preSharedKeys.cIdP

The cIdP key is defined by FURMS administrator. The information entered here setup the base authentication credentials, used to access the FURMS REST API exposed for Central IdP.

furmsServer.preSharedKeys.cIdP.username

string

Username for Central IdP REST API credential

furmsServer.preSharedKeys.cIdP.password

string

Password for Central IdP REST API credential

furmsServer.broker

Configuration options to setup connection with the RabbitMQ.

furmsServer.broker.host

string

The hostname or IP address that points to the RabbitMQ instance.

furmsServer.broker.port

integer [0-65535]

RabbitMQ port to which to connect.

furmsServer.broker.username

string

RabbitMQ user to use when connecting.

furmsServer.broker.password

string

RabbitMQ password for this user

furmsServer.broker.virtualHost

string

RabbitMQ virtual host name to which to connect.

furmsServer.ui

Configuration of user interface related features.

furmsServer.ui.maxSessionInactivityInSeconds

integer (default 1800)

Optional value, that defines number of seconds where users inactivity cases the automatic logout operation from FURMS UI.

furmsServer.ui.secondsBeforeShowingLogoutWarning

integer (default 120)

Optional value that, defines number of seconds before the user is shown the warning message about automatic logout from FURMS UI.
Any reconfiguration of aforementioned options in the case of FURMS installation from scratch, is currently supported only by reinstallation from scratch. You have to update the settings, drop databases (if stack was already started), and install FURMS stack again.

Install FURMS stack

Once configuration is finished, the following command will install the Unity-IdM as well as FURMS service:

> cd $FURMS_ROOT_DIR
> ansible-playbook -i inventory furms-devops-tooling/install-stack.yml

After installation the services are available in directory pointed out in installDir property defined in $FURMS_ROOT_DIR/group_vars/all.yml file.

FURMS system minor update procedure

Minor FURMS updates are performed whenever a newly installed software version differs only with the last number when compared to the currently installed one. Database backup is advised, however in the minor update case the risk is minimal - revision releases typically do not introduce database content migrations. The following steps provide example how to update the FURMS service into 1.0.1 version, assuming 1.0.0 is installed:

  • [Stop FURMS stack]

  • Install minor update:

    • enter the $FURMS_ROOT_DIR directory,

    • update the furmsVersion property defined in group_vars/all.yml file, change its value to 1.0.1

    • execute: ansible-playbook -i inventory furms-devops-tooling/install-minor-update.yml

  • [Start FURMS stack]

Upgrade from 1.0 to 2.0 release

This section describes the FURMS 2.0 release installation steps basing on 1.0 release configuration. Note that it is required to drop the databases for FURMS service as well as for Unity-IdM, however all of the Ansible related configuration shall be reused.

  • Install and configure RabbitMQ broker according to guidelines from this section.

  • Drop PostgreSQL database used by Unity-IdM instance.

  • Drop PostgreSQL database used by FURMS service instance.

  • Update the FURMS Ansible scripts to the latest version, execute ./install_furms_devops_tooling.py in the directory where tooling was installed.

  • Update the trustStore file: add the public CA certificate which is at the top of the certificates chain used to sign Broker credential.

  • Update your existing groups_var/all.yml Ansible configuration file, add the following configuration:

    broker:
    host:                -- set -- me --
    port:                -- set -- me --
    username:            -- set -- me --
    password:            -- set -- me --
    virtualHost:         -- set -- me --
ui:
    maxSessionInactivityInSeconds:     -- set -- me -- #optional: default 1800
    secondsBeforeShowingLogoutWarning: -- set -- me -- #optional: default 120

  • Install FURMS stack

Operating the system

Starting FURMS stack

Once FURMS stack has been installed, the following command starts the FURMS stack - Unity-IdM server as well as FURMS service:

> cd $FURMS_ROOT_DIR
> ansible-playbook -i inventory furms-devops-tooling/start-stack.yml

Stopping FURMS stack

At any time the FURMS stack can be stopped using the following command:

> cd $FURMS_ROOT_DIR
> ansible-playbook -i inventory furms-devops-tooling/stop-stack.yml

Runtime directories structure, log files

The following listing shows example directory structure after FURMS installation:

./20210211-214739
./20210211-214739/furms-server -> furms-server-1.0.0
./20210211-214739/furms-server-1.0.0
./20210211-214739/furms-server-1.0.0/furms-server
./20210211-214739/unity -> unity-server-3.4.3
./20210211-214739/unity-server-3.4.3
./20210211-214739/unity-server-3.4.3/conf
./20210211-214739/unity-server-3.4.3/bin
./20210211-214739/unity-server-3.4.3/webContents
./20210211-214739/unity-server-3.4.3/data
./20210211-214739/unity-server-3.4.3/workspace
./20210211-214739/unity-server-3.4.3/extra
./20210211-214739/unity-server-3.4.3/lib
./20210211-214739/unity-server-3.4.3/conf-orig
./current -> 20210211-214739
./logs
./workspace

The workspace/ directory can be ignored, it contains temporary installation data. The current symlink points to the currently active revision. It is especially relevant when there are more than one installation. There is also logs directory that contains log files from both, FURMS service as well as Unity-IdM.

Inside the current/ directory there are both services installed. The runtime data like PIDs and other can be found there.

Note that it is not advised to perform reconfigurations in the installation directories. Such changes will be lost during subsequent update with use of Ansible.

Authentication to Unity console

Access to Unity administration console should not be in general required for running FURMS, it may be however convenient to diagnose problems or to perform advanced configuration actions.

Unity console is available at the configured address of Unity server: https://{{unity.advertisedHost}}/console.

Login credentials are set to the ones from Ansible configuration: {{unity.initialAdminUsername}} and {{unity.initialAdminPassword}}.