Stores and databases#

Storing objects in Couchbase#

You can reassign the internal Blitz Identity Provider storages (buckets) in Couchbase Server DBMS used for data storage. For the following datasets, you can specify the need to use other storages (buckets) than the default ones.

To configure other storages (buckets) you need to add settings in blitz.prod.local.idp.internal-store-cb block:

  • buckets - list of used storages (buckets), if they are different from default ones;

  • bucketsMapping - overriding the default dataset locations to store in other storages.

An example of the configuration file is shown below. As a result, the acl dataset is placed in the users storage, and clt and iat are placed in apps. By default, all three datasets were written to the oauth store.

"internal-store-cb" : {
  …
  "buckets" : {
    ["users", "oauth", "audit", "builtin_idstore", "ctxs"]
  },
  "bucketsMapping" : {
    "acl" : "users",
    "clt" : "apps",
    "iat" : "apps"
  },
  …
}

Reading the Couchbase Server cluster configuration#

If one of the Couchbase Server cluster nodes is unavailable, users may experience errors when logging in to Blitz Identity Provider. In this case, you must calibrate the value of the global cluster configuration read interval. If the connection to a node is interrupted, the configuration will be recalculated on time so that Blitz Identity Provider will only access the working nodes. Do the following:

  1. Open the /usr/share/identityblitz/blitz-config/blitz.conf configuration file.

  2. In the blitz.prod.local.idp.internal-store-cb.ioConf section, set the value of the configPollInterval parameter in milliseconds.

    "internal-store-cb" : {
    "ioConf" : {
        "configPollInterval" : 2500
    },
    ...,
}

Object storage time#

You can set a limitation of database records retention period for audit data (by default, records are stored indefinitely). To do this, in the blitz.prod.local.idp.internal-store-cb block, add the ttlMapping setting specifying the doc_type of the record (aud) and the retention time in seconds.

Configuration example (audit retention time is limited to 90 days):

"internal-store-cb": {
  …
  "ttlMapping": {
    "aud": 7776000
  },
  …
}

You can configure a limitation on the retention period of records in the database for device data. To do this, add the settings in the blitz.prod.local.idp.login block:

  • uaActiveTtlInSec - storage time of the record of the device (in seconds) with which the user’s long-term session is associated or which the user marked as trusted at login. If the setting is not specified, the information about such a device is stored for one year from the last login from this device;

  • uaInactiveTtlInSec - time for storing the record of other devices (in seconds). If the setting is not specified, the information about such a device is stored for 5 days.

Example of configuration:

"login": {
  …
  "uaActiveTtlInSec": 2678400,
  "uaInactiveTtlInSec": 432000,
  …
}

Advanced PostgreSQL connection settings#

For advanced management of the connection pool with PostgreSQL or another JDBC-enabled database, do the following:

  1. Open the /usr/share/identityblitz/blitz-config/blitz.conf configuration file.

  2. In the blitz.prod.local.idp.internal-store-jdbc.pool section, set the following options:

    Option

    By default

    Description

    testOnBorrow

    true

    Check a connection status before sending data. In the case of an error, the system removes the connection and selects the next one from the pool.

    testOnCreate

    false

    Check a connection status after it has been created in the pool.

    testOnReturn

    false

    Check a connection status after returning it to the pool.

    testWhileIdle

    false

    Check an idle connection status. In the case of an error, the connection is removed from the pool.

    timeBetweenEvictionRunsMillis

    -1

    Interval in milliseconds between check runs of an idle connection. The option affects testWhileIdle.

    validationQuery

    -

    SQL query executed when checking a connection status from the pool, isValid() is used if the value is empty.

    		 
    "internal-store-jdbc" : {
     "pool" : {
         "maxIdleConn" : 10,
         "maxTotalConn" : 20,
         "maxWaitConnMs" : 30000,
         "minIdleConn" : 7,
         "testOnBorrow" : false,
         "testOnCreate" : false,
         "testOnReturn" : false,
         "testWhileIdle" : true,
         "timeBetweenEvictionRunsMillis" : 30000,
         "validationQuery" : ""
     }
}

  3. Restart the services.

    sudo systemctl restart blitz-idp blitz-console blitz-recovery blitz-registration

Advanced LDAP connection settings#

You can create settings for connection to attribute storages working via LDAP protocol in the admin console. At the same time, you can set LDAP connection pool settings through the admin console. Blitz Identity Provider will use the common connector pool settings to set up connections by each application that uses the connection to the storages. This can lead to a large number of LDAP connectors being created.

Using the blitz.conf configuration file, you can configure the parameters of the initial and maximum number of connectors in the context of different Blitz Identity Provider applications (for example, for the admin console you can set smaller values of connectors in the pool than for the authentication service). To do this, in the blitz.prod.local. id-stores block in the settings of the corresponding storage, along with the initialConnections and maxConnections settings, you can create settings of the form initialConnections#BLITZ_APP and maxConnections#BLITZ_APP, where BLITZ_APP is the name of the corresponding application (blitz-console, blitz-idp, blitz-registration, blitz-recovery).

An example of a setting where the admin console is set to a smaller connection pool size than for the other applications:

"id-stores" : {
  "list" : [
    {
      "type" : "LDAP",
      …
      "initialConnections" : 10,
      "initialConnections#blitz-console" : 1,
      "maxConnections" : 20,
      "maxConnections#blitz-console" : 1
    }
  ]
}

