Configuration file settings#

The configuration files for all Blitz Identity Provider applications except the blitz-keeper application are located in the /usr/share/identityblitz/blitz-config directory.

The following configuration files are used:

Most settings are set using the admin console. A number of settings require editing configuration files yourself. Such settings are described in the following subsections.

The blitz-keeper configuration file for the blitz-keeper application is located in /etc/blitz-keeper. The following configuration files are used:

The blitz.conf configuration file#

The main configuration file blitz.conf consists of the following configuration blocks with the following list of purposes:

  • blitz.prod.local.idp.apps - settings of connected apps;

  • blitz.prod.local.idp.apps-source – location of the connected application settings;

  • blitz.prod.local.idp.audit - security event logging settings;

  • blitz.prod.local.idp.captcha - settings for interaction with the CAPTCHA service;

  • blitz.prod.local.idp.events - settings for sending events to the queue;

  • blitz.prod.local.idp.federation - external identity provider settings;

  • blitz.prod.local.idp.flexible-flows - login procedures settings;

  • blitz.prod.local.idp.id-attrs - attribute settings;

  • blitz.prod.local.idp.id-stores - attribute storage settings in the credential storage;

  • blitz.prod.local.idp.internal-store - DBMS connection settings;

  • blitz.prod.local.idp.keystore - key store access settings;

  • blitz.prod.local.idp.lang – Blitz Identity Provider language settings;

  • blitz.prod.local.idp.license is the Blitz Idenity Provider license key;

  • blitz.prod.local.idp.logger - logger settings;

  • blitz.prod.local.idp.login - settings for authentication methods;

  • blitz.prod.local.idp.logout - settings of the logout process;

  • blitz.prod.local.idp.messages - message file settings;

  • blitz.prod.local.idp.messaging - settings for invoking messaging services;

  • blitz.prod.local.idp.net - network settings;

  • blitz.prod.local.idp.notifier - event notification settings;

  • blitz.prod.local.idp.oauth - scopes settings;

  • blitz.prod.local.idp.password-policy - password policy settings;

  • blitz.prod.local.idp.play - Blitz Identity Provider application server settings;

  • blitz.prod.local.idp.provisioning - user registration and forgotten password recovery services settings;

  • blitz.prod.local.idp.realms - Application ID encryption settings (privacy domains);

  • blitz.prod.local.idp.rights – settings of the access rights;

  • blitz.prod.local.idp.saml - SAML settings;

  • blitz.prod.local.idp.stores - primary DBMS settings;

  • blitz.prod.local.idp.tasks - settings of the task processing method;

  • blitz.prod.local.idp.user-profile - user profile settings;

  • blitz.prod.local.idp.webAuthn - security key settings;

  • home - path to the Blitz Identity Provider installation directory on the application server.

The following is a description of the settings that are inaccessible from the admin console, they can be configured by editing the blitz.conf configuration file.

Limiting the number of simultaneous user password verifications#

You can set a limit on the number of simultaneous password authentications with the same user login in a period of time. The default setting is that Blitz Identity Provider allows no more than 3 authentications to the same login within 600 ms. To adjust the default settings, you must add the following block in the blitz.conf configuration file to the blitz.prod.local.idp.login.methods.password section:

"throughput": {
  "limit": 3,
  "window": 600
}

Disabling the password change function at login#

If Blitz Identity Provider is connected to a writable account storage (the storage is not in read-only mode), then when a user logs in with an account from that storage, if the password policy requires the user to change their password, the user will be presented with a password change screen (asking them to enter their old and new password). Sometimes displaying the password change screen at login is not desirable. You can disable the screen by setting the following block of settings in the blitz.conf configuration file under blitz.prod.local.idp.login.methods.password:

"changePasswordMode": {
  "type": "except_for",
  "idStores":["ldap1","ldap2"]
}

The idStores setting should list the identifiers of those account storages for which the user should not be prompted to change their password at login.

Configuring the external attribute validator#

If the capabilities provided by regular expression input value conversion rules (see Configuring Input Value Conversion Rules) are not sufficient to implement the required business logic for validating the acceptability of an attribute value, the use of an external validator can be programmed and configured for the attribute.

To do this, you need to create a program with an external validator and build it into a JAR file.

The created JAR file should be copied to the servers with Blitz Identity Provider applications. The JAR file location address should be specified in the Java option extensionsDir.

Example:

export JAVA_OPTS="${JAVA_OPTS} -DextensionsDir=/usr/share/identityblitz/extensions"

In the blitz.prod.local.idp.id-attrs.attrsMeta attribute settings block, you must add validators block in the source block to the attribute description block for which you want to enable validation via an external validator:

  • in the className setting, specify the address of the Java class that implements the AttributeValidator interface from the Blitz JDK;

  • in the conf block, specify the settings to be passed to the validator.

Example of configuration:

"id-attrs" : {
    "attrsMeta" : [
        {
            {
                "class" : "verified-mobile",
                "format" : "string",
                "name" : "phone_number",
                "realmed" : false,
                "required" : false,
                "searchable" : true,
                "source" : {
                    "validators" : [
                        {
                            "className" : "validator.MobileValidator",
                            "conf" : {
                                "conf1" : "value1"
                            }
                        }
                    ],
                    "type" : "idStore"
                },
                "unique" : false
            },
            …
        }
    ]
}

Configuring the attribute translator#

You can associate a translator with an attribute that describes the attribute’s conversion rules for reading from the LDAP directory and writing to the LDAP directory. In the attribute storage settings block in the blitz.prod.local.idp.id-stores.list.mappingRules section of the attribute matching settings, in the attribute description block for which you want to enable a translator, you must add the translator block with the className setting, in which you must specify the name of the Java class that implements the translation algorithm. The Java class must implement the implementation of the LdapAttributeTranslator interface from the Blitz JDK.

If you need to configure the translator for the objectGUID attribute from the Active Directory LDAP directory so that this attribute is represented as a GUID string rather than in byte form, you can use the Blitz Identity Provider built-in Java class com.identityblitz.idp.store.ldap.core.translator.ObjectGUIDTranslator.

Example of configuration:

