General instructions for installation on CentOS and RHEL#

The Blitz Identity Provider installation generally proceeds in the following order:

Install JDK.
Install memcached memory manager.
Install and configure the DBMS.
Install and configure the RabbitMQ Queue server Optional.
Install the admin console and other Blitz Identity Provider services.
Set up synchronization of configuration files Only for cluster installation.
Configure the web server.
Configure external account repository Optional.

Tip

Depending on the operating system used, there are specifics on how to install the required environment. Follow the express instructions for Rocky Linux, AlmaLinux, Oracle Linux, and RHEL.

Important

Before getting started with deployment, learn the Blitz Identity Provider deployment architecture.

JDK#

On the servers designated to install the Blitz Identity Provider server software and the Blitz Identity Provider administrative console, you must install and configure JDK 8 by using one of the following products:

OpenJDK 8;
Oracle JDK 8.

Memcached#

Attention

The memcached version must be 1.4.15 or higher. The memcached service must be installed on the servers intended for installing Blitz Identity Provider services: blitz-console, blitz-idp, blitz-registration, blitz-recovery. The memcached service is not required for the blitz-keeper service.

Run the command:
```
yum -y install memcached
```
After installation is complete, add the memcached service to the autorun and start the service:
```
systemctl enable memcached
systemctl start memcached
```

Important

The memcached service runs on port 11211. Make sure that this port is open on firewalls and can be used to connect between servers with Blitz Identity Provider services.

DBMS#

Couchbase Server installation

The Couchbase Server installation instructions are tailored to CentOS 7 and RHEL 7.

You must install Couchbase Server on each of the servers allocated for DBMS installation according to the instructions. The Couchbase Server distribution is available for download.

Important

In DEV/TEST environments, it is acceptable to install Couchbase Server on existing servers with Blitz Identity Provider, but in this case you have to take into account that Couchbase Server uses its own built-in memcached service, and to avoid a conflict you need to adjust the memcached ports used in Blitz Identity Provider and Couchbase Server.

Add the Couchbase Server service to the autorun and start the service:

systemctl enable couchbase-server
systemctl start couchbase-server

Check if the service is running by executing the command:
```
systemctl status couchbase-server
```
Initialize Couchbase Server cluster on each server according to instructions (the first server initializes the cluster, other servers are included in the cluster). All settings can be set as suggested by default, only you need to set the full server name for each server in hostname. It is not recommended to use the IP address of the server as the server name.
On any of the hosts in the Couchbase Server cluster, run the script to prepare Couchbase Server to use Blitz Identity Provider. The script is located in the couchbase directory in the resources.zip archive as part of the Blitz Identity Provider distribution kit. Copy the script to any server in the Couchbase Server cluster, go to the directory, and execute the script to create buckets that will store Blitz Identity Provider information and indexes for executing Blitz Identity Provider search queries in the database:
```
./cb_init.sh
```
The script will need to be entered during execution:
- Couchbase Server URL name - enter a string like http://<hostname>:8091, where hostname is the host name of the server from which the script is executed;
- Couchbase Server administrator account login - set during cluster initialization when you perform the previous step of the instructions;
- Couchbase Server administrator account password - set during cluster initialization when you perform the previous step of the instructions;
- Couchbase Server account login - set during the running of Blitz Identity Provider service connection script;
  
  Tip
  
  It is recommended to name it blitz.
- Couchbase Server account password for Blitz Identity Provider application connection.
After running the script, make the following settings:
1. In the Couchbase Server administration console, edit the settings for the number of data copies on different Couchbase instances. To do this, select each bucket in turn in the Buckets menu, click Edit on it and set the Enable setting in the Replicas block and set the number of replicas. For a cluster of 3 servers it is recommended to set 1 for the number of replicas. Then, it is recommended to enable the Enable auto-failover setting in the Settings menu and set the Timeout value to 30 seconds (auto-failover will work only if the DBMS cluster has at least 3 servers and bucket replication is configured).
2. Set up a database backup.

PostgreSQL installation and configuration

Attention

PostgreSQL must be 9.6 or a later version.

PostgreSQL must be installed according to the instructions.

After installing PostgreSQL, run scripts to prepare PostgreSQL to use Blitz Identity Provider. The scripts are located in the postgres directory in the resources.zip archive as part of the Blitz Identity Provider distribution kit. Copy the scripts to the PostgreSQL server, go to the directory, and execute the following commands one by one:

