Guides

The Protectimus On-Premise Two-Factor Authentication Platform can be installed on your private servers or in your private cloud.

• Private server installation requirements: Java (JDK version 8); PostgreSQL DBMS, version 10 or later.
• Private cloud installation requirements: CPU: 2 cores, memory: 8 GB; OS: Linux; cloud disk: 20 GB; load balancer.

To ensure uninterrupted operation of your multi-factor authentication server, deploy it to a cluster of several servers (we recommend using at least three nodes). Use a load balancer to distribute the load among them.

To install the Protectimus On-Premise Platform, you can use the installer for Windows or create a Docker Image.

1. Protectimus Platform Installation Using a Docker Image

1. To start installing the Protectimus On-Premise Platform, first of all, download and install docker and docker-compose:

• Docker: https://docs.docker.com/engine/install/
• Docker-compose: https://docs.docker.com/compose/install/

2. Then clone the git repository: https://github.com/protectimus/platform-linux.git

3. Go to the platform-linux/platform directory and run:

docker-compose up -d

4. You can monitor the process of platform deployment using the command:

docker-compose logs -f

5. After the deployment process is complete, the platform will be available at: https://localhost:8443

2. Protectimus Platform Installation on Windows

1. Download and run the Protectimus Platform installer. Check the Platform box and click Next.If you are going to use DSPA or RADIUS integrations, and/or OTP delivery via chat-bots in messaging apps Telegram, Facebook Messenger, or Viber, also check the appropriate boxes.

2. Before deploying the Protectimus Platform, Java must be installed on your server. Click the Install button to check for Java. If it’s not installed yet, the latest JDK version will be installed automatically.

3. Also, database management system PostgreSQL (version 9.2 and above) must be installed on your server. Click the Install button to check for PostgreSQL. If it’s not installed yet, the latest PostgreSQL version will be installed automatically.

ATTENTION: You will need to set a superuser name and password during installation. You’ll need this password to login to PostgreSQL later.

Please, remember your superuser name (postgres) and the password you’ll add on this step. This name and password will be required to login to PostgreSQL later.

4. Login to PostgreSQL Database. Enter the superuser name and password you specified during the PostgreSQL installation and click LogIn. Then click Next to continue the installation.

5. Create and Select the database you will use for Protectimus On-Premise Platform.

• Create a new database. Enter the desired database name and click Create.
• Check whether it is created or not using the button List.
• Click the Select button, choose the database you’ve just created, and click Next.

6. Initiate the database. Click Init to execute SQL scripts and initiate your database. This may take some time.

7. Select the folder to install the Protectimus Platform and click Install.

The server will be started on port 8080, and the platform will be available from the address http://localhost:8080. It will be opened automatically after the installation. After launching the platform, you’ll need to register in the system.

3. How to Pay and Activate the License

After testing the Protectimus Platform successfully, you’ll need to get a license. To do so, go to http://platform_path/licensing, select the option you require and get the license key.

Using the key you received, you can pay for and download your license online. To do so:

1. Go to https://service.protectimus.com/en/platform and click Purchase License.

2. Enter your license key into the Licensing Key field and click Submit.

3. On the next step, click on the Pay button.

4. Choose a payment method. If you require an alternate payment method, contact Protectimus customer support.

5. After successful payment click on the Issue Platform License button.

   

   You can also do this on the page https://service.protectimus.com/en/platform by clicking the Issue License button.

6. Enter the key into the Licensing Key field and click Submit. After that, the license file will be downloaded.

7. After receiving the license file, download it to the server and provide the path to the license file in the licence.file.path parameter, in the file named protectimus.platform.properties.

4. How to Get Registered in Protectimus System

The installer will automatically open the registration form at http://localhost:8080.

Please, create an account and log in to configure the necessary settings.

5. How to Enable Users Synchronization With Your User Directory

1. Login to your Protectimus account, and click: Users – Synchronization – Add LDAP user provider

2. In the Connection section, fill in the details about your user directory.

Basic settings:

Field	Value	Note
Connection URLs	URL to connect to your LDAP server	Example: ldaps://dc1.domain.local:636 For DSPA, you need to use the LDAP connection, and you also need to import the SSL certificate. A standard way: keytool -import -alias ___ -file '___.cer' -keystore 'C:\Program Files\Java\jre___\lib\security\cacerts' -storepass changeit
Base DN	Full DN of the directory in which your users are stored	Example: DC=domain,DC=local
Password	The password of the specified user
User DN	DN or userPrincipalName of the administrator or user who has access to user information	Example: CN=Administrator, CN=Users, DC=demo, DC=domain, DC=local administrator@domain.local For DSPA, the user must have rights to change passwords
Timeout (ms)	Connection timeout

