Installing Soffid on your server

Guide to show the installation process os Soffid IAM on your server

Installing IAM Console

Guide to install  IAM Console on your own server

Prerequisites

Installing Soffid IAM solution requires the following requirements:

Video Tutorial

Windows

Linux

Installation

Download

You can download Soffid 3 components from our website Soffid Download Manager

Depending on your platform, you can download the MSI, RPM or DEB version.

IAM Console download.png

As soon as the install-x.y.z.sh file is in your computer, copy the file into a path of your server.

Installing IAM Console

Windows

Open the installation file. It will create the operating system level service and will start it. After some seconds, the installation wizard will be up and running in port 8080.

Linux

We recommend to install the package like:

sudo dpkg -i '/your-path/SOFFID 3 Console-Debian_Ubuntu installer-3.0.0.deb'

You can ckeck the IAM Console service status:

systemctl status soffid-iamconsole.service

Configuration

Then, open the web browser pointing to http://localhost:8080

The wizard will ask for the following information:

The next step, allows you to enter the name and password for the initial Soffid user. You must enter:

Manual Configuration

Configuring service startup

If you are using the RPM, DEB or MSI installers, the service is automatically configured to start up with the computer. If you are using the .tar.gz file, you must enable it manually. Execute these commands as root to start Soffid IAM console service on boot:

ln -fs /opt/soffid/iam-console-3/bin/catalina.sh /etc/init.d/soffid-iamconsole
ln -fs /etc/init.d/soffid-iamconsole /etc/rc2.d/S98soffid-iamconsole
ln -fs /etc/init.d/soffid-iamconsole /etc/rc3.d/S98soffid-iamconsole
ln -fs /etc/init.d/soffid-iamconsole /etc/rc2.d/K10soffid-iamconsole
ln -fs /etc/init.d/soffid-iamconsole /etc/rc3.d/K10soffid-iamconsole

If something is not running as expected, please check the log at:

root@localhost:~# cd /opt/soffid/iam-console-3/logs
root@localhost:/opt/soffid/iam-console-3/logs# less soffid.YEAR-MONTH-DAY.log


Now you can connect IAM Console http://localhost:8080/soffid The first thing you must do is to configure database parameters and admin user. When the console is created, the password for user admin will be valid for 24 hours.



Install Sync server

Guide to install Synchronization server on your own server

Prerequisites

Soffid IAM sync server requires the following requirements:

Video tutorial

Windows

Linux

Installation

Download

First of all, open your favorite browser and open the Soffid Download Manager.

Click on Synchronization server and download the latest version for your OS.

Syncserver download.png

Installing Sync Server

Windows

Open the installation file. It will install the software and will execute the installation wizard.

The installation wizard will ask if it is the first sync server or not.

Linux

sudo dpkg -i '/your-path/SOFFID 3 Sync server-Debian_Ubuntu installer-3.0.0.deb'

The installation wizard will ask if it is the first sync server or not.

Installing the first sync server

Automatic wizard

If you answer Y to the first question, the wizard will ask for the following information:

After checking the database status, the wizard will register the sync server and will create a new certification authority, as well as a digital certificate for the brand new sync server.

Manual wizard

If the wizar is not launched automatically, you should launch it manually. To do that, you must follow the next steps:

1. Stop syncserver service: systemctl stop soffid-iamsync.service