When making LDAP queries to the Blitz Identity Provider attribute storage, Blitz Identity Provider takes an existing LDAP directory connection from the connection pool. After the query is completed, Blitz Identity Provider does not close the connection, but returns it back to the connection pool for reuse. This procedure for interacting with LDAP provides high performance, but requires keeping connections to the LDAP directory open for extended periods of time. Firewall or LDAP directory settings may prevent Blitz Identity Provider applications from keeping LDAP directory connections open for extended periods of time.

Blitz Identity Provider TCP connections to an LDAP directory can be closed without a negotiated connection termination, so that the LDAP directory will close the connection without Blitz Identity Provider being notified. When attempting to use such a connection from the pool, a long timeout may occur before Blitz Identity Provider considers the connection closed and removes it from the connection pool. To ensure that this situation does not affect users, Blitz Identity Provider provides an algorithm to periodically check the validity of open LDAP connections. The healthCheckInterval period (in milliseconds) is used to check the connection status, and the timeout time in the absence of LDAP directory response to the request is set by the connectionTimeout parameters (in milliseconds). The described mode of optimal interaction with the connection pool is enabled by default (setting useSyncMode to false). In case of unstable operation of connections with LDAP directory it is recommended to try to enable synchronous mode of interaction with the directory (set useSyncMode to true).

Examples of recommended settings are below:

"id-stores" : {
  "list" : [
    {
      "type" : "LDAP",
      …
      "connectionTimeout" : 3000,
      "healthCheckInterval" : 300000,
      "useSyncMode" : false
    }
  ]
}

If several attribute storages are connected to Blitz Identity Provider at the same time, a situation may arise that when identifying and authenticating a user by login and password, several accounts, possibly belonging to different people, with matching logins may be detected in several storages. This situation should be avoided when implementing Blitz Identity Provider, and by default, if such a situation is detected, Blitz Identity Provider will issue a login error to the user indicating that there is an incorrect user account situation. However, in some cases there may be a situation when the implementation deliberately allows several accounts of different users in different storages to be found by one login. In this case, you can specify the firstSucceded mode in the authStrategy setting in the blitz.prod.local.idp.login settings block. In this case all found accounts will be checked, and whichever of them matches the user’s password first will be logged in with that account.

Example of configuration:

"login" : {
  "authStrategy" : {
    "mode" : "firstSucceeded"
  },
  …
}

Geodatabase#

You can connect to Blitz Identity Provider a database in mmdb format with geodata. In this case, Blitz Identity Provider will record the country, region and city data corresponding to the IP address, as well as the latitude, longitude and radius of accuracy obtained from the geodatabase, in addition to storing the IP address, when logging security events and memorizing the user’s devices and browsers.

The saved geodata will be shown to the administrator in the admin console. It is also possible to enable displaying geodata to the user in the “User profile” and include it in the texts of notifications sent by SMS or email.

To connect the database with geodata, you need to upload the mmdb file with the database to the servers with Blitz Identity Provider, and create a blitz.prod.local.idp.geoIp settings block with the following settings in the driver block:

  • type - type of the base with geodata. Only geoIp2-db type is supported;

  • path - path on the server to the file with geodatabase in mmdb format.

Example of configuration:

"geoIp": {
    "driver": {
        "type": "geoIp2-db",
        "path": "geoIp/GeoIP2-City.mmdb"
    }
}

Several DBMSs usage#

In Blitz Identity Provider you can configure simultaneous use of Couchbase Sever and PostgreSQL DBMS for storing different types of objects. To do this, specify the following settings in the blitz.prod.local.idp.stores settings block:

  • default_type - the default DBMS used. Possible values: cb - Couchbase Server, jdbc - PostgreSQL or other relational DBMS with JDBC support;

  • list-of-types - identifiers of Blitz Identity Provider object classes and used for placing corresponding DBMS objects (cb or jdbc). Only those object classes that are hosted in a DBMS other than the one specified in default_type should be included in the configuration. The following object classes are available:

    • user-store - user profile attributes;

    • access-token-store - security tokens;

    • refresh-token-store - refresh tokens;

    • id-ext-store - bindings of external identity providers;

    • device-code-store - Confirmation codes for OAuth 2.0 Device Authorization Grant;

    • access-list-store - user-granted permissions to applications;

    • blitz-action-store -contact confirmation codes (sms, email);

    • oath-token-store - bindings of HOTP and TOTP one-time password generators;

    • oath-load-proc-store - history of downloaded descriptions of hardware HOTP and TOTP one-time password generators;

    • confirmation-request-store - requests for one-time passwords;

    • reg-context-store - user registration context;

    • reg-context-storef - user registration context;

    • id-store-maker - a built-in storage of user IDs;

    • rcv-ctx-store - user password recovery context;

    • db-client-store - dynamic clients;

    • db-client-storef - dynamic clients;

    • initial-token-store - IAT tokens;

    • user-agent-store - users’ devices (browsers);

    • web-authn-key-store - security keys;

    • audit-store - security events;

    • task-store - asynchronous tasks.

  • utils - list of utility modules required for the used DBMS type: modules.CouchbaseModule - for Couchbase Server, modules.JDBCModule - for PostgreSQL.

Example of two DBMS sharing settings:

"stores" : {
  "default-type" : "jdbc",
  "list-of-types" : {
    "access-token-store" : "cb",
    "refresh-token-store" : "cb",
    "user-agent-store" : "cb"
   },
  "utils" : [
    "modules.CouchbaseModule",
    "modules.JDBCModule"
  ]
}