Updating Blitz Identity Provider#

Important

If the update is installed skipping intermediate versions, you should install the latest version of blitz.bin, and the rest of the settings should be made according to all releases skipped during the update.

Attention

In the case of PostgreSQL DBMS, you should also check the current resources.zip file to see what new DDL scripts have appeared in it, and execute them if such changes do not exist in the current database scheme.

Update from 5.20.0 to 5.21.0#

If the PostgreSQL database is used, apply the script: 021-5.21.0.sql.
Install blitz-5.21.0.bin.
If necessary, use a new feature: configure access to network services over the RADIUS protocol.

Update from 5.18.0 to 5.20.0#

If the PostgreSQL database is used, apply the script: 020-5.20.0.sql.
Install blitz-5.20.0.bin.
If necessary, customize new authentication methods:
- login confirmation by incoming call (Flash Call);
- automatic user identification by session properties.
If necessary, use new customization features using Java programming:
- request for the user to enter a security question (ready procedure);
- getting the user’s geodata;
- customization of the operation logic regarding data storages.

Update from 5.16.2 to 5.18.0#

In case of using PostgreSQL database, apply scripts:
1. 018-5.17.0.sql
2. 019-5.18.0.sql

In the blitz.conf configuration file, find the blitz.prod.local.idp.provisioning.recovery settings block. Apply the following changes:

Rename the security-question setting into system-security-questions.
Create the factor2 block. Copy and paste the methods section with its entire content into it. Remove the original methods section.
In the factor2 block, set "mode" : "by_user_required_factor".

Example of the block after editing#

"recovery" : {
    "dropInactivityLock" : true,
    "factor2" : {
        "methods" : [
            "email",
            "sms",
            "totp"
        ],
        "mode" : "by_user_required_factor"
    },
    "recovery-contacts" : [
        "phone_number",
        "email"
    ],
    "search-attrs" : [
        "email",
        "phone_number"
    ],
    "system-security-questions" : {
        "attrs" : [
            "family_name"
        ]
    }
}

Install blitz-5.18.0.bin.

Update from 5.15.x to 5.16.x#

In the nginx settings, block access to the /blitz/metrics addresses from external networks:
```
location /blitz/metrics {
    return 404;
}
```

If you use special bundle for applications via lang-variant (lang-variant optional field in the application settings), you need to register all language options in the blitz. conf -> lang-variant -> lang.

Example:

"lang": {
    "ignore-browser": false,
    "lang-variants": ["12345", "12346"], // this field
    "languages": ["ru","en"],
    "portal-lang-cookie": {
        "domain": ".identityblitz.ru",
        "name": "portal_lang"
    }
}

Install new blitz.bin.
If necessary, configure gathering performance metrics in Prometheus via direct access to /blitz/metrics at internal addresses of application servers.
If necessary, configure the storage of application settings in separate files.

Update from 5.14.0 to 5.15.x#

In case of using PostgreSQL database, apply scripts:
1. 017-5.15.0.sql
Install new blitz.bin.

Update from 5.11.x to 5.14.0#

In case of using PostgreSQL database, apply scripts:
1. 015-5.12.0.sql,
2. 016-5.13.0.sql
Install new blitz.bin.
In the “Appearance” section, check that a unique name is set for all templates in the “Template name” field. If there are several templates with the same name, rename them.
For each configured external identity provider in the new block “User selection” fill in the values of the settings “User’s name” and “User ID”. Filling example:
- The username is ${given_name-} ${family_name-}
- The user ID is ${email&maskInMiddle(4,8)}
Configuration is used during the user bind process when the user first logs in through the external identity provider. Based on the customization, the user is shown a card of Blitz Identity Provider account found for binding that matches the external Identity Provider account.
Verify login functions through external identity providers, if the appearance of the login binding screens is compromised, then adjust the appearance themes used.
Adjust the settings in the console.conf configuration file:
1. If login/password login to the admin console is used, add the roleClaim setting to console.conf with an empty value:
Example:
```
{
"login" : {
    "fp" : {

    ...
    "subjectClaim" : "sub",
    "roleClaim" : "",
    ...
    },
    "mode" : "credentials"
}
}
```
1. If the SSO login function to the admin console is used, add the roleClaim setting to the login.fp block in console.conf. As a value, specify the name of the attribute from id_token in which the administrator role is passed (common role names: root, security, ysadmin, app_admin, ui_admin, support, are taken from the credentials settings file from roles.name). Configure the external IDP to pass an attribute with a role. The attribute can be text (String) - then one role is passed, or an array of strings (ArrayOfString), then multiple roles can be passed.
Example:
```
{
"login" : {
    "fp" : {

    ...
    "subjectClaim" : "sub",
    "roleClaim" : "SOME_CLAIM_NAME",
    ...
    },
    "mode" : "sso"
}
}
```
From the “Administrators” menu of the console, you can remove those admin users who log in only through the external SSO logon.