2. Delete previous configuration: rm /opt/soffid/iam-sync/conf/*

3. Launch wizard: /opt/soffid/iam-sync/bin/configure

4. Start synserver service: systemctl start soffid-iamsync.service

The wizard will request about the database configuration:
......
Is this the first sync server in the network (y/n)? y
Database URL (jdbc:....): jdbc:mariadb://localhost/soffid
Database user: ADMIN_USER
Password: xxxxx
This server host name [soffid.my.lab]: localhost
Port to listen to [1760]: 1760
....

Installing the next sync servers

If you answer N to the first question, the wizard will ask for the following information:

The wizard will connect to the sync server and create a sync server connection request. The administrator must open the "My tasks" page and approve the request. Once the request is approved, the wizard will finish.

Running synchronization server in root mode

Sometimes it is necessary to run the sync server in root mode to solve a problem. To do this it is necessary to edit the service, modify some data and finally restart the service.

sudo systemctl edit --full soffid-iamsync
User=root
group=root
protectSystem=false
sudo systemctl restart soffid-iamsync

Manual Configuration

Manual service configuration

If you are using the RPM, DEB or MSI installers, the service is automatically configured to start up with the computer. If you are using the .tar.gz file, you must enable it manually. Execute these commands as root to start Soffid IAM sync server service on boot:

ln -fs /opt/soffid/iam-sync/bin/soffid-sync /etc/init.d/soffid-sync
ln -fs /etc/init.d/soffid-sync /etc/rc1.d/K01soffid-sync
ln -fs /etc/init.d/soffid-sync /etc/rc2.d/S06soffid-sync
ln -fs /etc/init.d/soffid-sync /etc/rc3.d/S06soffid-sync
ln -fs /etc/init.d/soffid-sync /etc/rc4.d/S06soffid-sync
ln -fs /etc/init.d/soffid-sync /etc/rc5.d/S06soffid-sync
ln -fs /etc/init.d/soffid-sync /etc/rc6.d/K01soffid-sync

Note that if you are running Centos, Redhat7 o version higher than Ubuntu 16.04, you should enable the service in systemctl

sudo systemctl enable soffid-sync

Once you have installed and configured Soffid Sync Server as a service, you could manage it with the following operations

service soffid-sync status
service soffid-sync restart
service soffid-sync start
service soffid-sync stop

First synchronisation server configuration

It is not recommended to install the first sync server on the same host where the database is installed.

To configure the server, please execute the following commands:

On Linux:

/opt/soffid/iam-sync/bin/configure -main -hostname [hostname] -port 760 -dbuser [soffid] -dbpass [pass] -dburl [jdbc:mysql://localhost:3306/soffid]

On Windows:

%ProgramFiles%\soffid\iam-sync\bin\configure -main -hostname [hostname] -port 760 -dbuser [soffid] -dbpass [pass] -dburl [jdbc:mysql://localhost:3306/soffid]

User and password must be the ones created during the installation process.

 The hostname value must be a FQDN (fully qualified domain name), for instance, "myhost.mydomain.com"  or in a test environment "syncserver.soffid.lab"

Mind the configuration wizard will refuse to register the sync server if this is not really the first sync server. If you really want to register this sync server as the first one, you must open the sync server management page and remove any already registered sync server.

image-1611041442254.png

Next servers configuration

In order to configure the next server syncservers, a two step process is required: first, a normal user installs and configure the sync server software; next, a Soffid administrator allows the sync server to join the sync servers network.

To perform the next step, you do not need to enter the database credentials. Instead, the primary sync server URL and a Soffid console user name and password are required.

For instance, you can execute:

On Linux:

/opt/soffid/iam-sync/bin/configure -hostname [hostname] -user [user] -pass [pass] -server [https://yourserver:760] -tenant [master]

On Windows:

%ProgramFiles%\soffid\iam-sync\bin\configure -hostname [hostname] -user [user] -pass [pass] -server [https://yourserver:760] -tenant [master]


After executing the command, an approval task will appear in Soffid console. The administrator can take ownership of the task and approve or reject it. After approving the server creation, the server will be configured as a proxy sync server (without database access).

The administrator can open the sync servers configuration page to change the sync server role at any time.

Configure a synchronization server proxy without approval in UI

If you want to bypass the appoval process, there is a configuration setting that allows it:


Thus, you can bypass the standard workflow needed for a sinchronization server to join the synchronization servers security network. Otherwise, the standard approval  workflow will be required.

Renaming a sync server

You can rename any sync server at any time by removing the conf directory and executing the configure process again, but the main sync server is a special case. If you remove the conf directory, the certification authority managed by the main sync server will be lost, and every single sync server will be thrown out of the security domain.

Instead, to reconfigure the main sync server you can execute

On Linux:

/opt/soffid/iam-sync/bin/configure -main -force -hostname hostname -port port -dbuser soffid -dbpass pass -dburl jdbc:mysql://localhost:3306/soffid

On Windows:

%ProgramFiles%\soffid\iam-sync\bin\configure -main -force -hostname hostname -port port -dbuser soffid -dbpass pass -dburl jdbc:mysql://localhost:3306/soffid

User and password must be the ones created during the installation process.

The Soffid installation process changes console setup to reflect the new sync server name

The url connection parameter depends on the database system:


Now you can connect to the IAM console http://localhost:8080/soffid  and chek if Console and Syncserver are connected.



Configure TLS for IAM Console

Introduction

The TLS protection of Soffid IAM Console is applied through the configuration of the Apache TomEE embedded in the installation.

This solution is running under java technology therefore we need a jks file (Java Key Store) or a PKCS#12 file with the information of your certificate.

Once you have the Console installed and your certificate in jks format you can follow this steps to configure it the first time or for an update.

Mind that sometimes, the network encryption algorithm is named SSL, in fact, the configuration file still displays the word SSL. However, SSL protocol is now outdated, and TLSv1.2 is used instead.

Load a PKCS#12 (.PFX) file

There are many standard ways to store and transfer private keys and certificates, but the most common one is the PKCS#12 format. Its main advantage is that it contains, in a single file, both the private key and the public certificate.

To transform the .PFX file to a java key store (.JKS), and can use the next command (you have to adapt it to your system):

keytool -v -importkeystore -srckeystore <YOUR_FILE.PFX> -srcstoretype PKCS12 \
  -destkeystore /opt/soffid/iam-console-3/conf/yourcert.jks \
  -deststoretype JKS \
  -destkeypass 123456 -srcstorepass 1234 -deststorepass 123456

Next, you will be asked for the PFX encryption password. It must be provided to you along the PFX file.

Next, you will be asked (probably twice) for the password to be used to encrypt the .JKS file.  This password must be written down in the server.xml file. At the sample SSL configuration file placed at the top of this page, the sample password is 123456.

Configuration

The configuration file to modify is the following one:

/opt/soffid/iam-console-3/conf/server.xml

It can contain one or more connectors. Uncomment or add the following one, that enables the TLS configuration:


These are the attributes that you have to configure.

Attribute
Comment
port You can choose the standard 443 or another custom port

protocols (inside SSLHostConfig tag) 

sslEnabledProtocols (inside Connector tag)

 You can configure the protocols allowed. For intance,  protocols="TLSv1.3" or sslEnabledProtocols="TLSv1.3"
certificateKeystoreFile The source by default starts from /opt/soffid/iam-console-3/ (the installation directory)
certificateKeystorePassword The password used to encrypt the jks file
certificateKeyAlias The alias to identify your key and certificate

To know the Key Alias, you can run: 

keytool -list -keystore yourcert.jks


Then, copy or replace your jks file into to the file /opt/soffid/iam-console-3/conf/yourcert.jks

After that, you have to restart the iam-console services.

sudo systemctl restart soffid-iamconsole

If you have some configuration error, you can search for more information in the Console log (the current day log):
/opt/soffid/iam-console-3/logs/soffid-YYYY-MM-DD.log

Example server.xml

This example only allows protocols TLSv1.3

............
<!-- Define a SSL/TLS HTTP/1.1 Connector on port 8443
         This connector uses the NIO implementation. The default
         SSLImplementation will depend on the presence of the APR/native
         library and the useOpenSSL attribute of the
         AprLifecycleListener.
         Either JSSE or OpenSSL style configuration may be used regardless of
         the SSLImplementation selected. JSSE style configuration is used below.
    -->
    
    <Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol"
               maxThreads="150" SSLEnabled="true">
        <SSLHostConfig protocols="TLSv1.3">
            <Certificate certificateKeystoreFile="conf/yourcert.jks" certificateKeystorePassword="XXXXXX" 
                         certificateKeyAlias="1" type="RSA" xpoweredBy="false" server="Apache TomEE" />
        </SSLHostConfig>
    </Connector>
............

Further information

Additional information can be found at Tomcat website: https://tomcat.apache.org/tomcat-7.0-doc/ssl-howto.html

https://es.wikipedia.org/wiki/TLS

Linux operator guide

Startup / Shutdown console

Start Soffid IAM console
systemctl start soffid-iamconsole.service
Stop Soffid IAM console
systemctl stop soffid-iamconsole.service
Status
systemctl status soffid-iamconsole.service
Logs

You can find the console logs at: /opt/soffid/iam-console-3/logs

Startup / Shutdown Synchronization servers

Start Sync server
systemctl start soffid-iamsync.service
Start Sync server
systemctl stop soffid-iamsync.service
Status
systemctl status soffid-iamsync.service
Logs

You can find the console logs at: /opt/soffid/iam-sync/logs

System backup 

Soffid relies on a database to store almost every identity data. So, the first step to perform a daily database backup.

Soffid console installation directory should be backed up after every installation or upgrade. Once the upgrade or installation has been done, only the log directory needs to be backed up.

Soffid synchronization servers configuration directory (conf) should be backed up just after configuration. In case of system failure, a new synchronization server should be installed and the conf directory can be restored onto it. The conf directory should be backed up on a different media than the database, due to conf directory contains the private keys that can decrypt the data stored in the database.

Windows operator guide

Startup / Shutdown console

Start Soffid IAM console

To start Soffid console, use service manager, or execute:

net start soffid-iamconsole
Stop Soffid IAM console

To stop Soffid console, use service manager or execute:

net stop soffid-iamconsole
Logs

You can find the console logs at: /opt/soffid/iam-console-3/logs

Startup / Shutdown Synchronization servers

Start Sync server

To start Soffid Sync server, use service manager or execute:

net start SoffidSyncServer
Start Sync server

To stop Soffid Sync server, use service manager or execute:

net stop SoffidSyncServer
Logs

You can find the console logs at: c:\program files\soffid\iam-console-3\logs

System backup 

Soffid relies on a database to store almost every identity data. So, the first step to perform a daily database backup.

Soffid console installation directory should be backed up after every installation or upgrade. Once the upgrade or installation has been done, only the log directory needs to be backed up.

Soffid synchronization servers configuration directory (conf) should be backed up just after configuration. In case of system failure, a new synchronization server should be installed and the conf directory can be restored onto it. The conf directory should be backed up on a different media than the database, due to conf directory contains the private keys that can decrypt the data stored in the database.