Обновление Blitz Identity Provider#

Важно

Если обновление ставится с пропуском промежуточных версий, то устанавливать blitz.bin нужно только от последней версии, а остальные настройки выполнить по всем пропускаемым при обновлении релизам.

Внимание

В случае СУБД PostgreSQL нужно проверить по актуальному файлу resources.zip, какие в нем появились новые DDL-скрипты, и выполнить их, если такие изменения отсутствуют в текущей схеме БД.

Обновление с 5.16.2 до 5.18.0#

В случае использования СУБД PostgreSQL применить скрипты:
1. 018-5.17.0.sql
2. 019-5.18.0.sql

Найти в конфигурационном файле blitz.conf блок настроек blitz.prod.local.idp.provisioning.recovery. Внести в блок следующие изменения:

Переименовать настройку security-question в system-security-questions.
Создать блок factor2 и перенести в него целиком секцию methods с содержимым. Удалить исходную секцию methods.
В блоке factor2 установить "mode" : "by_user_required_factor".

Пример блока после редактирования#

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

Установить blitz-5.18.0.bin.

Обновление с 5.15.x до 5.16.x#

В настройках nginx закрыть доступ на адреса /blitz/metrics из внешних сетей:
```
location /blitz/metrics {
    return 404;
}
```
При использовании для приложений особых bundle с помощью lang-variant (опциональное поле lang-variant в настройках приложения) нужно все варианты языка прописать в настройку lang в blitz.conf в настройку lang-variant.

Пример:
```
"lang": {
    "ignore-browser": false,
    "lang-variants": ["12345", "12346"], // this field
    "languages": ["ru","en"],
    "portal-lang-cookie": {
        "domain": ".identityblitz.ru",
        "name": "portal_lang"
    }
}
```
Установить новый blitz.bin.
При необходимости настроить сбор метрик функционирования в Prometheus через непосредственное обращение к /blitz/metrics по внутренним адресам серверов приложений.
При необходимости настроить хранение настроек приложений в отдельных файлах.

Обновление с 5.14.0 до 5.15.x#

В случае использования СУБД PostgreSQL применить скрипты:
1. 017-5.15.0.sql
Установить новый blitz.bin.

Обновление с 5.11.x до 5.14.0#

В случае использования СУБД PostgreSQL применить скрипты:
1. 015-5.12.0.sql,
2. 016-5.13.0.sql
Установить новый blitz.bin.
В разделе «Внешний вид» проверить, что для всех шаблонов в поле «Название шаблона» задано уникальное имя. Если есть несколько шаблонов с одинаковым названием, то переименовать их.
Для каждого настроенного внешнего поставщика идентификации в новом блоке «Выбор пользователя» заполнить значения настроек «Имя пользователя» и «Идентификатор пользователя». Пример заполнения:
- Имя пользователя – ${given_name-} ${family_name-}
- Идентификатор пользователя – ${email&maskInMiddle(4,8)}
Настройка используется в процессе привязки пользователя при первом входе через внешний поставщик идентификации. На основе настройки пользователю показывается карточка найденной для привязки учетной записи в Blitz Identity Provider, соответствующей учетной записи внешнего поставщика идентификации.
Проверить функции входа через внешние поставщики идентификации, если внешний вид экранов привязки при входе будет нарушен, то скорректировать используемые темы внешнего вида.
Корректировка настроек в конфигурационном файле console.conf:
1. Если используется вход в консоль управления по логину/паролю, то в console.conf добавить настройку roleClaim с пустым значением:
Пример:
```
{
"login" : {
    "fp" : {

    ...
    "subjectClaim" : "sub",
    "roleClaim" : "",
    ...
    },
    "mode" : "credentials"
}
}
```
1. Если используется функция входа в консоль управления через SSO, то в console.conf в блок login.fp добавить настройку roleClaim. В качестве значения указать имя атрибута из id_token, в котором передается роль администратора (обычные названия ролей: root, security, sysadmin, app_admin, ui_admin, support, берутся из файла настроек credentials из roles.name). Настроить, чтобы внешняя IDP передавала атрибут с ролью. Атрибут может быть текстовым (String) – тогда передается одна роль, или массивом строк (ArrayOfString), тогда можно передавать множество ролей.
Пример:
```
{
"login" : {
    "fp" : {

    ...
    "subjectClaim" : "sub",
    "roleClaim" : "SOME_CLAIM_NAME",
    ...
    },
    "mode" : "sso"
}
}
```
Из меню “Администраторы” консоли можно удалить тех пользователей-админов, которые входят только через внешний SSO-вход.