"id-stores" : {
    "list" : [
        {
            …
            "mappingRules" : [
                …
                {
                    "name" : "objectGUID",
                    "storeAttr" : "objectGUID",
                    "translator" : {
                        "className" :
                            "com.identityblitz.idp.store.ldap.core.translator.ObjectGUIDTranslator"
                }
            ],
        },
        …
    ]
}

Using a self-developed translator, it is necessary to create a program with an external translator and assemble it into a JAR file.

The created JAR file should be copied to the servers with Blitz Identity Provider applications. The JAR file location address should be specified in the Java option extensionsDir.

Example:

export JAVA_OPTS="${JAVA_OPTS} -DextensionsDir=/usr/share/identityblitz/extensions"

Configuring the call to an external electronic signature verification service#

To integrate with an external electronic signature verification service, a special signature verification library must be developed. The system will perform electronic signature verification through this system after this library is specified in the configuration file, in the blitz.prod.local.idp.login.methods.x509 section, as follows:

"x509-verifier" : {
    "javaClass" : "<Java-класс реализации коннектора>",
    "pathToJar" : "/usr/…/check-signature-1.0.0.jar",
    "signatureValidationServiceUrl" : "<адрес сервиса >"
}

Configuring the call of the electronic signature plug-in#

To set non-standard settings for calling the e-signature plugin when a user requests login by e-signature, it is necessary to create a plugin settings block with overridden plugin call settings in the blitz.prod.local.idp.login.methods.x509 section of the configuration file:

"plugin" : {
    "allModulesEnabled" : false,
    "capi" : {
        "providers" : [
            {
                "name" : "Crypto-Pro GOST R 34.10-2001 Cryptographic Service Provider",
                "pinMode" : 1
            },
            {
                "name" : "Crypto-Pro GOST R 34.10-2012 Strong Cryptographic Service Provider",
                "pinMode" : 1
            },
            {
                "name" : "Infotecs Cryptographic Service Provider",
                "pinMode" : 1
            },
            {
                "name" : "Signal-COM GOST R 34.10-2012 (512) Cryptographic Provider",
                "pinMode" : 1
            },
            {
                "name" : "Signal-COM CPGOST Cryptographic Provider",
                "pinMode" : 1
            },
            {
                "name" : "Signal-COM GOST R 34.10-2012 (256) Cryptographic Provider",
                "pinMode" : 1
            }
        ],
        "stores" : []
    },
    "modules" : [
        "capi",
        "Aladdin R.D. Unified JaCarta",
        "ISBC ESMART",
        "Rutoken",
        "SafeNet"
    ]
}

In the configuration block you can remove unnecessary modules from modules and providers to limit the list of available electronic signature means. Also for used providers it is possible to configure the mode of pin code input according to documentation on plugin.

If it is necessary to display only signature keys from the Windows OS registry, accessible via MS CAPI, then the settings block should look as follows:

"plugin": {
    "allModulesEnabled": false,
    "capi": {
        "stores": [
            {
                "name": "My"
            }
        ]
    },
    "modules": []
}

Configuring CAPTCHA#

To display the CAPTCHA service for logins and passwords you need to create a configuration file and load the required files (CSS and JS).

Changes in the configuration file must be done:

  • in the blitz.prod.local.idp.captcha settings block. An example of a setting entry is shown below:

"captcha" : {
    "exampleCaptcha": {
        "operations": [
            {
                "call": {
                    "headers": [
                        "accept:application/json",
                        "Authorization:Bearer ${cfg.bearerToken}"
                    ],
                    "method": "post",
                    "url": "https://captcha.example.com/captcha/1.0.0/check?uniqueFormHash=${ste.uniqueFormHash}&code=${ocp.code}&options[system]=${cfg.system}&options[token]=${cfg.token}"
                },
                "check": {
                    "errRegExp": {},
                    "okRegExp": {
                        "error": "0"
                    }
                },
                "name": "check",
                "newState": {
                    "uniqueFormHash": "${rsp.result.uniqueFormHash-}"
                }
            },
            {
                "call": {
                    "headers": [
                        "accept:application/json",
                        "Authorization:Bearer ${cfg.bearerToken}"
                    ],
                    "method": "get",
                    "url": "https://captcha.example.com/captcha/1.0.0/create?type=${cfg.type}&options[system]=${cfg.system}&options[token]=${cfg.token}"
                },
                "name": "create",
                "newState": {
                    "uniqueFormHash": "${rsp.result.uniqueFormHash-}"
                }
            },
            {
                "call": {
                    "headers": [
                        "accept:application/json",
                        "Authorization:Bearer ${cfg.bearerToken}"
                    ],
                    "method": "post",
                    "url": "https://captcha.example.com/captcha/1.0.0/refresh?uniqueFormHash=${ste.uniqueFormHash}&type=${cfg.type}&options[system]=${cfg.system}&options[token]=${cfg.token}"
                },
                "name": "refresh"
            }
        ],
        "plainParams": {
            "type": "arithmetic"
        },
        "secureParams": {
            "bearerToken": "<access_token>",
            "system": "<system_id>",
            "token": "<system_token>"
        }
    }
}

This block contains parameters for calling three methods of CAPTCHA service (create, check, refresh), as well as secret parameters - access token (bearerToken), system identifier (system), and system token (token).

  • in the block of login settings blitz.prod.local.idp.password. Inside this block add captcha block and configure it according to the example:

"captcha" : {
  "enabled": true,
  "initJs": "require(['https://demo.reaxoft.ru/themes/default/assets/js/passwordCaptcha.js', 'captcha-conf'], function(captcha, conf){ captcha(conf, 'https://demo.reaxoft.ru/themes/default/assets/css/passwordCaptcha.css');});",
  "mode": {
    "type": "always_on"
  },
  "name": "exampleCaptcha"
}

In this block you should configure the following parameters:

  • enabled - indicates whether CAPTCHA is enabled or not (true/false);

  • initJs - contains links to the Javascript and CSS loaded on the login page and required to display/invoke CAPTCHA on login page;

  • mode - CAPTCHA display mode, the following modes are provided:

    • always_on - CAPTCHA is always displayed;

    • on_header - CAPTCHA is displayed if the request has the header specified in the name parameter and the value specified in the value parameter.

    • by_brute_force_protection - A CAPTCHA is displayed if Blitz Identity Provider has detected password brute force on a specific account or mass password brute force on all accounts.

When using by_brute_force_protection mode, it is required to additionally create bruteForceProtection settings block with the following settings in blitz.prod.local.idp.password block:

  • disabled - whether the protection is disabled or not (true/false);

  • captcha - whether to use the CAPTCHA test when the protection is triggered (true/false);

  • delay - login delay time in seconds (applies if CAPTCHA usage is disabled);

  • block system in the thresholds setting - if system-level protection is required (protection against brute force on different logins). The settings are:

    • minAttemptsToActivate - minimum number of passed inputs to activate the protection mechanism based on the system statistics (100 inputs by default);

    • timeWindowInMin - time window for collecting statistics on the ratio of successful and unsuccessful inputs in minutes, must be even (100 minutes by default);

    • failedAttemptsPercent, the turnOff setting is the threshold for turning off automatic protection, in percent;

    • failedAttemptsPercent, the turnOn setting is the threshold for turning on automatic protection, in percent.

    • forced - enable forced protection for all (true/false).

  • system block in the thresholds setting - if protection at the level of individual users is required (protection against password mining for a particular user). The settings are specified:

    • ttlInSec - the period for which the counter of unsuccessful logins by user is accumulated in seconds (default is 3600 seconds);

    • failedAttempts, the turnOn setting is the number of invalid logins per period after which protection will be enabled for the account.

Example of bruteForceProtection block settings (only user-level protection is enabled):

"bruteForceProtection" : {
    "delay" : 0,
    "captcha" : true,
    "disabled" : false,
    "thresholds" : {
        "user" : {
            "failedAttempts" : {
                "turnOn" : 5
            },
            "ttlInSec" : 3600
        }
    }
}

Example of bruteForceProtection settings (user-level and system-level protection enabled):

"bruteForceProtection" : {
    "disabled": false,
    "delay" : 0,
    "captcha" : true,
    "thresholds" : {
        "system" : {
            "minAttemptsToActivate": 1000,
            "timeWindowInMin": 180,
            "failedAttemptsPercent" : {
                "turnOff" : 20,
                "turnOn" : 30
            },
            "forced" : false
        },
        "user" : {
            "ttlInSec": 3600,
            "failedAttempts" : {
                "turnOn" : 5
            }
        }
    }
}

If you use Google’s reCAPTCHA v3 service as a CAPTCHA, you must:

  • set the following settings in blitz.prod.local.idp.captcha:

"captcha" : {
  "reCAPTCHAv3" : {
    "operations" : [
      {
        "call" : {
          "headers" : [],
          "method" : "post",
          "url" : "https://www.google.com/recaptcha/api/siteverify?secret=${cfg.secret}&response=${ocp.response}"
        },
        "check" : {
          "errRegExp" : {},
          "okRegExp" : {
            "score" : "1\\.0|0\\.(5|6|7|8|9)",
            "success" : "true"
          }
        },
        "name" : "verify"
      }
    ],
    "plainParams" : {
      "sitekey" : "SITE_KEY"
    },
    "secureParams" : {
      "secret" : "SITE_SECRET"
    }
  }
}

Instead of SITE_KEY and SITE_SECRET you should fill in the values obtained when registering Google reCAPTCHA v3 on the site https://g.co/recaptcha/v3. You should also adjust the value in the score parameter - set the required threshold for successful passing of the check (in the example, the threshold is set not lower than 0.5).

  • set the following settings in blitz.prod.local.idp.password.captcha:

"captcha" : {
  "mode" : {
    "_name" : "X-Captcha-Check",
    "_value" : "true",
    "_type" : "on_header",
    "type" : "always_on"
  },
  "enabled" : true,
  "initJs" : "require(['/blitz/assets/blitz-common/javascripts/recaptcha_v3.js', 'captcha-conf'], function(captcha, conf){ captcha(conf);});",
  "name" : "reCAPTCHAv3"
}

To add a CAPTCHA to the confirmation page for linking a user account to an account from an external identity provider, you must set the following settings in blitz.prod.local.idp.externalIdps.captcha:

"captcha" : {
  "mode" : {
    "_name" : "X-Captcha-Check",
    "_value" : "true",
    "_type" : "on_header",
    "type" : "always_on"
  },
  "enabled" : true,
  "initJs" : "require(['/blitz/assets/blitz-common/javascripts/recaptcha_v3.js', 'captcha-conf'], function(captcha, conf){ captcha(conf);});",
  "name" : "reCAPTCHAv3"
}

To add a CAPTCHA to the user registration page, you must set the following settings in blitz.prod.local.idp.provisioning.registration.captcha:

"captcha" : {
  "mode" : {
    "_name" : "X-Captcha-Check",
    "_value" : "true",
    "_type" : "on_header",
    "type" : "always_on"
  },
  "enabled" : true,
  "initJs" : "require(['/blitz/assets/blitz-common/javascripts/recaptcha_v3.js', 'captcha-conf'], function(captcha, conf){ captcha(conf);});",
  "name" : "reCAPTCHAv3"
}

To add a CAPTCHA to the password recovery page, you must set the following settings in blitz.prod.local.idp.provisioning.recovery.captcha:

"captcha" : {
  "mode" : {
    "_name" : "X-Captcha-Check",
    "_value" : "true",
    "_type" : "on_header",
    "type" : "always_on"
  },
  "enabled" : true,
  "initJs" : "require(['/blitz/assets/blitz-common/javascripts/recaptcha_v3.js', 'captcha-conf'], function(captcha, conf){ captcha(conf);});",
  "name" : "reCAPTCHAv3"
}

Configuring sending events to the queue server#

The following events can be sent to the queue server:

  • user registration (USER_REGISTERED);

  • password changed (USER_PASSWORD_SET);

  • marker of session cancellations changed (USER_CRID_CHANGED);

  • user attribute changes (USER_ATTRIBUTE_CHANGED);

  • clearing user attributes (USER_ATTRIBUTE_REMOVED);

  • user removed (USER_REMOVED);

  • external user account bound (FEDERATION_POINT_BOUND);

  • external user account detached (FEDERATION_POINT_UNBOUND);

  • revocation of the authorization (scopes) issued to the application (SCOPES_REVOKED);

  • group created (GROUP_CREATED);

  • attributes of group updated (GROUP_UPDATED);

  • group removed (GROUP_REMOVED);

  • group member added (GROUP_MEMBER_ADDED);

  • group member removed (GROUP_MEMBER_REMOVED).

To send events to the queue you should create a block blitz.prod.local.idp.events with the following code (using the example of user registration and password change):

"events" : {
    "drivers" : {
        "rabbit_driver" : {
            "properties" : {},
            "server" : {
                "host" : "<RMQ_HOST>",
                "port" : 5672
            },
            "type" : "RMQ",
            "user" : {
                "password" : "<RMQ_PASS>",
                "username" : "<RMQ_USERNAME>"
            }
        }
    },
    "routes" : {
        "USER_PASSWORD_SET" : [
            "password_sync"
        ],
        "USER_REGISTERED" : [
            "registration"
        ]
    },
    "targets" : [
        {
            "discardList" : "PSWD_SYNC_DISCARD",
            "driver" : {
                "ext" : {
                    "exchange_name" : "users",
                    "routing_key" : "pwd_sync"
                },
                "id" : "rabbit_driver"
            },
            "encCertificate" : "rmqkey",
            "name" : "password_sync",
            "redelivery" : 3
        },
        {
            "discardList" : "REG_DISCARD",
            "driver" : {
                "ext" : {
                    "exchange_name" : "users",
                    "routing_key" : "registration"
                },
                "id" : "rabbit_driver"
            },
            "encCertificate" : "rmqkey",
            "name" : "registration",
            "redelivery" : 3
        }
    ]
}

Following settings should be configured:

  • RMQ_HOST - RabbitMQ queue server domain;

  • RMQ_USERNAME - user name for the queue server;

  • RMQ_PASS - password for the queue server.

In addition, to encrypt passwords sent to the queue (only for USER_REGISTERED and USER_PASSWORD_SET messages), the encCertificate parameter should specify the alias of the electronic signature key (in the standard BlitzIdPKeystore.jks key store) with which to encrypt passwords in messages.

Configuring the use of a queue server as a message broker#

Blitz Identity Provider uses a built-in message broker to handle asynchronous tasks, using a database to track tasks.

If the intensity of requests to the Blitz Identity Provider is high, it may be appropriate to use the RabbitMQ queue server as a message broker. To do this, you need to make the following settings in the RabbitMQ console (usually, http://hostname:15672/):

  • create a queue with the name blitz-tasks (in the “Queues “ menu of the console);

  • create an exchange named blitz-tasks-exh (in the “Exchanges “ menu of the console) and configure binding on the blitz-tasks queue with a routing_key named blitz-tasks;

  • create the blitz user (in the “Admin” menu of the console) and assign rights to the created queue to it.

After configuring RabbitMQ, adjust the settings in blitz.conf - in the blitz.prod.local.idp.tasks block set broker-type to rmq and set the connection settings to RabbitMQ in the broker-rmq block:

  • set the name blitz-tasks-exh in the exchange parameter;

  • set the queue parameter in the executionRules block and the name parameter in the queues block to blitz-tasks;

  • set the user name (blitz) in the username parameter in the user block;

  • set the user’s password in the password parameter in the user block - the password will be encrypted after Blitz Identity Provider is launched;

  • specify the address and port of the connection to RabbitMQ in the host and port parameters of the server block;

  • if necessary, adjust other parameters defining the size of the connection pool (poolSize), the number of channels (channelSize), the waiting time for a response from the queue server (ackTimeout);

  • if necessary, adjust the task processing broker settings that determine the number of attempts (maxAttempts) to re-process tasks in case of an error, the time between attempts (redeliveryDelayInSec), the size of the processed message bundle (dequeueBatchSize), the queue check period (dequeuePeriodInSec), the number of handlers (executorPoolSize):

A configuration example is shown below:

"tasks" : {
    "broker-type" : "rmq",
    "broker-rmq" : {
        "consumer" : {
            "poolSize" : 2
         },
         "exchange" : "blitz-task-exh",
         "publisher" : {
             "ackTimeout" : 15,
              "channelsSize" : 8,
              "poolSize" : 2
         },
         "server" : {
             "host" : "RMQ_HOST",
             "port" : 5672
         },
         "user" : {
             "password" : "CHANGE_ME",
             "username" : "blitz"
         }
    },
    "executionRules" : [
        {
            "maxAttempts" : 2,
            "queue" : "blitz-tasks",
            "redeliveryDelayInSec" : 60
        }
    ],
    "queues" : [
        {
            "dequeueBatchSize" : 10,
            "dequeuePeriodInSec" : 30,
            "executorPoolSize" : 5,
            "name" : "blitz-tasks"
        }
    ]
}

Configuring object store in Couchbase Server#

You can reassign the internal Blitz Identity Provider buckets in Couchbase Server used for data storage. For the following datasets, you can specify the need to use different 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"
  },
  …
}