3. After filling in details about your user directory, add synchronization attributes.Click on the Attributes button.

   

   Then add your attributes as shown in the example.

   

4. After successfully adding the user provider, you need to import the users into the Protectimus system and synchronize them with your user directory.In the Synchronization mode field, you should choose how you would like to import your users.

   Importing users can be set up in three ways:

   • Import – will never update user data.
   • Import and Update – will always update user data when possible.
   • Import, Update and Delete – will always update user data when possible. Protectimus users, as well as the software tokens assigned to them, will be removed upon the user’s removal from external user storage.

5. Now configure the Use pagination setting.When Use pagination is activated, it means that if the number of records exceeds 200 or 500, multiple queries will be used for retrieval. This is due to LDAP typically returning a limited number of entries by default.

6. Set up a filter to be applied during synchronization. Use this filter to select only the users you want to synchronize.For example, to import only those users who have the telephoneNumber and mail attributes specified, set up such a filter:
   (&(telephoneNumber=*)(mail=*))
   To import users from a specific group, choose the required group. In our example, it is the Users group.

7. Now configure the Enroll SMS token setting.When Enroll SMS token is activated, SMS tokens will be enrolled and assigned to your users during synchronization.

8. In the Resource associations section, you can choose the resource to which the users will be assigned during synchronization.

9. The next step is to enable user synchronization. This can be accomplished in three ways:
   1. Use the Synchronize now button to synchronize all users at once. You can also select the Synchronize modified button to synchronize only the users who have been modified since the last synchronization.
   2. Use the Synchronize individuals feature to synchronize only the selected users from your user directory.
   
   3. Or enable automatic user synchronization by activating the Enabled option at the top of the page.
   

 

6. How to Configure SSL Certificate, Mail and SMS Tokens, and Specify the Path to the License File

Once you’ve successfully installed the platform, it will generate a configuration file named protectimus.platform.properties. The protectimus.platform.properties file must be located in the same directory as the executable. This file allows you to customize the following settings:

• Add SSL certificate for the Protectimus Platform. Different SSL certificate formats are supported, including .pkcs12, .pem, .der, .pfx.
• Configure delivery of messages via email;
• Configure SMPP server connection to add your SMS provider to deliver one-time passwords via SMS.
• Specify the path to the license file. Please note that the path to the license file should be indicated with double backslashes (eg. C:\\some\\path\\file).

Available properties that you can add to the protectimus.platform.properties file include:

6.1. SSL Certificate Configuration

PROPERTY NAME	PROTERTY STANDS FOR
https.port	Port on which your application listens for HTTPS requests. Typically, platform uses port 8443 by default.
https.keystore.type	Type of keystore used to store SSL certificates and private keys. Types: JKS, PKCS12.
https.keystore.password	Password required to access the keystore.
https.keystore	Full path to the keystore file containing SSL certificates and private keys. Please note that the keystore file should be located in the ..\\Protectimus\\Platform folder, in the same place as the .war and .properties files. The path should be indicated with double backslashes, for example C:\\Program Files\\Protectimus\\Platform\\keystore.jks.

Example:

6.2. Email Message Delivery Configuration

PROPERTY NAME	PROTERTY STANDS FOR
smtp.host	SMTP server’s hostname or IP address.
smtp.port	Port number for SMTP server.
smtp.user	Username or email account for authentication.
smtp.password	Password associated with the username or email account.
default.from.address	Allows you to set the address from which emails will be sent to the user.

Example:

6.3. SMPP Server Connection Configuration

PROPERTY NAME	PROTERTY STANDS FOR
smpp.server.login	SMPP server login.
smpp.server.password	SMPP server password.
smpp.server.host	Host or IP address of the SMPP server.
smpp.server.port	Port for the SMPP server.
smpp.message.encoding	Encoding for SMPP messages.
smpp.from.address	Source or sender address for SMPP messages.

Example:

7. How to Import Trusted SSL Certificate

By default, a self-signed SSL certificate is used for the SSL connections with the Protectimus On-Premise Platform. If you would like to import your own trusted SSL certificate, follow the instructions below. To import the SSL certificate, you will need the SSL certificate itself, the keytool, and openssl utilities. Different SSL certificate formats are supported, including .pkcs12, .pem, .der, .pfx.