Обновление с 5.10.0 до 5.11.x#

В случае использования СУБД PostgreSQL применить скрипты 000-service-tasks.sql, 013-tasks.sql, 014-sec_ch_ua.sql.
Проверить нестандартные строчки в custom_messages. Если в строчках с текстами писем используется функция $[device.mkey&dic(dics.devices)], то заменить ее на $[device.mkey&dic(dics.devices,os.ver)].
Установить новый blitz.bin.
В файле play.conf скорректировать настройки подключения к memcached – добавить operationTimeout, timeoutExceptionthreshold, maxReconnectDelay:
- operationTimeout – время ожидания выполнения запроса к memcached в мс;
- timeoutExceptionThreshold – количество попыток выполнения запроса, после которых узел считается не доступным;
- maxReconectDelay – интервал между попытками установить соединение с узлом в секундах.
Пример конфига с добавленными настройками с рекомендуемыми значениями:
```
"memcached" : {
"operationTimeout" : 1000,
"timeoutExceptionThreshold" : 1,
"maxReconnectDelay" : 10,
"servers" : [
    …
]
}
```
В случае использования СУБД PostgreSQL при необходимости переключить обработку задач с брокера RabbitMQ на брокер jdbc (это можно сделать если RabbitMQ больше ни для чего не используется и есть желание отказаться от его дальнейшего использования). Брокер jdbc рекомендуется использовать только в средах с небольшой нагрузкой.

Для настройки использования брокера jdbc необходимо:
- Проверить, что в блоке настроек stores в файле blitz.conf задана настройка default-type в значении jdbc:
```
"stores" : {
"default-type" : "jdbc"
},
```
- В файл blitz.conf в блоке tasks скорректировать настройки брокера следующим образом:
```
"tasks" : {
"broker-type" : "task-store",
"executionRules" : [
    {
    "maxAttempts" : 2,
    "queue" : "blitz-tasks",
    "redeliveryDelayInSec" : 60
    }
],
"queues" : [
    {
    "dequeueBatchSize" : 10,
    "dequeuePeriodInSec" : 30,
    "executorPoolSize" : 5,
    "name" : "blitz-tasks"
    }
]
}
```
- Серверу, выполняющему обработку задач, добавить параметр запуска akka.coordinated-shutdown.phases.service-stop.timeout в значении 30s:
```
Dakka.coordinated-shutdown.phases.service-stop.timeout=30s
```

Обновление с 5.9.0 до 5.10.0#

В случае использования СУБД PostgreSQL применить скрипт 012-geo_to_audit.sql.
Установить новый blitz.bin.
Если правила выбора хранилищ учетных записей или текущие алгоритмы процедур входа проверяют динамический client_id и выполняют его парсинг с использованием разделителя «:», то необходимо дополнить используемые алгоритмы парсинга, чтобы они учитывали для новых динамических client_id использования символа «~» в качестве разделителя.
При необходимости в блоке «Контроль доступа» приложения добавить правила контроля доступа.
При необходимости включить использование в Blitz Identity Provider справочника геоданных в формате mmdb (справочник приобретается Заказчиком самостоятельно).
При необходимости включить передачу событий безопасности на сервер очередей Kafka.

Обновление с 5.8.0 до 5.9.0#

В случае если планируется продолжать работать с СУБД Couchbase Server версии 6.0, то необходимо в файле etc/default/blitz-* в JAVA_OPTS добавить системную переменную -Dcouchbase.durability.mode=clientVerified.

В будущем если будет произведено обновление до Couchbase Server версии 6.5 или 7.0, то необходимо убрать переменную или изменить ее на одно из возможных значений:
- disabled – Blitz Identity Provider получает ответ от Couchbase после записи в память на основной ноде;
- majority – Blitz Identity Provider получает ответ от Couchbase после записи в память на основной ноде и на большинстве реплик;
- majorityAndPersistActive – Blitz Identity Provider получает ответ от Couchbase после записи на диск на основной ноде и в память на большинстве реплик;
- persistToMajority – Blitz Identity Provider получает ответ от Couchbase ответ после записи на диск на основной ноде и на большинстве реплик.
При отсутствии настройки (работа по умолчанию) используется режим majority.

Переменная влияет на ожидание записи данных в память ноды и на диск, соответственно влияет на производительность.