Update from 5.10.0 to 5.11.x#

If using PostgreSQL database, apply the 000-service-tasks.sql, 013-tasks.sql, 014-sec_ch_ua.sql scripts.
Check for non-standard lines in custom_messages. If the $[device.mkey&dic(dics.devices)] function is used in the lines with the texts of letters, replace it with $[device.mkey&dic(dics.devices,os.ver)].
Install new blitz.bin.
In the play.conf file, adjust the memcached connection settings - add operationTimeout, timeoutExceptionthreshold, maxReconnectDelay:
- operationTimeout - time to wait for memcached request execution in ms;
- timeoutExceptionThreshold - the number of attempts to execute the request, after which the node is considered unavailable;
- maxReconectDelay - the interval between attempts to establish a connection to the node in seconds.
Example configuration file with added settings with recommended values:
```
"memcached" : {
"operationTimeout" : 1000,
"timeoutExceptionThreshold" : 1,
"maxReconnectDelay" : 10,
"servers" : [
    …
]
}
```
In case of using PostgreSQL DBMS, if necessary, switch task processing from RabbitMQ broker to jdbc broker ( if RabbitMQ is not used for anything else and you want to abandon its further use). It is recommended to use the jdbc broker only in environments with low load.

To configure the use of the jdbc broker is required:
- Check that the stores settings block in the blitz.conf file has the default-type setting set to jdbc:
```
"stores" : {
"default-type" : "jdbc"
},
```
- In the blitz.conf file in the tasks block, adjust the broker settings as follows:
```
"tasks" : {
"broker-type" : "task-store",
"executionRules" : [
    {
    "maxAttempts" : 2,
    "queue" : "blitz-tasks",
    "redeliveryDelayInSec" : 60
    }
],
"queues" : [
    {
    "dequeueBatchSize" : 10,
    "dequeuePeriodInSec" : 30,
    "executorPoolSize" : 5,
    "name" : "blitz-tasks"
    }
]
}
```
- To the server running task processing, add the startup parameter akka.coordinated-shutdown.phases.service-stop.timeout to a value of 30s:
```
Dakka.coordinated-shutdown.phases.service-stop.timeout=30s
```

Update from 5.9.0 to 5.10.0#

If the PostgreSQL database is used, apply the 012-geo_to_audit.sql script.
Install new blitz.bin.
If account storage selection rules or current login procedure algorithms check a dynamic client_id and parses it using the “:” delimiter, then the parsing algorithms used must be augmented to accommodate for new dynamic client_ids using the “~” character as a delimiter.
If necessary, add access control rules in the “Access control” block of the application.
If necessary, enable use in Blitz Identity Provider of a geodata directory in mmdb format (the directory is purchased by the Customer himself).
If necessary, enable transmission of security events to the Kafka queue server.

Update from 5.8.0 to 5.9.0#

If you plan to continue working with Couchbase Server DBMS version 6.0, you must add the -Dcouchbase.durability.mode=clientVerified system variable to JAVA_OPTS in the etc/default/blitz-* file.

In the future, if an update to Couchbase Server version 6.5 or 7.0 is performed, you should remove the variable or change it to one of the possible values:
- disabled – Blitz Identity Provider receives a response from Couchbase after writing to memory on the primary node;
- majority – Blitz Identity Provider receives a response from Couchbase after writing to memory on the primary node and on most replicas;
- majorityAndPersistActive – Blitz Identity Provider receives a response from Couchbase after writing to disk on the primary node and to memory on most replicas;
- persistToMajority – Blitz Identity Provider receives a response from Couchbase response after writing to disk on the primary node and on most replicas.
If there is no setting (default operation), majority mode is used.

The variable affects waiting for data to be written to node memory and to disk, consequently affecting performance.