Setting the storage time of objects in the database#

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,
  …
}

Configuring the Blitz Identity Provider domain#

You can change the Blitz Identity Provider domain by editing domain settings configuration file in the blitz.prod.local.idp.net settings block.

Example of configuration:

"net" : {
"domain" : "demo.identityblitz.com"
}

If necessary, change the domain setting in blitz.prod.local.idp.lang in the portal-lang-cookie block (see Multilanguage support).

The example of configuration file excerpt:

"lang" : {
  …
  "portal-lang-cookie" : {
    "domain" : "identityblitz.com",
    …
  }
}

If necessary, you can change the path to applications (by default, applications are available using the /blitz path). You can edit the path in the play.conf configuration file. It is necessary to change the context parameter in the play.http block:

"http" : {
"context" : "/blitz",
...
}

Change the Blitz Identity Provider domain and path in the /blitz-config/saml/conf/relying-party.xml, /blitz-config/saml/metadata/idp-metadata.xml files.

An example of changing settings in relying-party.xml:

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<ns18:RelyingPartyGroup …>
  <ns18:AnonymousRelyingParty
    provider="https://demo.identityblitz.com/blitz/saml"
    defaultSigningCredentialRef="IdPCredential"/>
  <ns18:DefaultRelyingParty
    provider="https://demo.identityblitz.com/blitz/saml"
    defaultSigningCredentialRef="IdPCredential">
    …
  </ns18:DefaultRelyingParty>
  …
</ns18:RelyingPartyGroup>

An example of changing settings in idp-metadata.xmll:

<?xml version="1.0" encoding="UTF-8"?>
<EntityDescriptor … entityID="https://demo.identityblitz.com/blitz/saml">
  <IDPSSODescriptor …>
    …
    <ArtifactResolutionService
      Binding="urn:oasis:names:tc:SAML:1.0:bindings:SOAP-binding"
      Location="https://demo.identityblitz.com/blitz/saml/profile/SAML1/SOAP/ArtifactResolution"
      index="1"/>
    <ArtifactResolutionService
      Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP"
      Location="https://demo.identityblitz.com/blitz/saml/profile/SAML2/SOAP/ArtifactResolution"
      index="2"/>
    <SingleLogoutService
      Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
      Location="https://demo.identityblitz.com/blitz/saml/profile/SAML2/Redirect/SLO"
      ResponseLocation="https://demo.identityblitz.com/blitz/saml/profile/SAML2/Redirect/SLO"/>
    <SingleLogoutService
      Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Plain-Redirect"
      Location="https://demo.identityblitz.com/blitz/saml/profile/SAML2/Redirect/Plain/SLO"
      ResponseLocation=
        "https://demo.identityblitz.com/blitz/saml/profile/SAML2/Redirect/Plain/SLO"/>
    <SingleLogoutService
      Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP"
      Location="https://demo.identityblitz.com/blitz/saml/profile/SAML2/SOAP/SLO" />
    …
    <SingleSignOnService
      Binding="urn:mace:shibboleth:1.0:profiles:AuthnRequest"
      Location="https://demo.identityblitz.com/blitz/saml/profile/Shibboleth/SSO"/>
    <SingleSignOnService
      Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
      Location="https://demo.identityblitz.com/blitz/saml/profile/SAML2/POST/SSO"/>
    <SingleSignOnService
      Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST-SimpleSign"
      Location="https://demo.identityblitz.com/blitz/saml/profile/SAML2/POST-SimpleSign/SSO"/>
    <SingleSignOnService
      Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
      Location="https://demo.identityblitz.com/blitz/saml/profile/SAML2/Redirect/SSO"/>
    <SingleSignOnService
      Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Plain-Redirect"
      Location="https://demo.identityblitz.com/blitz/saml/profile/SAML2/Redirect/Plain/SSO"/>
  </IDPSSODescriptor>
  <AttributeAuthorityDescriptor …>
    …
    <AttributeService
      Binding="urn:oasis:names:tc:SAML:1.0:bindings:SOAP-binding"
      Location="https://demo.identityblitz.com/blitz/saml/profile/SAML1/SOAP/AttributeQuery"/>
    <AttributeService
      Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP"
      Location="https://demo.identityblitz.com/blitz/saml/profile/SAML2/SOAP/AttributeQuery"/>
    …
    </AttributeAuthorityDescriptor>
</EntityDescriptor>

Advanced storage 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 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, the Blitz Identity Provider takes an existing LDAP directory connection from the connection pool. After the query is completed, the 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 the 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"
  },
  …
}

Blocking inactive users#

Blitz Identity Provider tracks the time of last user activity. It is possible to block user accounts that have been inactive for a long time. To activate this feature, run the lockinactive.sh script in cron. The script is located in the /usr/share/identityblitz/blitz-console/bin directory on the server with the blitz-console application. It is recommended to run the script once a day during minimal activity on the system. Before running the script it is necessary to edit it in a text editor - install:

  • inactive_period - required period of inactivity (in days), after which the account should be blocked;

  • range_size is the range of account coverage (in days), accounts whose last activity was between (current date - inactive_period - range_size) and (current date - inactive_period) will be blocked.

Blitz Identity Provider also allows you to automatically lock an account at the time of a login attempt if the account has been inactive for a long period of time. To enable this feature, add the blitz.prod.local.idp.lock configuration block with the inactivity block having a limit setting in seconds that specifies the maximum allowed inactivity period after which the account will be locked out for inactivity when a login attempt is made. In the checkInterval setting, you can specify the minimum period in seconds, no more often than which the account will be checked for inactivity period when logging in.

Example of configuration:

"lock" : {
    "inactivity" : {
        "checkInterval" : 86400,
        "limit" : 31536000
    }
}

In the settings of the password recovery service, you can enable the mode that will allow unlocking an account locked due to inactivity in case of successful recovery of a forgotten password (see Access recovery).

Prohibit reuse of the remote user ID#

Blitz Identity Provider keeps track of previously used user IDs so that they cannot be reused after a user account has been deleted for a specified period of time. To do this, add the following remove section to the blitz.prod.local.idp.provisioning block, specifying the number of days (days) during which the user ID cannot be used for re-registration:

"provisioning" : {
  …
  "remove": {
    "mode": "keepRemovedId",
    "days": 365
  }
}

Configuring user groups#

To enable the ability to view user groups, you must add blitz.prod.local.idp.groups following settings block:

"groups": {
  "profiles": [
    {
      "type": "mirror",
      "id": "orgs",
      "groupStore": "389ds",
      "attrsMap": {
        "name": "displayname",
      },
      "filter": "objectClass=group"
    }
  ],
  "stores": {
    "list": [
      {
        "type": "ldap_based",
        "id": "389ds",
        "desc": "Группы",
        "ldapStore": "389ds",
        "baseDN": "ou=external,ou=groups,dc=test",
        "searchScope": "SUB",
        "idAttrName": "cn",
        "membersAttrName": "uniqueMember",
        "memberOfAttrName": "memberOf",
        "newGroupAttrs": [
          {
            "attr": "objectclass",
            "format": "strings",
            "value": "top,groupOfUniqueNames,group"
          },
          {
            "attr": "dn",
            "format": "string",
            "value": "cn=${id},ou=external,ou=groups,dc=test"
          }
        ]
      }
    ]
  }
}

Specifics of settings:

  • in profiles.groupStore, stores.list.id, stores.ldapStore must be the identifier of the LDAP directory used to store users;

  • in profiles.attrsMap and stores.list.idAttrName must contain group attributes (class groups), e.g. name. Attribute names can be named differently if desired, only LDAP attributes of type String are supported;

  • in stores.list.baseDN you should check (and correct if necessary) the path for storing organizations in LDAP. If the path is corrected, also adjust the "value": "cn=${id},ou=external,ou=groups,dc=test" setting accordingly.