Оптимальное значение необходимо выявлять в ходе нагрузочного тестирования и с учетом требований по надежности хранения данных.
Изменение настроек работы с хранилищами:
- в файле play.conf удалить блок modules
- в файл blitz.conf в основной блок (рядом с internal-store) добавить блок:
```
"stores" : {
    "default-type": "cb"
},
```
В данном случае в качестве хранилища для всех объектов будет использоваться CouchBase Server.

default-type может принимать значения:
- cb - используется CouchBase
- jdbc - используется PostgreSQL
Если необходимо разделить объекты по разным хранилищам, то надо в блок stores добавить блок:
```
```
"list-of-types" : {
    "<название внутреннего хранилища>" : "<тип хранилища>"
},
```
```
В качестве внутреннего хранилища могут быть следующие значения:
- 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
Изменение настроек работы с задачами

В blitz.conf в блоке tasks необходимо добавить параметр:
```
"broker-type": "<TYPE>"
```
В качестве значения <TYPE> указать одно из следующих:
- cb – обработка очередей в CouchBase
- rmq – обработка очередей в RabbitMQ
Если параметра broker-type нет, то по умолчанию используется CouchBase. При использовании PostgreSQL в качестве основной СУБД доступна только обработка очередей в RabbitMQ.
При необходимости настроить регистрацию аудита незавершенных попыток входа (когда пользователь ввел правильные логин и пароль, но не смог подтвердить вход).

Для этого в файле blitz.conf в блоке login добавить параметры:
```
"postponeEnabled" : true,
"postponeTtl" : 3600 // время в секундах, по умолчанию 10800
```
Параметр postponeTtl задает время ожидания окончания входа. После истечение этого времени может быть зарегистрировано событие о незавершенной попытке входа, если к этому моменту вход еще не завершится.

В случае если для обработки задач используется RabbitMQ, то для основной очереди задач необходимо сделать дополнительную очередь с название <название основной очереди>-postpone и задать для нее следующие аргументы:
```
x-dead-letter-exchange = <используемый exchange>
x-dead-letter-routing-key = <основная очередь>
```
Так же для созданной очереди необходимо настроить binding на используемый exchange.
Задать настройку регистрации событий безопасности. В файле blitz.conf добавить блок:
```
"audit": {
    "emitters": [
        "audit-store",
        "log"
    ]
},
```
В блоке emitters указывают:
- audit-store - данные будут отправлены в БД, согласно настройкам из блока stores
- log - данные будут отправлены в файл, согласно настройкам в logback.xml
При необходимости можно оставить только один emitter.

Предупреждение

Без блока audit данные аудита не будут сохраняться и отображаться!

Пример блока в logback.xml для настройки отправки аудита в файл:
```
<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>
```
Подготовить комплект новых процедур входа для релиза 5.9.0:
- Если используются стандартные процедуры входа, то взять обновленные процедуры входа из раздела «Примеры процедур входа» Настройка процедур входа в приложения. Внести в них правки, если ранее в использованные стандартные процедуры входа вносились правки.
- Если используются нестандартные процедуры входа, то обратиться в техническую поддержку РЕАК СОФТ для корректировки процедур либо выполнить корректировку самостоятельно. Необходимые изменения в процедуре входа:
Если в процедуре входа использовался вызов вида
```
userReqFactor = ctx.userProps("requiredFactor")
```
или иное обращение к ctx.userProps("requiredFactor") для определения требуемого для пользователя уровня аутентификации, то нужно скорректировать вызов на следующий:
```
Integer userReqFactor = 0;
if (ctx.user() != null) {
    userReqFactor = ctx.user().requiredFactor();
}
```
В консоли управления деактивировать все процедуры входа, требующие изменения (см. предыдущий пункт).
В случае использования СУБД PostgreSQL применить скрипты 010-add_usr_prp.sql, 011-pp_audit.sql.
Установить новый blitz.bin.
Обновить и активировать в консоли процедуры входа на скорректированные для релиза 5.9.0.
При необходимости через консоль управления настроить вход через Тинькофф ID.
При необходимости адаптировать новые стандартные процедуры входа для функций «Настройка Face ID / Touch ID при входе», «Отображение объявления при входе», «Запрос согласия при входе», «Запрос ввода атрибута при входе».

Обновление с 5.7.0 до 5.8.0#