1. Import the certificate as trusted into the keystore:

 

2. Convert the certificate to PKCS12 format:

 

3. Import the certificate to the keystore:

 

8. How To Integrate and Configure the Protectimus On-Premise Platform

Integrate the Protectimus On-Premise Platform with the system you plan to protect with two-factor authentication and configure the necessary settings. To do this, download the instructions for the integration component you require on the Integrations page.

9. How to Update the Protectimus On-Premise Platform

You can update the Protectimus On-Premise Platform using a Docker image on any operating system. However, if you initially installed the Platform on Windows, you may follow the instructions for Windows users below.

9.1. Updating Platform Using a Docker Image

You have two options for updating the Protectimus On-Premise Platform with a Docker image:

• cloning a repository from Git;
• manual update.

We’ll walk you through both methods, allowing you to choose the one that best suits your preferences.

9.1.1. Updating via Git Repository Cloning

1. Use this command to copy the repository containing Docker Compose files to your local computer, where the Protectimus On-Premise Platform is installed.
   git clone https://github.com/protectimus/platform
   The contents of the archive will be as follows:
   . └── platform ├── platform │ ├── docker-compose.yaml │ ├── .env │ ├── platform_data │ │ ├── autogenerated-keystore.jks │ │ └── protectimus.platform.properties │ └── postgres_data ├── radius │ ├── config │ │ ├── radius.all.yml │ │ └── radius.yml │ ├── docker-compose.yaml │ └── .env └── unifi-guest-portal ├── config │ ├── fragments.html │ ├── guest-portal.all.yml │ └── guest-portal.yml ├── docker-compose.yaml └── .env

2. Go to the platform directory:
   cd platform/platform

3. Run the application using Docker Compose. This command will start all the containers required for your application in the background (-d):
   docker-compose up -d

4. Stop running containers using this command:
   docker-compose down

5. Make a backup of your database. The data is located in the postgres_data directory.

6. Get latest changes from Git repository. This command will update your local repository to the latest version that you have uploaded to Git. Resolve any configuration conflicts if necessary.
   git pull

7. Download the updated images. This command will download the updated Docker images from your Docker registry:
   docker-compose pull

8. Restart containers with new images. This command will restart the containers using the updated images in the background mode (-d):
   docker-compose up -d

9.1.2. Manual Update from Github

1. Download the latest version of the archive with the Protectimus Platform from Github and extract it: https://github.com/protectimus/platform/releasesThe contents of the archive will be as follows:
   . └── platform ├── platform │ ├── docker-compose.yaml │ ├── .env │ ├── platform_data │ │ ├── autogenerated-keystore.jks │ │ └── protectimus.platform.properties │ └── postgres_data ├── radius │ ├── config │ │ ├── radius.all.yml │ │ └── radius.yml │ ├── docker-compose.yaml │ └── .env └── unifi-guest-portal ├── config │ ├── fragments.html │ ├── guest-portal.all.yml │ └── guest-portal.yml ├── docker-compose.yaml └── .env

2. Go to the platform directory:
   cd platform/platform

3. Run the application using Docker Compose. This command will start all the containers required for your application in the background (-d):
   docker-compose up -d

4. Stop running containers using this command:
   docker-compose down

5. Make a backup of your database. The data is located in the postgres_data directory.

6. Change the component version to the latest in the .env file.

7. Download the updated images. This command will download the updated Docker images from your Docker registry:
   docker-compose pull

8. Restart containers with new images. This command will restart the containers using the updated images in the background mode (-d):
   docker-compose up -d

9.2. Updating Platform on Windows

9.2.1. Before updating the platform, stop the platform in services. 9.2.2. Install the new version of the Protectimus On-Premise Platform, and when selecting a database, choose the one used in the old version of the Protectimus platform.

1. Choose the necessary components.

2. Click Next.

3. Click Next.

4. Use your username and password to log in to the PostgreSQL database you created during the first platform installation and click LogIn.

5. Enter the name of the database you used in the old version of the Protectimus platform and click Select. You can click the List button to see the list of available databases if you don’t remember the exact name of the necessary database.

6. Preferably, use the same destination folder as previously.

7. Once the platform is installed, you will see the changelog describing recent updates; close it.

8. Then click OK to finish the installation.