General installation instructions#

Blitz Identity Provider installation generally proceeds in the order described below.

Tip

Depending on the operating system used, there are specifics on how to install the required environment. For convenience, follow express instructions.

Important

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

Step 1. JDK#

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

OpenJDK 8;
Oracle JDK 8.

Step 2. 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.

CentOS and RHEL

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.

Step 3. DBMS#

Couchbase Server Installation

Couchbase Server installation guidelines are provided for 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 package 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 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.

CentOS and RHEL

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 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
psql -d blitzdb -U blitz -f 020-5.20.0.sql
psql -d blitzdb -U blitz -f 021-5.21.0.sql

After running the script, set up a database backup.

Step 4. RabbitMQ#

Optional

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.

CentOS and RHEL

You need to install RabbitMQ according to instructions.

Step 5. Blitz Identity Provider#

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 blitz-console, blitz-idp, blitz-registration, blitz-recovery applications you need to:

Copy blitz-5.X.X.X.bin``file (for example, to ``/tmp directory) from Blitz Identity Provider distribution kit to the servers intended for installation.

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

-i – list of applications to be installed, separated by a space (for example, idp console registration recovery);
-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

It will be installed in directory /usr/share/identityblitz.

Installer launch example#

cd /tmp
chmod +x blitz-5.X.X.bin
./blitz-5.X.X.bin -- -j /opt/oracle/jdk -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 by default.
- ADMIN_USER_NAME – administrator account in Blitz Identity Provider;
  
  Note
  
  If not specified, it will be admin by default.
- 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 servers 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;
- TRUSTED_SERVERS – addresses of subnets of servers with Blitz Identity Provider services (by default 127.0.0.1/32).
  The example of 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 by default.
- ADMIN_USER_NAME – administrator account in Blitz Identity Provider;
  
  Note
  
  If not specified, it will be admin by default.
- 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 DBMS 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;
- TRUSTED_SERVERS – addresses of subnets of servers with Blitz Identity Provider services (by default 127.0.0.1/32).
  The example of configuration file#
  
  DOMAIN=test ROOT_CONTEXT=/blitz MEMCACHED_SERVERS="127.0.0.1 192.168.122.96" DB_MODE=PG PG_HOSTNAME=192.168.122.20 PG_DB_NAME=blitzdb PG_USERNAME=blitz PG_PASSWORD=123456 TRUSTED_SERVERS="127.0.0.1/32 192.168.122.96/32 192.168.122.0/24" ADMIN_USERNAME=admin1 ADMIN_PASSWORD=0123456789 KEYSTORE_PASSWORD=0123456789

Run 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 instance is configured on domain: test.loc
The Administration Console available on addresses:
 http://testinstallation.local:9001/blitz/console

Administration user credentials of 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-*

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 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
```
Set JAVA_HOME value in response to the installer prompts - the directory where JDK is installed on the server.

It will be installed in directory /usr/share/identityblitz.

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

Step 6. Configuration files synchronization#

Only for installation in a cluster

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

Step 7. Web Server#

It is recommended to use nginx as a web server. A sample configuration file for nginx is included in Blitz Identity Provider distribution package - 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 server with Blitz Console.

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 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 |project| distribution kit - it is the ``static_errors folder in the resources.zip archive.

Step 8. LDAP directory#

Optional