su - postgres

createdb blitzdb

psql
CREATE USER blitz WITH ENCRYPTED PASSWORD 'set-your-pwd';
GRANT ALL PRIVILEGES ON DATABASE blitzdb TO blitz;
GRANT ALL ON ALL TABLES IN SCHEMA public TO blitz;

psql -d blitzdb -U blitz -f 000-SCRIPT000.sql
…
psql -d blitzdb -U blitz -f NNN-SCRIPTNNN.sql

Instead of set-your-pwd you should insert the password that will be used to connect to PostgreSQL.

Instead of 000-SCRIPT000.sql … NNN-SCRIPTNNN.sql you should insert the names of scripts from the postgres/ddl directory from the resources.zip archive. For example:

psql -d blitzdb -U blitz -f 000-service-tasks.sql
psql -d blitzdb -U blitz -f 001-init-database.sql
psql -d blitzdb -U blitz -f 002-new_pp_columns.sql
psql -d blitzdb -U blitz -f 003-usd_id_table.sql
psql -d blitzdb -U blitz -f 004-usr_auth_table.sql
psql -d blitzdb -U blitz -f 005-usr_agt_table.sql
psql -d blitzdb -U blitz -f 006-usr_htp_hmc_alg.sql
psql -d blitzdb -U blitz -f 007-usr_atr_cfm.sql
psql -d blitzdb -U blitz -f 008-wak.sql
psql -d blitzdb -U blitz -f 009-fix_pp_column.sql
psql -d blitzdb -U blitz -f 010-add_usr_prp.sql
psql -d blitzdb -U blitz -f 011-pp_audit.sql
psql -d blitzdb -U blitz -f 012-geo_to_audit.sql
psql -d blitzdb -U blitz -f 013-tasks.sql
psql -d blitzdb -U blitz -f 014-sec_ch_ua.sql
psql -d blitzdb -U blitz -f 015-5.12.0.sql
psql -d blitzdb -U blitz -f 016-5.13.0.sql
psql -d blitzdb -U blitz -f 017-5.15.0.sql
psql -d blitzdb -U blitz -f 018-5.17.0.sql
psql -d blitzdb -U blitz -f 019-5.18.0.sql

After running the script, set up a database backup.

RabbitMQ queue server#

Installation of the RabbitMQ Queue server is optional and is required if the Queue server is to be used to pass events to adjacent systems or as a message broker.

You need to install RabbitMQ according to instructions.

Blitz Identity Provider services#

To install the blitz-console, blitz-idp, blitz-registration, and blitz-recovery services, use the unified blitz-5.X.X.bin installer. To install the blitz-keeper service, use a standalone installer blitz-keeper-5.X.X.bin.

Important

You can install the admin console on any server where the Blitz Identity Provider server is installed, but it is recommended that a separate administrative server be dedicated to the installation of the Admin console. The JDK and memcached must be installed on the server beforehand.

To install the blitz-console, blitz-idp, blitz-registration, blitz-recovery services, do the following:

Copy blitz-5.X.X.X.bin from the Blitz Identity Provider distribution to the servers intended for installation.

Run the blitz-5.X.X.bin installer with the following start options:

-i – list of services to be installed, separated by a space;
-j – the JAVA_HOME value is the directory of JDK installation:

OpenJDK 8

/usr/lib/jvm/java-1.8.0-openjdk

Oracle JDK 8

/opt/oracle/jdk

The installation will be performed in the /usr/share/identityblitz directory.

Installer launch example#

cd /tmp
chmod +x blitz-5.X.X.bin
./blitz-5.X.X.bin -- -j /usr/lib/jvm/bellsoft-java8.x86_64 -i "idp console recovery registration"

Console during the installation process#

Verifying archive integrity...  100%   MD5 checksums are OK. All good.
Uncompressing Blitz IDP  100%
****************************************************************
Application blitz-registration installed
Application blitz-recovery installed
Application blitz-console installed
Application blitz-idp installed
****************************************************************

Create the blitz_param.txt file with initial Blitz Identity Provider settings:
Couchbase Server
- DOMAIN – external domain name where Blitz Identity Provider will be running on;
- ROOT_CONTEXT – URL path where Blitz Identity Provider will be running on;
  
  Note
  
  If not specified, it will be /blitz.