Configuring trusted certificates of FIDO2 and U2F security key providers#

Blitz Identity Provider allows you to remap the list of intermediate and root certificates of security key providers (WebAuthn, Passkey, FIDO2, U2F) (see Login with security keys (WebAuthn, Passkey, FIDO2) and Login confirmation with security keys (WebAuthn, Passkey, FIDO2, U2F)). To do this, in the blitz.prod.local.idp.webAuthn.trustedStores settings block, specify the settings containing the type (type), file path (path) and password (password) of access to the key container to be used to verify the signature of attestation objects generated during security key registration. The standard key container is automatically updated when new versions of Blitz Identity Provider are installed and contains current root and intermediate certificates of TPM modules, FIDO, as well as Apple and Google certificates required to verify the signature of attestation objects. If you want to restrict security keys to devices from specific vendors, you must remove unnecessary root and intermediate certificates from the key container.

Example of configuration:

"webAuthn" : {
    …
    "trustedStores" : [
        {
            "password" : "*****",
            "path" : "webAuthn-trusted-ca.jks",
            "type" : "jKS"
        }
    ],
    …
}

OIDC Discovery Service Settings#

Blitz Identity Provider automatically posts the OIDC Discovery service according to the settings specified in Blitz Identity Provider. As part of the service, you can specify a documentation address for the OIDC service. To specify your own documentation address, you must specify the serviceDocumentationUrl setting in the blitz.prod.local.idp.oauth settings block with the value of the documentation reference address.

Changing the call addresses of external identity providers#

When implementing Blitz Identity Provider, you may need to configure calls from Blitz Identity Provider servers to external identity provider handlers not directly, but through a proxy server. In this case, it is necessary to change the default addresses of handlers of external identity providers to the addresses registered on the proxy server. To correct the handler addresses, you need to change the values of the authUri, tokenUri, dataUri settings in the corresponding blocks of the external Identity Provider settings in blitz.prod.local.idp.federation.

Example of settings for logging in through an external Google provider:

"federation" : {
  "points" : {
    "google" : [
      {
        …
        "authUri" : "https://accounts.google.com/o/oauth2/auth",
        "tokenUri" : "https://accounts.google.com/o/oauth2/token",
        "dataUri" : "https://www.googleapis.com/oauth2/v1/userinfo?alt=json",
        …
      },
      …
    ]
  }
}

Configuring an external SAML login provider#

Blitz Identity Provider allows you to configure login through an external identity provider running SAML 2.0.

To do this, in the blitz.prod.local.idp.federations configuration block, create an external provider saml with the following settings:

  • name is the system name of the external identity provider;

  • humanReadableName - description of the external identity provider;

  • clientId is the service provider name (EntityId) assigned to the Blitz Identity Provider when registering with the external SAML Identity Provider;

  • signAuthnReq - specifies whether the Blitz Identity Provider should sign the SAML request sent to the external identity provider;

  • checkAssertionSign - determines whether to check the signature of SAML assertions received from an external identity provider (for PROD environments, it is mandatory to include signature verification);

  • credentials block with access settings to the key container used for signing requests to the SAML Identity Provider. It is configured optionally in case a separate key container is required for interaction with an external identity provider. If the setting is not specified, keys will be taken from the main keystore configured in the blitz.prod.local.idp.keystore block (in this case the name of the identity provider from the name setting will be used as alias). The settings are:

    • alias is the name of the key in the container;

    • keystore is a configuration block containing the container type (type), which can be JCEKS or BKS, as well as the container path (path) and the container password (password);

  • idpMetaPath - path to the file where the external identity provider metadata (XML file with IDP metadata) is stored;

  • userMatching configuration block - specifies the rules of account matching:

    • in the type setting is an indication that the basic (value builder) account binding setting is used;

    • in the mapping setting - rules for mapping accounts from the external SAML Identity Provider to accounts in the Blitz Identity Provider;

    • in the matchingRules setting - rules for migrating SAML assertions from an external identity provider to account attributes in the Blitz Identity Provider;

    • requireLogInToBind - feature “Prompt the user to enter a login and password for binding if the account has not been identified “;

    • strictMatching - a feature “Require password input if account has been identified”;

    • uniqueMatching – a feature “Only one account by the configured matching rules should be found for binding”.

Example of external identity provider settings:

"federation" : {
  "points" : {
    "saml" : [
      {
       "name" : "demo-idp",
        "humanReadableName" : "External SAML IDP",
        "clientId" : "login.company.com",
        "signAuthnReq" : true,
        "checkAssertionSign" : true,
        "_credentials" : {
            "alias" : "demo-idp",
            "keyStore" : {
              "password" : "*****",
              "path" : "demo-idp-key.jks",
              "type" : "JCEKS"
            }
        },
        "idpMetaPath" : "demo-idp-metadata.xml",
        "userMatching" : {
          "type" : "builder",
          "mapping" : [
            {
              "attr" : "urn:saml:mail",
              "master" : false,
              "value" : "${email}"
            }
          ],
          "matchingRules" : [
            [
              {
                "attr" : "urn:saml:mail",
                "value" : "${email}"
              }
            ]
          ],
          "requireLogInToBind" : false,
          "strictMatching" : false,
          "uniqueMatching" : false
        }
      }
    ],
    …
  }
}

After creating the external provider settings, it is necessary to include it in the list of available external identity providers. To do this, in the blitz.prod.local.idp.login settings block in the list of authentication methods (methods) in the list of external login providers externalIdps add the external provider c fedPoint corresponding to the configured one.

Configuration example to enable an external identity provider with type saml and name demo-idp:

"login" : {
  …
  "methods" : {
    …
    "externalIdps" : {
      "idps" : [
        …
        {
          "fedPoint" : "saml:demo-idp"
        },
        …
      ],
      …
    },
    …
  },
  …
}

Customize the logo for the login button via the external login provider according to the Customize login button logos through external identity providers instructions.

Enable logging of incomplete login attempts#

In Blitz Identity Provider, all events are logged when the process that caused them has finished. This is normal for most events, because the processes are short-term.

Among all the events being recorded, there are some important events related to user login. If the login is successful, a security event is logged at the very end of the login process, indicating who logged in, where and when, what authentication methods were used, IP address, UserAgent and many other details.

The login process can be a complex, depending on the configurations made during implementation. It may not always be sufficient to only enter a username and password and an additional login confirmation is required, or during the login process the user will interact with auxiliary applications (pipes), for example, to update a contact, configure a passkey or answer a question about whether he/she trusts the device/browser. If a user stops logging in at any point during this process, it may not be completed, and as a result, an audit event will not be created for that incomplete process. Depending on at what point this happens, this could be a security issue. For example, if a user simply opened the login page and did not enter a username and password, then logging such an event in the security log is has no particular interest. But if the user entered the correct username and password, but got to a login confirmation screen that he didn’t pass, then such a security event would be a good reason to record. Perhaps the malicious user was brute-forcing the password and was able to successfully pick it, but was unable to pass the second authentication factor. A security event would make this situation known if it were recorded and analyzed.

To activate event logging of unsuccessful (incomplete) logins it is necessary to add parameters in the blitz.prod.local.idp.login settings block:

  • postponeEnabled - value true if the mechanism is enabled;

  • postponeTtl - time in seconds after which a pending audit event is logged if the login has not been completed.

In case RabbitMQ is used to process tasks, you must make an additional queue named <main queue name>-postpone for the main task queue and set the following arguments for it:

x-dead-letter-exchange = <используемый exchange>
x-dead-letter-routing-key = <основная очередь>

Also for the created queue, you need to configure binding to the exchange used.

Configuring the transfer of security events to a file or Kafka#

In Blitz Identity Provider, you can configure the logging of security events to one or more receivers. The configuration is set in the blitz.prod.local.idp.audit configuration block.

The following settings must be configured:

  • emitters - defines the list of receivers of audit records. For each receiver the settings block is filled in:

    • type - receiver type. Possible values:

      • audit-store - the record is made in the DBMS;

      • log - the record is made to the logger with the name logback.

    • enabled - optional setting - determines whether the receiver is enabled or not;

    • include - optional setting - lists the types of security events (see the table below), which are used to write to the receiver. If the setting is not specified, all security events are written;

    • exclude - optional setting - lists the types of security events (see table below) that should not be written to the receiver. If the setting is not specified, no events are excluded. If the setting is specified together with include, the list of events is first defined by the include setting, and then the events specified in exclude are excluded from it. It is recommended not to use both include and exclude settings together, but to use only one of them;

    • logger - optional setting - specified only for the receiver with log type. Allows you to define the name of the logger. If the setting is not specified, the recording is made to the logger with the name AUDIT;

    • name - optional setting - specified for receivers with types log and kafka. Specifies the name of the receiver, since multiple receivers can be configured for these receiver types. If the setting is not specified, log and kafka are used as receiver names;

    • bootstrapServers - a mandatory setting for a receiver with type kafka - specifies a list of addresses for initial connection to the Kafka cluster;

    • topic - mandatory setting for receiver with type kafka - the name of the Kafka topic to which the event should be sent;

    • securityProtocol - optional setting for receiver with type kafka - in case of using SASL connection may not be specified. In case of connection via SSL, the value SSL must be specified in the setting;

    • sasl - optional configuration block for receiver with type kafka - specifies connection parameters when using SASL authentication to connect to Kafka:

      • jaasConfig is a connection string that can use the substitution parameters from secureParams;

      • mechanism is the value of PLAIN;

      • secureParams - block with parameters that will be encrypted in the configuration file when the server is started.

    Block example:

    "sasl" : {
    "jaasConfig" : "org.apache.kafka.common.security.plain.PlainLoginModule required username=\"alice\" password=\"${pswd}\"",
    "mechanism" : "PLAIN",
    "secureParams" : {
        "pswd" : "Содержимое зашифруется при запуске",
    }
},

    • ssl - optional configuration block for receiver with type kafka - sets SSL parameters for connection to Kafka:

      • enabledProtocols - lines with the list of enabled protocols;

      • keyStore is a settings block with parameters for accessing the Blitz Identity Provider key container. It contains type, path, password settings;

      • trustedStore - settings block with parameters of access to the container with trusted certificates. It contains type, path, password settings;

      • keyPassword - optional setting - the password to access the key.

    Block example:

    "securityProtocol" : "SSL",
