# 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: - Windows or Linux (Ubuntu are the most used) - Java JDK 8 or higher. Java JDK11 recommended - 8GB RAM - > 10GB disk space - [Supported database installed](https://bookstack.soffid.com/books/installation/page/initialize-database "Initialize database") ## Video Tutorial ### Windows ### Linux ## Installation ### Download You can download Soffid 3 components from our website [Soffid Download Manager](http://download.soffid.com/download/) Depending on your platform, you can download the MSI, RPM or DEB version. [![IAM Console download.png](https://bookstack.soffid.com/uploads/images/gallery/2021-03/scaled-1680-/iam-console-download.png)](https://bookstack.soffid.com/uploads/images/gallery/2021-03/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: ```shell sudo dpkg -i '/your-path/SOFFID 3 Console-Debian_Ubuntu installer-3.0.0.deb' ``` You can ckeck the IAM Console service status: ```shell systemctl status soffid-iamconsole.service ``` #### Configuration Then, open the web browser pointing to [http://localhost:8080](http://localhost:8080) The wizard will ask for the following information: - **Host name:** enter the name that will be used by end-users to access to the console. To use the fully qualified domain name is suggested. A virtual service name can be used as well. Mind that the web server will work even when you put a wrong host names. This host name will be used in email notifications that contain a link to the console. - **User name**: Enter the name of a user with permissions to create tables and indexes in the selected database. - **Password**: Enter the database user password. - **Database type**: select the right database engine: Maria DB, MySQL, PostgreSQL, MS SQL Server or Oracle. - **Database URL**: complete the database URL. The default template use to be good enough, but you can use advanced features depending on the selected database driver: - Maria DB and MySQL: [https://mariadb.com/kb/en/about-mariadb-connector-j/](https://mariadb.com/kb/en/about-mariadb-connector-j/) - PostgreSQL: [https://jdbc.postgresql.org/documentation/80/connect.html](https://jdbc.postgresql.org/documentation/80/connect.html) - MS SqlServer: [https://docs.microsoft.com/es-es/sql/connect/jdbc/building-the-connection-url?view=sql-server-ver15](https://docs.microsoft.com/es-es/sql/connect/jdbc/building-the-connection-url?view=sql-server-ver15) - Oracle: [https://docs.oracle.com/cd/B28359\_01/java.111/b31224/urls.htm#BEIJFHHB](https://docs.oracle.com/cd/B28359_01/java.111/b31224/urls.htm#BEIJFHHB) The next step, allows you to enter the name and password for the initial Soffid user. You must enter: - Login name: by default it's admin, but you can use any other naming convention. To change it is good security practice. - First name: Your first name. - Last name: Your last name. - Password: Enter the initial password to use. Write it twice and don't forget it. ## 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: ```shell 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: ```shell 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](http://%3Cnode-ip%3E%3Cpublish-port%3E/) 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: - Windows or Linux (Ubuntu are the most used) - Java JDK 8 or higher - 8GB RAM - > 10GB disk space - [Soffid console installed](https://bookstack.soffid.com/books/installation/page/installing-iam-console "Installing IAM Console") ## Video tutorial ### Windows ### Linux ## Installation ### Download First of all, open your favorite browser and open the [Soffid Download Manager](http://www.soffid.com/download/). Click on *Synchronization server* and download the latest version for your OS. [![Syncserver download.png](https://bookstack.soffid.com/uploads/images/gallery/2021-03/scaled-1680-/ntnsyncserver-download.png)](https://bookstack.soffid.com/uploads/images/gallery/2021-03/ntnsyncserver-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: - **Database URL**: Use the same URL used to install the console. - **Database use**r: The user name to connect to the database. It was used during the console installation - **Database password**: The database user password - **Host name**: Enter the fully qualified domain name of the host. IP addresses are not accepted. - **Port to listen**: Enter a TCP port number. The sync server will receive connections from the console or other sync servers through this port. The suggested value is 1760. 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: - **Cloud service**: You can install an on-premise sync server connected to a cloud instance. In this case, the communication stack works in a slightly different way. If this is the case, enter Y. If you are connecting to an on-premise Soffid deployment, enter N. - **Server URL**: Enter the URL for the first sync server. - **Tenant name**: Enter the tenant name. If the sync server is not intended to work with a single tenant, enter master. - **User name**: Enter an administrator user name. - **Password**: Enter the administrator password. - **Host name**: Enter the fully qualified domain name of the host. IP addresses are not accepted. - **Port to listen**: Enter a TCP port number. The sync server will receive connections from the console or other sync servers through this port. The suggested value is 1760. 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. ```shell sudo systemctl edit --full soffid-iamsync ``` ```shell User=root group=root protectSystem=false ``` ```shell 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: ```shell `ln -fs /opt/soffid/iam-sync/bin/soffid-sync /etc/init.d/soffid-syncln -fs /etc/init.d/soffid-sync /etc/rc1.d/K01soffid-syncln -fs /etc/init.d/soffid-sync /etc/rc2.d/S06soffid-syncln -fs /etc/init.d/soffid-sync /etc/rc3.d/S06soffid-syncln -fs /etc/init.d/soffid-sync /etc/rc4.d/S06soffid-syncln -fs /etc/init.d/soffid-sync /etc/rc5.d/S06soffid-syncln -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: ```shell `/opt/soffid/iam-sync/bin/configure -main -hostname [hostname] -port 760 -dbuser [soffid] -dbpass [pass] -dburl [jdbc:mysql://localhost:3306/soffid]` ```
On Windows: ```shell %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](https://bookstack.soffid.com/uploads/images/gallery/2021-01/scaled-1680-/image-1611041442254.png)](https://bookstack.soffid.com/uploads/images/gallery/2021-01/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: ```shell `/opt/soffid/iam-sync/bin/configure -hostname [hostname] -user [user] -pass [pass] -server [https://yourserver:760] -tenant [master]` ```
On Windows: ```shell `%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: - Open console and click on *Start →* *Soffid Configuration → Soffid Parameters*: - Click on *Add New* and, then, write the parameter **soffid.server.register**, set the value to ***direct*** and *Confirm changes*. - Execute the configuration of a synchronization server proxy as follows: On Linux: ``` /opt/soffid/iam-sync/bin/configure -hostname hostname -user usuario -pass pass -server https://:760 -tenant master ``` On Windows: ``` %ProgramFiles%\soffid\iam-sync\bin\configure -hostname hostname -user usuario -pass pass -server https://:760 -tenant master ``` Where **hostname** is the name of the synchronization server proxy, **user** and **pass** are the Soffid console user name and password and, finally, **URL** is the first synchronization server URL. - In the Soffid console, go to *Start→ Soffid Configuration → Agents* and click on *Synchronization Servers* to check if the synchronization server proxy has been registered. 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: ```shell /opt/soffid/iam-sync/bin/configure -main -force -hostname hostname -port port -dbuser soffid -dbpass pass -dburl jdbc:mysql://localhost:3306/soffid ``` On Windows: ```shell %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: - For Oracle by SID: jdbc:oracle:thin:@localhost:1571:XXXX - For Oracle by Service Name: jdbc:oracle:thin:@localhost:1571/XXXX - For Mysql: jdbc:mysql://localhost:3306/XXXX - For SQLServer: "jdbc:sqlserver://localhost:1433;databaseName=XXXX" - For Postglesql: "jdbc:postgresql://localhost:5432/XXXXX

