FURMS System Administrator Manual

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.

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

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 a minimal supported one. 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.

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

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.
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.
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
preSharedKeys.cIdP	Defines the information to setup the base authentication credentials, used to access the FURMS REST API exposed for Central IdP.
preSharedKeys.cIdP.username	string	Username for Central IdP REST API credential
preSharedKeys.cIdP.password	string	Password for Central IdP REST API credential

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.

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.

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

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

preSharedKeys.cIdP

Defines the information to setup the base authentication credentials, used to access the FURMS REST API exposed for Central IdP.

preSharedKeys.cIdP.username

string

Username for Central IdP REST API credential

preSharedKeys.cIdP.password

string

Password for Central IdP REST API credential

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]

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}}.