"ssl" : {
    "enabledProtocols" : ["TLSv1.2,TLSv1.3"],
    "keyStore" : {
        "password" : "CHANGE-ME",
        "path" : "/etc/blitz-config/bip-d1app01-1.jks",
        "type" : "JKS"
    },
    "trustedStore" : {
        "password" : "CHANGE-ME",
        "path" : "/etc/blitz-config/ca.jks",
        "type" : "JKS"
    },
    "keyPassword": "CHANGE-ME"
},

    • tuning - optional settings block for a receiver with type kafka - specifies optional producer settings for interaction with Kafka. Parameter names must be specified with a dot as in the Kafka documentation.

    Block example:

    "tuning": {
    "client.id": "BlitzKafka"
}

    • emitAtLeastOneOf - optional setting - the list of receivers is specified, it is enough to record events in any of them for the operation to be considered successful;

    • emitToAllOf - optional setting - specifies the list of receivers that must receive confirmation of successful event recording for the operation to be considered successful. If the emitAtLeastOneOf and emitToAllOf settings are not specified, then confirmation from all configured receivers is mandatory;

    • emitTimeoutInSec - optional setting - defines the maximum response time from the receiver in response to event record requests. If the setting is not specified, the wait is 60 seconds.

    Example of audit recording settings in log, DBMS and Kafka at the same time:

    "audit": {
    "emitters": [
        {
            "type": "log",
            "name": "users-log",
            "enabled": true,
            "logger": "AUDIT",
            "exclude": ["admin_added", "admin_pswd_changed", "admin_removed", "admin_roles_changed",
                        "config_changed"]
        },
        {
            "type": "log",
            "name": "admins-log",
            "enabled": true,
            "logger": "AUDITADMIN",
            "include": ["admin_added", "admin_pswd_changed", "admin_removed", "admin_roles_changed",
                        "config_changed"]
        },
        {
            "type": "audit-store",
            "enabled": true
        },
        {
            "type" : "kafka",
            "enabled": true,
            "name" : "kafka",
            "include": ["login"],
            "bootstrapServers" : ["infra-kfk01:9443"],
            "topic" : "blitz_audit",
            "securityProtocol" : "SSL",
            "ssl" : {
                "enabledProtocols" : ["TLSv1.2,TLSv1.3"],
                "keyStore" : {
                    "password" : "CHANGE-ME",
                    "path" : "/etc/blitz-config/bip-app01.jks",
                    "type" : "JKS"
                },
                "trustedStore" : {
                    "password" : "CHANGE-ME",
                    "path" : "/etc/blitz-config/ca.jks",
                    "type" : "JKS"
                }
            },
        }
    ],
    "emitAtLeastOneOf": ["users-log","admins-log","kafka"],
    "emitToAllOf": ["audit-store"],
    "emitTimeoutInSec": 30
}

When logging an audit to the logger, you can configure the logger using the logback.xml configuration file (see for more information <https://logback.qos.ch/documentation.html>`__). Example of configuring the ``AUDIT logger in the logback.xml configuration file:

…
    <appender name="AUDIT" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <file>${dir.logs}/audit-${app.name}.log</file>
        <encoder>
            <pattern>%date - [%level] -[%file:%line] - %message%n%xException{20}</pattern>
        </encoder>
        <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
            <fileNamePattern>${dir.logs}/archive/audit-${app.name}.%d{yyyy-MM-dd}.log.gz</fileNamePattern>
            <maxHistory>90</maxHistory>
            <totalSizeCap>5GB</totalSizeCap>
        </rollingPolicy>
    </appender>

    <logger name="AUDIT" additivity="false">
        <appender-ref ref="AUDIT" />
    </logger>
…

Log entries example:

2022-11-22 14:03:01,576 - [INFO] -[LoggerEventEmitterDriver.scala:32] - {"ip":"172.25.0.1","timestamp":1669114981529,"id_store":"ldap01","authnDone":"true","process_id":"fe25a9b5-bdea-433b-86f9-42c96c197acd","user_agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/107.0.0.0 Safari/537.36","lp_id":"test-system","client_auth_method":"redirectUri","type":"login","object_id":"BIP-123456","protocol":"oAuth","subject_id":"BIP-123456","auth_methods":"webAuthn","session_id":"1fedbc79-4cc1-429f-bf62-d475d2617be2"}
2022-11-22 14:03:41,593 - [INFO] -[LoggerEventEmitterDriver.scala:32] - {"ip":"172.25.0.1","timestamp":1669115021586,"id_store":"ldap01","authnDone":"false","process_id":"b8f3ae70-7163-45b4-97af-cbd880ae1f7d","user_agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/107.0.0.0 Safari/537.36","lp_id":"test-system","client_auth_method":"redirectUri","type":"login","object_id":"BIP-123456","protocol":"oAuth","subject_id":"BIP-123456","auth_methods":"webAuthn","session_id":"1fedbc79-4cc1-429f-bf62-d475d2617be2"}

The set of record attributes may vary depending on the type of security event and the specifics of the login process. Attribute assignments in the audit record are shown in the table below:

Assigning attributes to an audit record

Attribute

Purpose and possible meanings

type

Security Event Type:

  • admin_added - administrator added

  • admin_pswd_changed - administrator password changed

  • admin_removed - administrator removed

  • admin_roles_changed - administrator roles changed

  • app_password_changed - the password for the application is set

  • attribute_changed - attribute added, changed or deleted

  • attribute_confirmed - attribute confirmed

  • auth - authentication performed (with OAuth 2.0 Resource Owner Password Credentials)

  • auth_failed - authentication error

  • auth_req - authentication request

  • authz_granted - OAuth authorization issued

  • authz_rejected - OAuth authorization denied

  • authz_revoked - OAuth authorization revoked

  • bind_ext_account - account is bound to an external account

  • config_changed - changed configuration settings

  • duo_put - Duo Mobile app is bound

  • duo_remove - Duo Mobile application is unbound

  • grant_right - assigning access rights

  • group_attr_changed - user group’s attribute has been changed or deleted

  • group_registered - user group created

  • group_removed - user group deleted

  • hotp_attached - HOTP generator is bound

  • hotp_detached - HOTP generator is unbound

  • internal_user_deleted - account deleted

  • locked_methods_changed - changed the list of blocked authentication methods

  • login - login is performed

  • login_failed - login error

  • login_stopped - unsuccessful login

  • logout - user is logged out

  • logout_req - logout request

  • member_added - the user is joined to the user group

  • member_removed - user excluded from the user group

  • needed_password_change - flag of password change necessity is set

  • recovery - account access restored

  • recovery_fail - access recovery failed

  • recovery_req - access recovery is request

  • registration - account is registered

  • registration_req - registration is request

  • required_factor_changed - changed user authentication mode

  • reset_user_password - password set by administrator

  • revoke_right - revoke access rights

  • send_email_code - confirmation code sent to email

  • send_push_code - confirmation code sent to Push

  • send_sms_code - confirmation code sent by SMS

  • token_exchange_failed - access token exchange denied

  • token_exchanged - access token has been exchanged

  • token_granted - access token issued

  • totp_attached - TOTP generator is bound

  • totp_detached - TOTP generator is unbound

  • unbind_ext_account - account is unbound from external account

  • user_locked - account locked

  • user_password_changed - user password changed

  • user_unlocked - account unlocked

  • web_authn_reg_key - security key added

  • web_authn_revoke_key - security key removed

alt_pswd_cause

The reason why the user was asked to change the password. Possible values:

  • password_expired - password expired

  • password_reset - password should be changed at the first login

  • password_policy_violated - password does not comply with password policy

attr_name

Installed, deleted or modified attribute name

auth_methods

Contains a list of authentication methods passed by the user. Possible values:

  • password - password authentication

  • spnego - login using an OS session

  • x.509 - login with electronic signature tool

  • qrCode - login by QR code

  • webAuthn - login or login confirmation with security keys

  • css - automatic login based on the results of user registration or password recovery

  • sms - one-time password by SMS

  • email - one-time email password

  • hotp - second factor of authentication with hardware key fob

  • totp is the second factor of authentication using the software TOTP confirmation code generator

  • externalIdps:<type>:<name> - login using an external identity provider (social network)

  • userApp - secondary authentication in the mobile application

  • outside_%NAME% - external logging in method named %NAME%

The presence of the prefix cls: before the method means that the login was performed using a long-term session, and that the primary login previously used those login methods listed after cls:

auth_soft_id

Authenticator application (when logging in by QR code)

authnDone

Whether authentication was performed at this login

captcha_passed

An indication that a CAPTCHA was asked when logging in

client_auth_method

A method for authenticating the application that called Blitz Identity Provider:

  • internal - for events triggered by internal Blitz Identity Provider applications

  • x.509 - for events triggered by SAML applications, provided that the SAML request came signed

  • Basic - for applications calling REST services that use Basic authorization

  • redirectUri - for applications that have identified themselves in the URL (e.g., specified their client_id in the URL parameter), but whose authentication has not been performed (it is not reliably known that this is actually calling the Blitz Identity Provider for this particular application)

  • Bearer - using access_token for authentication by mobile app with dynamic client_id/client_secret

dcId

Dynamic client_id

device

device ID

deviceFingerprint

Device imprint

dTyp

Device type (for dynamic registration)

email

E-mail address

entry_point

The type of interface used to register the user:

  • WEB - when registering from the Blitz Identity Provider web application

  • REST - when registering via Blitz Identity Provider REST services

error

Error (for unsuccessful events)

ext_account_id

External account ID

ext_account_name

Name of the external identity provider

ext_account_type

Type of External Identity Provider

failed_method

Indicates which authentication method the user was unable to pass

group_id

User group identifier

group_profile

User Group Usage Profile Identifier

id_store

User profile storage

ip

user IP address

ip_ctr

Country according to IP address

ip_st

Region according to IP address

ip_ct

City according to IP address

ip_lat

Latitude according to IP address

ip_lng

Longitude according to IP address

ip_rad

Surrounding by IP address

lp_id

The identifier of the application (EntityId for SAML or client_id for OIDC) that invoked the Blitz Identity Provider.

mobile

Mobile phone number

module

Identifier of the modified setting block

new_attr_value

New value of the installed or modified attribute

new_factor

New value of the attribute indicating the necessity to verify the second authentication factor

new_roles

Roles added to the administrator account

oauth_scopes

List of authorizations granted or revoked by the user

object_id

Identifier of the operation object (user for which the operation was performed)

old_attr_value

Previous value of the deleted or modified attribute

old_factor

Previous value of the attribute indicating the need to verify the second authentication factor

old_roles

Roles revoked from the administrator account

origin_app

Identifier of the application that initiated user registration or password recovery

process_id

Process ID

protocol

The protocol for the application to communicate with the Blitz Identity Provider. Possible values:

  • SAML - for SAML and WS-Federation

  • OAuth - for OpenID Connect and OAuth 2.0

  • simple - for proxy authentication-

  • internal - to log in to the User Profile (_blitz_profile)

pswd_changed

An indication that a password change was recommended

pswd_tmp_locked

An indication that there was a temporary lockdown

recovery_contact

The contact (email or cell phone number) specified during recovery

recovery_type

Password recovery type: email or mobile

right_name

Name of access right

roles

Administrator account roles

session_id

Unique identifier of the user session. Allows you to correlate all user events performed by the user within a common user session

subject_id

Identifier of the subject of the operation (the user who invoked the operation)

tags

Tag of assigned or revoked access right

timestamp

The date and time of the event. For example, 2022-11-04T17:49:58.384+0300

tried_old_pswd

An indication that a login attempt was made with a password from the saved password history (previous password)

used_login

Login used at sign in

user_agent

User device data (UserAgent)

wa_key_id

Security key identifier

wa_key_name

Security key name

withDelay

Entry delay was enabled

Changing system names of login and password fields#

By default, Blitz Identity Provider names the login and password fields with the identifiers login and password on the login page. When implementing the Blitz Identity Provider when migrating from an existing login system that used different field names, there may be a requirement that you need to keep the previously used field names in the Blitz Identity Provider. This may be useful because some browsers that have saved user logins and passwords and use them for auto-substitution will be able to continue to auto-substitute the saved values even when the login system switches to using Blitz Identity Provider, as long as the domain of the login page and the name of the fields on the login page are preserved.

To set the required login and password field names, the following settings must be added to the blitz.prod.local.idp.password settings block:

  • loginInputName - ID of the login input field on the login page;

  • passwordInputName - ID of the password input field on the login page.

Example of configuration:

"password" : {
    …
    "loginInputName" : "j_username",
    "passwordInputName" : "j_password",
    …
}

Configuring the use of the 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"
    }
}