The optimal value should be identified through load testing and taking into account the storage reliability requirements.
Changing the settings for working with storages:
- in the play.conf file, delete the modules block
- in the blitz.conf file, add a block to the main block (next to internal-store):
```
"stores" : {
    "default-type": "cb"
},
```
In this case, CouchBase Server will be used as the storage for all objects.

default-type can take values:
- cb is used for CouchBase
- jdbc - used for PostgreSQL
If you need to separate objects into different storages, you should add a block stores to the stores block:
```
```
"list-of-types" : {
    "<название внутреннего хранилища>" : "<тип хранилища>"
},
```
```
The following values can be the internal storage:
- user-store
- access-token-store
- refresh-token-store
- id-ext-store
- device-code-store
- access-list-store
- blitz-action-store
- oath-token-store
- oath-load-proc-store
- confirmation-request-store
- reg-context-store
- reg-context-storef
- id-store-maker
- rcv-ctx-store
- db-client-store
- db-client-storef
- initial-token-store
- user-agent-store
- web-authn-key-store
- audit-store
Changing the settings for working with tasks

In blitz.conf in the tasks block, you need to add a parameter:
```
"broker-type": "<TYPE>"
```
Specify one of the following as the value of <TYPE>:
- cb - queue processing in CouchBase
- rmq - queue processing in RabbitMQ
If the broker-type parameter is not available, CouchBase is used by default. When using PostgreSQL as the main DBMS, only queue processing in RabbitMQ is available.
If necessary, configure audit logging of incomplete login attempts (when the user has entered the correct login and password, but failed to confirm the login).

Add parameters for this in the blitz.conf file in the login block:
```
"postponeEnabled" : true,
"postponeTtl" : 3600 // время в секундах, по умолчанию 10800
```
The postponeTtl parameter specifies the time to wait for the login to complete. After this time expires, a pending login attempt event may be logged if the login has not yet been completed.

In case RabbitMQ is used to process tasks, then it is necessary to make an additional queue for the main task queue with the name <general queue name>-postpone 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.

Set the security event logging configuration. Add a block in the blitz.conf file:

"audit": {
    "emitters": [
        "audit-store",
        "log"
    ]
},

The emitters block specifies:

audit-store - the data will be sent to the database, according to the settings from the stores block
log - data will be sent to a file, according to the settings in logback.xml

Only one emitter can be left if necessary.

Warning

Without the audit block, the audit data will not be saved and displayed!

Example of a block in logback.xml to configure sending audits to a 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>

Prepare a set of new login procedures for Release 5.9.0:
- If standard login procedures are used, take the updated login procedures from the “Examples of authentification flows” section Ready-made login procedures. Make edits to them if edits have been made to the previously used standard login procedures.
- If non-standard entry procedures are used, contact REAK SOFT technical support to correct the procedures or perform the correction yourself. Necessary changes in the input procedure:
If the login procedure used a view call
```
userReqFactor = ctx.userProps("requiredFactor")
```
or other invocation of ctx.userProps("requiredFactor") to determine the authentication level required for the user, you must adjust the call to the following:
```
Integer userReqFactor = 0;
if (ctx.user() != null) {
    userReqFactor = ctx.user().requiredFactor();
}
```
In the admin console, deactivate all login procedures that require modification (see previous point).
If the PostgreSQL database is used, apply the 010-add_usr_prp.sql, 011-pp_audit.sql scripts.
Install new blitz.bin.
Update and activate the login procedures in the console to the corrected ones for release 5.9.0.
If necessary, set up login via Tinkoff ID through the admin console.
If necessary, adapt new standard login procedures for the functions “Customize Face ID / Touch ID login”, “Announcement screen at login”, “Request for consent at login”, “Request for attribute input at login”.

Update from 5.7.0 to 5.8.0#

Install new blitz.bin.
If necessary, in the Blitz Identity Provider admin console, in the “Security key confirmation” authentication method settings in the “First factor” block, you can enable the setting “Equate the use of this method to the use of the first and second factor. If enabled, the login with a security key will mean that the user passed two-factor authentication”.

Update from 5.6.7 to 5.7.0#

Install new blitz.bin.
If necessary, configure the use of external validators and attribute translators (see External attribute validator and Attribute translator).
If the PostgreSQL database is used, apply the 009-fix_pp_column script.

Update from 5.4.0 to 5.6.7#

Install new blitz.bin.

Migrate the settings for the allowable logout return prefixes:

If the applications are not many, in the admin console, in each application’s settings, enter the allowed logout return URL prefixes in the OAuth 2.0 block of the application card (the setting has been moved from the main application settings to the OAuth 2.0 protocol block of the application). See. OAuth 2.0 and OpenID Connect 1.0.
- edit the settings of the _blitz_profile application (in the console you can go to /console/app?id=_blitz_profile):
- configure the OAuth protocol (if not already configured) by specifying client_secret (any, will not be used) and a return link prefix (you can specify the address where the /blitz/profile application is accessible).

If there are a lot of applications (several dozen), then use a script to automate settings updates:

will require python3 with the pyhocon module installed.

create a file conf-migr.py and insert the logout settings migration script into it:

# -*- coding: utf-8 -*-

import json

from pyhocon import ConfigFactory

file_path = 'blitz.conf'

conf = ConfigFactory.parse_file(file_path)

apps = conf["blitz"]["prod"]["local"]["idp"]["apps"]

for app in apps:

    if "logout" in apps[app]:
        if "oauth" in apps[app]:
            apps[app]["oauth"]["logout"] = apps[app]["logout"]

new_logger_levels = {}

for level in conf["blitz"]["prod"]["local"]["idp"]["logger"]["levels"]:
    new_logger_levels[level.replace('\"', '')] = conf["blitz"]["prod"]["local"]["idp"]["logger"]["levels"][level]

conf["blitz"]["prod"]["local"]["idp"]["logger"]["levels"] = new_logger_levels

new_apps = {}

for app in apps:
    new_app_id = app.replace('\"', '')
    new_apps[new_app_id] = apps[app]

conf["blitz"]["prod"]["local"]["idp"]["apps"] = new_apps

new_stores = []

for store in conf["blitz"]["prod"]["local"]["idp"]['id-stores']['list']:
    new_store = {}
    for key in store:
        new_store[key.replace('\"', '')] = store[key]

    new_stores.append(new_store)

conf["blitz"]["prod"]["local"]["idp"]['id-stores']['list'] = new_stores

print(json.dumps(conf, indent=4, ensure_ascii=False))

and specify in the file_path parameter the path to the configuration file.

run the command:

.python/bin/python conf-migr.py > new_blitz.conf

If necessary, customize the login with security keys:
- add to the factors block in blitz.conf for the first and second factor:
```
{
    "enabled" : false,
    "method" : "webAuthn"
}
```
- add webAuthn to the user-profile.enabled-methods / tabs blocks in blitz.conf.
- make the settings according to the documentation (see Login confirmation with WebAuthn, Passkey, FIDO2, U2F).
If the PostgreSQL database is used, apply the 006-usr_htp_hmc_alg, 007-usr_atr_cfm, 008-wak scripts.

Update from 5.3.0 to 5.4.0#

Install new blitz.bin.
If necessary, configure a CAPTCHA test on user registration (see CAPTCHA).

Update from 5.2.4 to 5.3.0#

Install new blitz.bin.
If necessary, configure a CAPTCHA test on password recovery (see CAPTCHA).
Adjust application startup settings blitz.login.setLastAuth.disabled and blitz.csrf.cookie.ttlInSec if necessary (see Configure launch options for Blitz Identity Provider services).
If necessary, configure the call addresses of external vendor handlers (see Call addresses of external providers).
Check and, if needed, adjust the security event notification settings (see Notifications and sending messages).

Adjust the created appearance templates:

Replace the first line of the template (template signature) with a line of the form:

@(headers: Html, form: Html, scripts: Html, path: String)(implicit request: RelyingPartyRequest[_], messages: Messages)

to a line of the form:

@(headers: Html, fBuilder: FormBuilder, scripts: Html, path: String)(implicit request: RelyingPartyRequest[_], messages: Messages)

In the template body, replace @form with @fBuilder().

Update from 5.0 to 5.2.4#

Install new blitz.bin.
In order to enable QR code login and edit settings in the console, you should:
- edit blitz.conf - add the following block to the first factor in login.factors:
```
{
"enabled" : false,
"method" : "qrCode"
}
```
- in the console under “Authentication” configure and enable the authentication method “Login by QR code” (see Login by QR code).
If necessary, enable notifications about logging in from unknown devices - in the console under “Messages”.
If necessary, configure and enable the “multilogin” feature (see Session limit).
If necessary, set up an Apple ID (see Apple ID).
If the PostgreSQL database is used, apply the 005-usr_agt_table script.