Установить новый blitz.bin.
При необходимости в консоли управления Blitz Identity Provider в настройках метода аутентификации “Подтверждение с помощью ключа безопасности” в блоке “Первый фактор” можно включить настройку “Приравнять использование этого метода к применению первого и второго фактора. Если опция включена, то вход по ключу безопасности будет означать, что пользователь прошел двухфакторную аутентификацию”.

Обновление с 5.6.7 до 5.7.0#

Установить новый blitz.bin.
При необходимости настроить использование внешних валидаторов и трансляторов атрибутов (см. Внешний валидатор атрибута и Транслятор атрибута).
В случае использования СУБД PostgreSQL применить скрипт 009-fix_pp_column.

Обновление с 5.4.0 до 5.6.7#

Установить новый blitz.bin.
Выполнить миграцию настроек допустимых префиксов возврата при логауте:
- Если приложений не много, то в консоли управления в настройках каждого приложения внести в блоке OAuth 2.0 карточки приложения разрешенные префиксы URL возврата при логауте (настройка была перенесена из основных настроек приложения в блок протокола OAuth 2.0 приложения). См. Настройка OAuth 2.0 и OpenID Connect 1.0.
  - отредактировать настройки приложения _blitz_profile (в консоли можно перейти по ссылке /console/app?id=_blitz_profile):
  - настроить протокол OAuth (если еще не настроено), указав client_secret (любой, не будет использоваться) и префикс ссылок возврата (можно указать адрес, по которому доступно приложение /blitz/profile).
- Если приложений много (несколько десятков), то воспользоваться скриптом автоматизации обновления настроек:
  - потребуется python3 с установленным модулем pyhocon.
  - создать файл conf-migr.py и вставить в него скрипт миграци настроек логаута:
    # -*- 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))
    при этом в параметре file_path указать пусть к файлу конфигурации.
  - далее выполнить команды:
    .python/bin/python conf-migr.py > new_blitz.conf
При необходимости настроить вход с помощью ключей безопасности:
- в блок factors в blitz.conf для первого и второго фактора добавить:
```
{
    "enabled" : false,
    "method" : "webAuthn"
}
```
- в блоках user-profile.enabled-methods / tabs в blitz.conf добавить webAuthn.
- выполнить настройки согласно документации (см. Подтверждение входа с помощью ключей безопасности (WebAuthn, Passkey, FIDO2, U2F)).
В случае использования СУБД PostgreSQL применить скрипты 006-usr_htp_hmc_alg, 007-usr_atr_cfm, 008-wak.

Обновление с 5.3.0 до 5.4.0#

Установить новый blitz.bin.
При необходимости настроить тест CAPTCHA при регистрации пользователя (см. CAPTCHA).

Обновление с 5.2.4 до 5.3.0#

Установить новый blitz.bin.
При необходимости настроить тест CAPTCHA при восстановлении пароля (см. CAPTCHA).
При необходимости скорректировать настройки запуска приложений blitz.login.setLastAuth.disabled и blitz.csrf.cookie.ttlInSec (см. Настройка опций запуска приложений Blitz Identity Provider).
При необходимости настроить адреса вызова обработчиков внешних поставщиков (см. Адреса вызовов внешних поставщиков).
Проверить и при необходимости скорректировать настройки уведомлений о событиях безопасности (см. Настройка уведомлений и отправки сообщений).
Скорректировать созданные шаблоны внешнего вида:

Первую строку шаблона (сигнатура шаблона) заменить со строки вида:
```
@(headers: Html, form: Html, scripts: Html, path: String)(implicit request: RelyingPartyRequest[_], messages: Messages)
```
на строку вида:
```
@(headers: Html, fBuilder: FormBuilder, scripts: Html, path: String)(implicit request: RelyingPartyRequest[_], messages: Messages)
```
В теле шаблона заменить @form на @fBuilder().

Обновление с 5.0 до 5.2.4#

Установить новый blitz.bin.
Для возможности включить вход по QR-коду и редактирования настроек в консоли, необходимо:
- отредактировать blitz.conf - добавить на первый фактор в login.factors следующий блок:
```
{
"enabled" : false,
"method" : "qrCode"
}
```
- в консоли в разделе «Аутентификация» настроить и включить метод аутентификации “Вход по QR-коду” (см. Вход по QR-коду).
При необходимости включить уведомления о входе с неизвестных устройств - в консоли в разделе «Сообщения».
При необходимости настроить и включить функцию «мультивход» (см. Ограничение сессий).
При необходимости настроить Apple ID (см. Вход через Apple ID).
В случае использования СУБД PostgreSQL применить скрипт 005-usr_agt_table.