Settings for auxiliary applications (pipes)#

You can configure Blitz Identity Provider to show an announcement to the user upon login. This can show the user one or two buttons, and the user’s choice can be analyzed in the login procedure.

To customize the display to the user of the ad, you need:

  • create a login procedure based on the standard one (see Displaying an announcement to the user at login);

  • in the blitz.conf configuration file add the blitz.prod.local.idp.built-in-pipes section, in which you assign the id identifier and the type announcement type to the auxiliary application with the info type. The following announcement configurations are possible:

    • news - a single button is displayed,

    • agreement - two buttons are displayed;

  • configure button and announcement texts (see Configuring auxiliary application messages (pipes)).

Example configuration of two info helper applications with identifiers alarm and user_agreement:

"built-in-pipes": {
    "info": [
        {
            "id": "alarm",
            "type": "news"
        },
        {
            "id": "user_agreement",
            "type": "agreement"
        }
    ]
}

You can configure after login Blitz Identity Provider to show the user a selection box from a list of values and store the result of the selection in an attribute in the user’s account.

To customize the display of a list of values to the user:

Configuration example of the choice helper application:

"built-in-pipes": {
    "choice": [
        {
            "id": "select_value",
            "claim": "role"
        }
    ]
}

Using several DBMSs at the same time#

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"
  ]
}

Keeping connected application settings in separate files#

By default, the settings of all connected applications are stored inside the main configuration file blitz.conf in the blitz.prod.local.idp.apps section. If a large number of applications (hundreds) are to be connected to Blitz Identity Provider, then keeping application settings in separate configuration files can be more preferable. For this, you need:

  1. In the /usr/share/identityblitz/blitz-config directory, create a root directory that will store the application settings. By default, the /usr/share/identityblitz/blitz-config/apps directory will be used.

  2. Inside the directory of application settings, create a directory for each application, observing the following rules:

    • the directory name must be created out of the application identifier (appId);

    • if the application identifier contains the / character, it must be substituted with # in the directory name;

    • if the application identifier contains the : character, it must be substituted with % in the directory name.

    Note

    For example, you need to create the https%##example.com directory for the application with the https://example.com identifier.

    Important

    Make sure to create directories for the service applications _blitz_console, _blitz_idp, _blitz_reg, _blitz_recovery, _blitz_profile.

  3. Inside each application directory, create a file with the name app.conf, containing an application configuration from the original blitz.conf. The relevant section must be called app and not the appId value, as it was in blitz.conf. Later on, inside the application directory, a hidden .snapshot directory with backups of the old application configurations will also be created after each setting modification through the console or API.

    The example of the app.conf configuration file:

    ##########################################################################################
# version: 822
# modified: 2023-08-20 21:17:27 MSK
# author: admin
# ip: 127.0.0.1
# user agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 …
##########################################################################################
{
    "app": {
        "domain": "https://identityblitz.ru",
        "name": "Тестовое приложение",
        "oauth": {
            …
        },
        …
    }
}

  4. After migrating all existing application settings from blitz.conf to separate configuration files, set the application setting reading mode in the blitz.prod.local.idp.apps-source section of blitz.conf:

    "apps-source": {
    "type": "filesystem",
    "dir": "apps"
 }

  5. Restart the Blitz Identity Provider applications and try to sign in to the applications. If everything is alright, you can remove the application settings from the original blitz.prod.local.idp.apps section.

Interface text settings#

Multilanguage support#

The Blitz Identity Provider web interface supports multi-language. Two languages are provided by default - Russian and English.