Now you can connect to the IAM console [http://localhost:8080/soffid](http://%3Cnode-ip%3E%3Cpublish-port%3E/) 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): ```shell keytool -v -importkeystore -srckeystore -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
portYou can choose the standard 443 or another custom port
certificateKeystoreFileThe source by default starts from /opt/soffid/iam-console-3/ (the installation directory)
certificateKeystorePasswordThe password used to encrypt the jks file
certificateKeyAliasThe alias to identify your key and certificate
To know the Key Alias, you can run: ```shell 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. ```shell 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 ```XML ............ ............ ``` ## Further information Additional information can be found at Tomcat website: [https://tomcat.apache.org/tomcat-7.0-doc/ssl-howto.html](https://tomcat.apache.org/tomcat-7.0-doc/ssl-howto.html) --- *[https://es.wikipedia.org/wiki/TLS](https://es.wikipedia.org/wiki/TLS)* # Linux operator guide ## Startup / Shutdown console ##### Start Soffid IAM console ```shell systemctl start soffid-iamconsole.service ``` ##### Stop Soffid IAM console ``` systemctl stop soffid-iamconsole.service ``` ##### Status ```shell 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 ```Powershell systemctl start soffid-iamsync.service ``` ##### Start Sync server ```Powershell systemctl stop soffid-iamsync.service ``` ##### Status ```Powershell 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. - For Maria DB, look at: [Backup and restore overview](https://mariadb.com/kb/en/backup-and-restore-overview/) - For Oracle, look at: [Backing Up The Database](http://docs.oracle.com/cd/E11882_01/backup.112/e10642/rcmbckba.htm#BRADV8003) - For SQL Server, look at: [Create a Full Database Backup (SQL Server)](http://msdn.microsoft.com/en-US/en-en/library/ms187510.aspx) 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: ```shell 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: ```Powershell net start SoffidSyncServer ``` ##### Start Sync server To stop Soffid Sync server, use service manager or execute: ```Powershell 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. - For Maria DB, look at: [Backup and restore overview](https://mariadb.com/kb/en/backup-and-restore-overview/) - For Oracle, look at: [Backing Up The Database](http://docs.oracle.com/cd/E11882_01/backup.112/e10642/rcmbckba.htm#BRADV8003) - For SQL Server, look at: [Create a Full Database Backup (SQL Server)](http://msdn.microsoft.com/en-US/en-en/library/ms187510.aspx) 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.