- ADMIN_USER_NAME – administrator account in Blitz Identity Provider;
  
  Note
  
  If not specified, it will be admin.
- ADMIN_PASSWORD – password for the administrator account in Blitz Identity Provider;
- KEYSTORE_PASSWORD – password for a key container that will be created during the installation;
  
  Note
  
  If the ADMIN_PASSWORD and KEYSTORE_PASSWORD parameters are not specified, these passwords will automatically be generated and displayed as a result of the configuration script execution.
- MEMCACHED_SERVERS – memcached servers addresses;
- DB_MODE – DBMS in use: CB for Couchbase Server;
- CB_NODES – addresses of nodes in the Couchbase Server DBMS;
- CB_USERNAME – account name in the Couchbase Server DBMS (blitz by default);
- CB_ PASSWORD – account password in the Couchbase Server DBMS.
  Example of the configuration file#
  
  DOMAIN=test MEMCACHED_SERVERS="192.168.122.10 127.0.0.1" DB_MODE=CB CB_NODES="192.168.122.20 192.168.122.21 192.168.122.22" CB_USERNAME=blitz CB_PASSWORD=12ABcd45
PostgreSQL
- DOMAIN – external domain name where Blitz Identity Provider will be running on;
- ROOT_CONTEXT – URL path where Blitz Identity Provider will be running on;
  
  Note
  
  If not specified, it will be /blitz.
- ADMIN_USER_NAME – administrator account in Blitz Identity Provider;
  
  Note
  
  If not specified, it will be admin.
- ADMIN_PASSWORD – password for the administrator account in Blitz Identity Provider;
- KEYSTORE_PASSWORD – password for a key container that will be created during the installation;
  
  Note
  
  If the ADMIN_PASSWORD and KEYSTORE_PASSWORD parameters are not specified, these passwords will automatically be generated and displayed as a result of the configuration script execution.
- MEMCACHED_SERVERS – memcached servers addresses;
- DB_MODE – DBMS in use: PG for PostgreSQL;
- PG_HOSTNAME – PostgreSQL server address;
- PG_DB_NAME – database name in the PostgreSQL DBMS;
  
  Tip
  
  It is recommended to set blitzdb.
- PG_USER_NAME – account name in the PostgreSQL DBMS;
  
  Tip
  
  It is recommended to set blitz.
- PG_USER_PASSWORD – account password in the PostgreSQL DBMS;
  Example of the configuration file#
  
  DOMAIN=test.loc MEMCACHED_SERVERS="192.168.122.10 127.0.0.1" DB_MODE=PG PG_HOSTNAME=127.0.0.1 PG_DB_NAME=blitzdb PG_USER_NAME=blitz PG_USER_PASSWORD=12ABcd45

Run the Blitz Identity Provider initial setup script with the right path to the blitz_param.txt file:

/usr/share/identityblitz/blitz-console/bin/configure -f blitz_param.txt

The script will prepare the configuration files, generate and display the Blitz Identity Provider administrator login and password, and generate a password for the key container:

****************************************************************
Your Blitz Identity Provider configured on domain: test.loc
Your Blitz Identity Provider Console available on addresses:
  http://test.loc:9001/blitz/console

Administration user credentials of Blitz Console:
  username - admin
  password - 98aAB0D3f2
Your can change user credentials at file - /usr/share/identityblitz/blitz-config/credentials

Create keystore /usr/share/identityblitz/blitz-config/blitz-keystore.bks and generate:
 - JWS(RSA256) keypair - jws_rs256_rsa_default
 - AES(AES128) security key - jdbc

Generated password for keystore: BeEBcd2239
****************************************************************

Tip

If input errors were made when running the installer, so that the installation was performed with incorrect parameters, you can use the following command to delete the files that the installer created so that you can perform a clean installation again:

rm -rf /usr/share/identityblitz /etc/default/blitz-* /etc/blitz-* /var/log/identityblitz/ /lib/systemd/system/blitz-*

Edit the blitz.prod.local.idp.net block by adding the subnet addresses of the Blitz Identity Provider servers to the trustedServers setting:
```
"net" : {
    "domain" : "blitz-domain.com",
    "trustedServers" : [
      "192.168.1.0/24"
    ]
}
```
If you plan to use the REST services protection function with Blitz Identity Provider, copy the blitz-keeper-5.X.X.X.bin file from the Blitz Identity Provider distribution package to the servers intended for installation of the Security Gateway (for example, to the /tmp directory).
Run the blitz-keeper-5.X.X.bin installer:
```
cd /tmp
chmod +x blitz-keeper-5.X.X.bin
./blitz-keeper-5.X.X.bin
```
In response to the installer’s request, specify the directory of JDK installation in JAVA_HOME:

OpenJDK 8

/usr/lib/jvm/java-1.8.0-openjdk

Oracle JDK 8

/opt/oracle/jdk

The installation will be performed in the /usr/share/identityblitz directory.

Add services to autorun on their respective servers and run them:

systemctl enable blitz-console
systemctl start blitz-console
systemctl enable blitz-idp
systemctl start blitz-idp
systemctl enable blitz-registration
systemctl start blitz-registration
systemctl enable blitz-recovery
systemctl start blitz-recovery
systemctl enable blitz-keeper
systemctl start blitz-keeper

Configuration files synchronization#

When you deploy Blitz Identity Provider in a cluster, you must configure synchronization of the Blitz Identity Provider configuration between Blitz Identity Provider cluster servers:

Web Server configuration#

It is recommended to use nginx as a web server. A sample configuration file for nginx is included in the Blitz Identity Provider distribution - it is the blitz-idp.conf file from the nginx directory in the resources.zip archive. You need to adjust the following configuration blocks, then upload the file to the server with nginx (/etc/nginx/conf.d directory):

Adjust the balancing settings block:

upstream blitz-idp {
    server [BLITZ-IDP-NODE-01]:9000 max_fails=3 fail_timeout=120;
    server [BLITZ-IDP-NODE-02]:9000 max_fails=3 fail_timeout=120;
}
upstream blitz-reg {
    server [BLITZ-REG-NODE-01]:9002 max_fails=3 fail_timeout=120;
    server [BLITZ-REG-NODE-02]:9002 max_fails=3 fail_timeout=120;
}
upstream blitz-rec {
    server [BLITZ-REC-NODE-01]:9003 max_fails=3 fail_timeout=120;
    server [BLITZ-REC-NODE-02]:9003 max_fails=3 fail_timeout=120;
}
upstream blitz-keeper {
    server [BLITZ-KPR-NODE-01]:9012 max_fails=3 fail_timeout=120;
    server [BLITZ-KPR-NODE-02]:9012 max_fails=3 fail_timeout=120;
}
upstream blitz-console {
    server [BLITZ-CONSOLE-NODE-01]:9001 max_fails=3 fail_timeout=120;
}

The parameters have the following designations:

[BLITZ-%%%-NODE-XX] - names (hostname) of servers with Blitz Identity Provider services (blitz-idp, blitz-registration, blitz-recovery, blitz-keeper);
[BLITZ-CONSOLE-NODE-01] is the name (hostname) of the Blitz Admin Console server.

Correct the block of TLS termination settings:
```
ssl_certificate         [BLITZ-SSL-CERT-FILE];
ssl_certificate_key     [BLITZ-SSL-PRIVATEKEY-FILE];
```
The parameters have the following designations:
- [BLITZ-SSL-CERT-FILE] - path (full name) to the file with TLS server certificate;
- [BLITZ-IDP-CONSOLE-NODE-01] - path (full name) to the file with TLS server key.
Note that the Blitz Identity Provider ignores the X-Forwarded-Proto https header if the nginx X-Forwarded-For contains more than one IP address, for example:
```
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
```
In this case, it is recommended to use the following directive value:
```
proxy_set_header X-Forwarded-For $client_ip
```
In this case, client_ip is calculated using map. The first value from the list will be taken:
```
map $http_x_forwarded_for $client_ip {
    default $remote_addr;
    "~(?<IP>([0-9]{1,3}\.){3}[0-9]{1,3})*" $IP;
    "~(?<IP>([0-9]{1,3}\.){3}[0-9]{1,3}),.*" $IP;
}
```
Copy the static_errors folder with the server error page files to the /usr/share/nginx/html` folder on the nginx server. The files with examples of error pages can be found in the Blitz Identity Provider distribution - it is the ``static_errors folder in the resources.zip archive.

General instructions for installation on CentOS and RHEL#

JDK#

Memcached#

DBMS#

RabbitMQ queue server#

Blitz Identity Provider services#

Configuration files synchronization#

Web Server configuration#

LDAP directory#