By default, the interface is displayed to the user in the language that corresponds to their system language in the OS and their preferred language in the browser. In this case, you can switch the language by changing the primary input language (the language in which web pages are displayed) in the browser you are using. For example, to change the language in the Chrome browser, follow the steps:

  • go to the browser settings (chrome://settings/);

  • select “Show additional settings”;

  • click on the “Change language preferences” button;

  • move the desired language to the first place in the list.

To change the language in Firefox browser, you need to follow the steps:

  • go to the browser settings (about:preferences);

  • select the “General” section of the settings;

  • in the “Language” subsection, press the “Select” button;

  • move the desired language to the first position in the list:

Additionally, it is possible to configure the language using the blitz.conf configuration file. To do this, edit the language setting section blitz.prod.local.idp.lang with the following parameters:

  • languages - list of available languages. The first language in the list is considered to be the default language;

  • portal-lang-cookie - name (name) and setting domain (domain) of the cookie with the current portal language (optional). If a portal cookie is set, the language change in Blitz Identity Provider is stored in the specified cookie;

  • ignore-browser - whether or not the browser language ignore mode is turned off;

  • lang-variants – list of identifiers for special sets of strings for individual applications (see Modifying messages for different applications).

The example of configuration file excerpt:

"lang" : {
  "ignore-browser" : true,
  "languages" : [
    "ru",
    "en"
  ],
  "lang-variants": ["special1", "special2"],
  "portal-lang-cookie" : {
    "domain" : "domain.com",
    "name" : "blitzlng"
  }
}

Thus, for example, if the use of the English interface language is not required, it can be removed from the languages parameter.

Modifying the text messages of the web interface#

Blitz Identity Provider allows you to change text strings used in the system interface. To do this, you need to edit the messages file located in the /custom_messages/ directory by adding a string like “parameter=value”, where parameter is the text string identifier and value is the required text.

All text strings used by Blitz Identity Provider by default are saved in the messages.zip archive included with the software.

For example, the following string is responsible for the text in the registration form that contains URL to the User agreement:

reg.page.reg.action.agreement=Нажимая на&nbsp;кнопку &laquo;Зарегистрироваться&raquo; вы&nbsp;соглашаетесь с&nbsp;<a href="{0}" target="_blank">условиями использования</a>

The file must be saved in UTF-8 encoding in order to display correctly.

If you need to change the English language, add the messages.en file to the specified directory and change the necessary files in it.

If you want to use the @ character in texts, you must enter it twice.

Modifying message templates and SMS messages#

Email templates are text strings saved in the same way as regular strings in the web interface. They are modified in the same way.

The unified format of message codes is used, which has the following form:

message.$[группа_сообщений].$[тип_сообщения].$[вариация].$[канал].$[часть]

Following message groups are used:

  • notif - for notifications;

  • auth - for interaction with the user during authentication;

  • reg - for interaction with the user during registration;

  • recovery - for interaction with the user when restoring access;

  • profile - for interaction with the user in the User profile;

  • api - for interaction with the user when using API.

Variations allow you to specify variations in addition to the basic message template (for example, a separate template by application). The presence of a variation is checked by the basic template with the message text (body'' part). If the variation of the main template is described in the system, all other templates (``email.subject, email.from, push.title) will be applied with the same variation. If there are multiple variations, they will be checked in some specified order (usually from more detail to less detail). If there are no variations, the base template will be used. In most cases there are no variations.

The following channels are available:

  • sms - sending messages by SMS. There are no parts for this channel;

  • email - sending messages by email. Parts for this channel:

    • subject - subject;

    • body - main content;

    • from - sender (optional);

  • push - sending push notifications. Parts for this channel:

    • title - subject;

    • body - main content.

Example keys for login_unknown_device messages type:

  • message.notif.login_unknown_device.email.subject - subject of the email message;

  • message.notif.login_unknown_device.email.body - text of the email message;

  • message.notif.login_unknown_device.email.from - sender of the email message;

  • message.notif.login_unknown_device.sms - SMS text.

The table below summarizes the descriptions of the message types from the different groups.

Message types from “notification” (notif) group

Message type

Description

Parameters

login_unknown_device

User notification about the login from unknown device

  • device - code of the device

  • device.msg - name of the device computed with msg(audit.device.$[device]) string

  • browser - user browser

  • user session attributes

  • ua.name - device name

  • app.id - application identifier

  • app.name - application name

  • ip – IP-address

  • ip.country - country

  • ip.state - region

  • ip.city - city

  • ip.lat - latitude

  • ip.lng - longitude

  • ip.radius - radius of the neighborhood

  • device.type - device type

  • device.mkey - collected key for messages, formation rule: s"$deviceType.$osName.$osVer"

  • os.name - operating system name

  • os.ver - operating system version

  • os.mkey - collected key for messages, formation rule: s”$osName.$osVer”

  • event.time is the time of the event (in unixtime).

You can use the following formatting features in a message template:

  • $[<ATTR>&dic(<MSG_KEY_PREFIX>,<PARAM_SUBSTITUTION>)] - get value from string;

  • $[<ATTR>&formatUnixTime(dd MMMM YYYYY year,ru,GMT)] - date and time formatting, where dd MMMM YYYYY - template in SimpleDateFormat format, ru - locale (optional), GMT - timezone (optional)

link_social_network

User notification about linking to social network

  • f p.humanReadableName - name of the external identity provider

  • user attributes

change_pwd

User notification about password change

user attributes

changed_pwd_to_object

User notification about password change in dependent account

attributes of the dependent account with obj. prefix

access_recovery

User notification about password recovery

user attributes

access _recovery_by_object

User notification about password recovery in dependent account

attributes of the dependent account with obj. prefix

set_2factor_auth

User notification of the assignment of the second authentication factor

  • method - authentication method code

  • method.msg - authentication method name computed by the msg(message.method .name.$[method]) string

  • user attributes

granted_access_to

Subject notification about granted access to the object

  • blitz_right - access rights code

  • subject attributes

  • object attributes with the obj. prefix

granted_access_on

Object notification about granted access to it

  • blitz_right - access rights code

  • object attributes

  • subject attributes with the obj. prefix

revoked_access_to

Subject notification about revoked access to the object

  • blitz_right - access rights code

  • subject attributes

  • object attributes with the obj. prefix

revoked_access_on

Object notification about revoked access to it

  • blitz_right - access rights code

  • object attributes

  • subject attributes with the obj. prefix

on_registration

User notification about registration of his/her account

  • _entryPoint_ - registration channel

  • _appId_ – application

  • _requesterId_ – application

  • user attributes

Example line:

message.notif.login_unknown_device.email.body=Уважаемый пользователь!<br><br>Мы обнаружили, что вы вошли в систему с нового устройства $[event.time&formatUnixTime(dd MMMM YYYY г.,ru,GMT)]:<br>$[device.mkey&dic(dics.devices,os.ver)], браузер $[ua.name&dic(dics.browsers)]<br>Если вы не совершали это действие, обратитесь к администратору.

Message types from the “registration” (reg) group

Message type

Description

Parameters

vrf_code

Sending contact confirmation code during registration

  • code – confirmation code

  • link– confirmation link (only for email channel)

  • req.ip – IP-address

  • req.userAgent - userAgent of the user

  • cfg.domain - domain

  • user attributes from the registration context with the prefix attrs.

set_pwd_link

Sending the link to change password during registration (only for email channel)

  • link - link to password change page

  • req.ip – IP-address

  • req.userAgent - userAgent of the user

  • cfg.domain - domain

  • user attributes from the registration context with the prefix attrs.

generated_pwd

Sending the assigned registration password (only for SMS channel)

  • pwd - generated password

  • req.ip – IP-address

  • req.userAgent - userAgent of the user

  • cfg.domain - domain attributes of the user from the registration context with the prefix attrs.

Message types from the “recovery” group

Message type

Description

Parameters

vrf_code

Sending contact confirmation code during recovery

  • code – confirmation code

  • link - confirmation link (for email only)

Message types from the “authentication” (auth) group

Message type

Description

Parameters

vrf_code

Sending mobile number confirmation code (channels: SMS/push)

code – confirmation code

Message types from the “User profile” (profile) group

Message type

Description

Parameters

vrf_code

Sending confirmation code if it was changed in User profile

  • attr.msg - name of the attribute in the profile form

  • attr – attribute code

  • link– confirmation link (only for email channel)

  • code – confirmation code

Message types from the “program interface” (api) group

Message type

Variations

Description

Parameters

vrf_code

  • $attr.$rpId – separately for current application and attribute

  • $attr - separately for this attribute

Sending contact confirmation code via API

  • code – confirmation code

  • link– confirmation link (only for email channel)

  • attr.value - new contact (e-mail or cell phone)

  • attr – contact attribute code

Modifying device and browser names#

In Blitz Identity Provider you can customize the names of devices (operating systems) and browsers with exact version. To do this, you need to create lines in the custom_messages directory in the messages file whose names correspond to the following patterns:

  • for browsers - dics.browsers.<name>. The following browsers are supported for substitution into <name>: Firefox, Opera, Chrome, Safari, IE, Edge, Yandex, Sputnik, unknown. The text of the string receives the browser version as a substitution string {0}.

  • for devices (operating systems) - dics.devices.<typ>.<os>.<ver>. As <typ> you can specify: kindle, mobile, tablet, iphone, windowsPhone, pc, ipad, playStation, unknown. As <os> you can specify: Android, iOS, WindowsPhone, Windows, macOS, Linux, ChromeOS, unknown. If no private string is defined for <os> and <ver>, the more general string is taken. The operating system version is passed into the string text as a {0} substitution string.

Example lines:

dics.browsers.Firefox=Firefox Browser {0}
dics.browsers.Opera=Opera {0}
dics.browsers.Chrome=Google Chrome {0}
dics.browsers.Safari=Safari {0}
dics.browsers.IE=Internet Explorer
dics.browsers.Edge=Microsoft Edge {0}
dics.browsers.Yandex=Яндекс.Браузер {0}
dics.browsers.Sputnik=Спутник
dics.devices.mobile=Мобильное устройство
dics.devices.mobile.Android=Android
dics.devices.mobile.Android.10=Android 10
dics.devices.mobile.Android.9=Android 9
dics.devices.tablet=Планшет
dics.devices.iphone=iPhone
dics.devices.iphone.iOS.14=iPhone (iOS {0})
dics.devices.pc.macOS=macOS {0}
dics.devices.pc.macOS.13=macOS Ventura {0}
dics.devices.pc.macOS.12=macOS Monterey {0}
dics.devices.pc.macOS.11=macOS Big Sur {0}
dics.devices.pc.macOS.10.15=macOS Catalina {0}
dics.devices.pc.macOS.10.14=macOS Mojave {0}
dics.devices.pc.macOS.10.13=macOS High Sierra {0}
dics.devices.pc.macOS.10.12=macOS Sierra {0}
dics.devices.pc.Windows.8=Windows 8
dics.devices.pc.Windows.10=Windows 10
dics.devices.pc.Windows.11=Windows 11

Modifying messages for different applications#

It is possible to modify all text messages and templates in order to use specific texts/templates for different applications. For example, you can brand emails sent during registration on different websites connected to the same Blitz Identity Provider installation, or provide a link to download different resource rules.

To bind a set of templates to a specific application, follow the steps:

  1. Create a text file copy that should be used only for this application. To do this, create a text file messages.ru-special1 (messages.en-special1) in the custom_messages/ directory for this application, in which special1 is a sequence of 5-8 characters (both numbers and letters of the Latin alphabet are allowed).

  2. Edit the messages.ru-special1 (messages.en-special1) file to add application-specific strings (see Modifying the text messages of the web interface). All other strings will be taken from the default string database.

  3. Edit the blitz.conf file as follows:

    • in the blitz.prod.local.idp.apps section of the file, find the application ID that should use the created template file;

    • add a parameter to the application settings in the ”lang-variant” : “special1” format, in which special1 is the character sequence used to label the template.

    Example:

    "demo-application" : {
    "domain" : "http://testdomain.ru",
    "lang-variant" : "special1",
    "name" : "test",
    "oauth" : {
        "autoConsent" : false,
        "clientSecret" : "1234567890",
        "defaultScopes" : [],
        "enabled" : true,
        "redirectUriPrefixes" : [
            "http://localhost"
        ]
    },
    "theme" : "default"
}

  4. In the blitz.prod.local.idp.lang -> lang-variant setting, register all character sequences used to label various applications (special1, special2).

After that, a specially created message file will be used when logging into this application.

Configuring auxiliary application messages (pipes)#

In Blitz Identity Provider, you can configure the messages of the helper application that issues the security key (Passkey, WebAuthn, FIDO2) at user login. You can configure different message texts depending on the user’s devices (operating systems). To do this, create strings in the custom_messages directory in the messages file whose names correspond to the following patterns:

  • pipes.conf.webAuthn.addKey.<message-path>.<device-type>.<os>;

  • login.outside.flow.error.internal.webAuthn.addKey.<device-type>.<os>.

As <message-path> the string name is specified (see example below). The <device-type> specifies the device type: mobile, tablet, iphone, pc, ipad. As <os> you can specify: Android, iOS, Windows, macOS, Linux, ChromeOS. If no private string is defined for <device-type> and <os>, the more general string is taken.

Example lines:

pipes.conf.webAuthn.addKey.page.title.pc.macOS=Вход по Touch ID
pipes.conf.webAuthn.addKey.head.title.pc.macOS=Вход по Touch ID
pipes.conf.webAuthn.addKey.info.pc.macOS=Использовать Touch ID или пароль компьютера Mac для входа в приложения?
pipes.conf.webAuthn.addKey.finishInfo.pc.macOS=Вход по Touch ID для учетной записи настроен. Нажмите кнопку "Продолжить"
pipes.conf.webAuthn.addKey.name.pc.macOS=Touch ID на Mac
login.outside.flow.error.internal.webAuthn.addKey.pc.macOS=Произошла ошибка при настройке входа по Touch ID на Mac

pipes.conf.webAuthn.addKey.page.title.pc.Windows=Вход через Windows Hello
pipes.conf.webAuthn.addKey.head.title.pc.Windows=Вход через Windows Hello
pipes.conf.webAuthn.addKey.info.pc.Windows=Использовать PIN-код компьютера, распознавание лица или отпечатка пальца для входа в приложения?
pipes.conf.webAuthn.addKey.finishInfo.pc.Windows=Вход через Windows Hello для учетной записи настроен. Нажмите кнопку "Продолжить"
pipes.conf.webAuthn.addKey.name.pc.Windows=Windows Hello
login.outside.flow.error.internal.webAuthn.addKey.pc.Windows=Произошла ошибка при настройке входа через Windows Hello

pipes.conf.webAuthn.addKey.page.title.iphone.iOS=Вход по Face ID
pipes.conf.webAuthn.addKey.head.title.iphone.iOS=Вход по Face ID
pipes.conf.webAuthn.addKey.info.iphone.iOS=Использовать Face ID или Touch ID телефона для входа в приложения?
pipes.conf.webAuthn.addKey.finishInfo.iphone.iOS=Вход через Face ID для учетной записи настроен. Нажмите кнопку "Продолжить"
pipes.conf.webAuthn.addKey.name.iphone.iOS=Face ID на iPhone
login.outside.flow.error.internal.webAuthn.addKey.iphone.iOS=Произошла ошибка при настройке входа через Face ID

pipes.conf.webAuthn.addKey.page.title.ipad.iOS=Вход по Touch ID
pipes.conf.webAuthn.addKey.head.title.ipad.iOS=Вход по Touch ID
pipes.conf.webAuthn.addKey.info.ipad.iOS=Использовать Touch ID планшета для входа в приложения?
pipes.conf.webAuthn.addKey.finishInfo.ipad.iOS=Вход через Touch ID для учетной записи настроен. Нажмите кнопку "Продолжить"
pipes.conf.webAuthn.addKey.name.ipad.iOS=Touch ID на iPad
login.outside.flow.error.internal.webAuthn.addKey.ipad.iOS=Произошла ошибка при настройке входа через Touch ID

pipes.conf.webAuthn.addKey.page.title.mobile.Android=Вход по распознаванию лица или отпечатка пальца
pipes.conf.webAuthn.addKey.head.title.mobile.Android=Вход по распознаванию лица или отпечатка пальца
pipes.conf.webAuthn.addKey.info.mobile.Android=Использовать распознавание лица или отпечатка пальца для входа в приложения?
pipes.conf.webAuthn.addKey.finishInfo.mobile.Android=Вход через распознавание лица или отпечатка пальца для учетной записи настроен. Нажмите кнопку "Продолжить"
pipes.conf.webAuthn.addKey.name.mobile.Android=Smart Lock на Android
login.outside.flow.error.internal.webAuthn.addKey.mobile.Android=Произошла ошибка при настройке входа через через распознавание лица или отпечатка пальца

pipes.conf.webAuthn.addKey.page.title=Вход по ключу безопасности
pipes.conf.webAuthn.addKey.head.title=Вход по ключу безопасности
pipes.conf.webAuthn.addKey.info=Использовать ключ безопасности FIDO2 для входа в приложения?
pipes.conf.webAuthn.addKey.finishInfo=Вход через ключ безопасности для учетной записи настроен. Нажмите кнопку "Продолжить"
pipes.conf.webAuthn.addKey.name=FIDO2

In Blitz Identity Provider, you can configure texts for an auxiliary application that shows a message to the user while login to the application. To do this, define in the custom_messages directory in the messages file the strings for the customized blitz.prod.local.idp.built-in-pipes.info applications with their {id} of the helper application.

Example lines:

pipes.info.head.title.{id} - название вкладки
pipes.info.page.title.{id} - заголовок вспомогательного приложения
pipes.info.message.{id} - текст сообщения
pipes.info.read.{id} - название кнопки (для вспомогательных приложений с типом "news")
pipes.info.agree.{id} - название 1-й кнопки (для вспомогательных приложений с типом "agreement")
pipes.info.disagree.{id} - название 2-й кнопки (для вспомогательных приложений с типом "agreement")

You can customize texts in the Blitz Identity Provider for a helper application that asks the user to select a value from a list at user’s login and stores the result of the selection in an account attribute. To do this, define in the custom_messages directory in the messages file the strings for the configured blitz.prod.local.idp.built-in-pipes.choice applications with their {id} of the helper application.

Example lines:

pipes.choice.head.title.{id} - название вкладки
pipes.choice.page.title.{id} - заголовок вспомогательного приложения
pipes.choice.info.{id} - текст информации под заголовком
pipes.choice.button.{id}.{choiceId} – текст на кнопке выбора
pipes.choice.skip – текст на кнопке пропуска

You can customize texts in Blitz Identity Provider for an auxiliary application that asks the user to enter an attribute value at application login. To do this, define lines in the custom_messages directory in the messages file that correspond to the following pattern - pipes.act.attr. <message-path>.common.<attr-name>. The string name is specified as <message-path> (see below for an example). The attribute name is specified as <attr-name>.

Example strings (in case the family_name attribute is filled):

pipes.act.attr.page.title.common.family_name=Подтверждение фамилии
pipes.act.attr.head.title.common.family_name=Подтверждение фамилии
pipes.act.attr.info.confirm.common.family_name=В учетной записи указана ваша фамилия?<br>Проверьте и нажмите кнопку <b>Подтвердить</b>.
pipes.act.attr.info.enter.common.family_name=В учетной записи не указана фамилия.<br>Введите и нажмите кнопку <b>Подтвердить</b>.
pipes.act.attr.label.common.family_name=Фамилия
pipes.act.attr.msg.required.msg.common.surname=Введите фамилию

Admin console configuration files#

The admin console is configured using the console.conf and credentials files. The following subsections describe the possible settings.

Configuring Admin console login via SSO#

You can configure the Blitz Identity Provider admin console to log in via the OIDC Identity Provider. The provider can be the current installation of Blitz Identity Provider, a custom installation of Blitz Identity Provider, or even an external software if it is compatible with OIDC.

The following admin console login modes are supported:

  • standard mode by the account login/password configured in “Administrators” section (see Restarting Blitz Identity Provider applications);

  • login via SSO;

  • the hybrid mode of logging in when the administrator can log in both by the login/password in the standard mode and using SSO.

With SSO mode, admin profiles must still be created under “Administrators” and roles must be assigned. The password setting for the administrator account is optional with SSO, as long as the user will only use SSO to log in.

To configure the admin console login mode via SSO, you must:

  • Register the application in the external identity provider (SSO) settings. The allowed return prefixes (redirect_uri) must include the Blitz Identity Provider installation domain. Get the client_id and client_secret of the application for the admin console after registration;

  • in the console.conf configuration file, create a login settings block with the following content:

{
  "login" : {
    "fp" : {
      "authUri" : "https://idp-host.com/blitz/oauth/ae",
      "clientId" : "blitz-console",
      "clientSecret" : "client_secret_value",
      "logoutUrl" : "https://idp host.com/blitz/login/logout?post_logout_redirect_uri=https://idp host.com/blitz/console",
      "scopes" : [
        "openid"
      ],
      "subjectClaim" : "sub",
      "roleClaim" : "roles",
      "tokenUri" : "https://idp-host.com/blitz/oauth/te"
      },
    "mode" : "sso"
  }
}

You must specify parameters:

  • In the authUri``and ``tokenUri parameters, you must specify the addresses of the Authorization Endpoint and Token Endpoint handlers of the external identity provider.

  • In the clientId and clientSecret parameters, specify the client_id and client_secret values, assigned to the application registered in the external identity provider application that corresponds to the admin console parameters.

  • In the logoutUrl parameter, specify the link to which the user should be redirected user when logging out of the admin console, so that a single logout via an external identity provider.

  • In the scopes parameter, prescribe the list of scopes which must be requested (at least openid scopes are needed).

  • In subjectClaim specify the name of the attribute from the identity token (id_token) that is used as the account identifier. Using this identifier the administrator’s login will be performed in sso login mode.

  • Specify in roleClaim the attribute name from the identification token (id_token), in which the role (string) or the role list (array of strings) of the administrator is passed. Using these identifiers the administrator’s login will be performed in sso login mode.

  • In the mode parameter, you must specify the required login page mode: sso - login only using an external identity provider (see the figure below); internal - login only using the login and password from the administration console settings. If the parameter is not specified, both options are available at the user’s choice. It is not required to create administrator accounts in the “Administrators” menu prior to logging in via SSO “Logging in via SSO”.

image126_en

Admin console login window when SSO mode is enabled

image127_en

Admin console login window with all login modes enabled

To avoid showing an intermediate login screen where the user clicks the “Logging in via SSO” button, you can invoke the admin console using a link of the following form: https://hostname:port/blitz/console?mode=SSO.

Session limit#

Security policy may require that a user or administrator cannot be logged in from multiple devices at the same time. To fulfill this security policy for administrator access to the admin console, the session block must be added to the console.conf configuration file:

"session" : {
  "mode" : "exclusive",
  "check-interval" : 10
}

With this setting, if an administrator login is detected with an account that has already logged in, the previous login will display the login page in the admin console for any action. The check-interval setting (specified in seconds) specifies the period of time in seconds how quickly the previous session will be logged out when a new session appears.

If the security policy also requires to prevent multiple sessions for normal users, this mode can be selectively enabled for certain users when logging in to certain applications. This can be done by configuring the login procedure (see Configuring application authentication flows).

Additionally, in the web application “User profile” it is necessary to enable the setting according to which an early exit from the web application will take place in case the user profile is blocked or the policy prohibiting multiple user logins has been violated. In the blitz.conf configuration file, in the blitz.prod.local.idp.user-profile settings block, add the check-session-interval setting, which specifies the period of session activity check by the web application:

"user-profile" : {
  "check-session-interval" : 10,
  …
}

Configuring the roles and access rights to the admin console#

The standard administrator roles are described in the previous sections (see Administrator account management). In the credentials configuration file you can create additional administrator roles or correct access rights in existing roles. To do this, in the roles block, adjust the composition of access rights (privileges) corresponding to the role (name).

Example of configuration:

"roles" : [
  {
    "name" : "new-role",
    "privileges" : ["w_app","w_system","w_ui","w_user","w_admin","r_audit"]
  }
]

If new roles are created, text strings with role names must also be defined for them (see Interface text settings). Example of a text string for a new role new_role:

page.admins.role.new-role=имя новой роли

The list of available access rights for filling the privileges setting is given in the table below.

Blitz Identity Provider admin console access rights

Access rights

Available sections of the Admin console

w_app

“Applications”

w_system

“Data sources”, “Authentification”, “Authentification flows”, “Social login providers”, “SAML”, “OAuth 2.0”, “Devices”, “Messages”

w_ui

“Self services”, “Login page themes”

w_admin

“Administrators”, “Events”

w_user

“User search”, “Group search”, “Access rights”

r_user

“User search” (view only), “Group search” (view only), “Access rights” (view only)

r_audit

“Events” (view only)