8.1. Кастомизация интерфейсов аутентификации, регистрации и восстановления доступа - Avanpost FAM/MFA+

8.1. Кастомизация интерфейсов аутентификации, регистрации и восстановления доступа

Общие сведения

Страницы, отображаемые не аутентифицированному пользователю, могут быть кастомизированы и стилизованы, а именно, изменить можно следующий перечень:

  • Страницы аутентификации по различным методам и факторам аутентификации.
  • Страницы регистрации.
  • Страницы восстановления доступа.
  • Страницы аутентификации посредством доверенных провайдеров.
  • Страницы инициализации аутентификаторов.
  • Страницы ошибок.
  • Шаблоны писем.
  • Системные сообщения в части локализации.

Для версии FAM 1.7 или младше, шаблоны страниц по умолчанию размещены по пути: public/templates/default относительно базового каталога /opt/idp (/opt/idp/public/templates/default). Путь /opt/idp зависит от места установки файлов системы и может отличаться в различных развёртываниях системы.

Файлы шаблонов, размещённые по пути public/templates/*.html являются служебными и не должны быть изменяемы.

Путь к файлам шаблона задаётся в конфигурационном файле системы config.json (начиная с версии FAM v1.8.7.346 меняется конфигурационный файл с config.json на config.toml) в параметре templates секции templates:

"templates": {
    "templates": "public/templates/default",
    ...
},

Для версии FAM 1.8 или старше, шаблоны расположены по пути /opt/idp/public/views/standard. 

Файлы шаблонов, размещённые по пути public/views/standard/*.html являются служебными и не должны быть изменяемы.

Путь к файлам шаблона задаётся в конфигурационном файле системы config.toml в секции ui-templates (для версий FAM от 1.9 и старше):

[ui-templates]
dir = '/opt/idp/public/views'
bundle = 'custom'

Методика первичной кастомизации шаблонов для версий 1.7 и младше

Не рекомендуется вносить изменения в файлы, расположенные по пути public/templates/default. 

Общий подход:

  • Для проверки шаблонов нужно использовать развёрнутый экземпляр системы. Поэтому рекомендуется проверять шаблоны на тестовой среде с системой перед внесением изменений в шаблоны на продуктивном сервере.
  • Для контроля изменений следует использовать систему контроля версий, например, git. Для этого следует инициализировать репозиторий. Также рекомендуется хранить актуальную копию репозитория отдельно от сервера с развёрнутым приложением.

Следует придерживаться следующей методики:

  1. Скопировать файлы из каталога public/templates/default в новый каталог. Например, создать каталог public/templates/custom1, где custom1 - произвольное имя каталога для кастомизируемых шаблонов, и переместить файлы в него:

    cp -R /opt/idp/public/templates/default /opt/idp/public/templates/custom
  2. Инициализировать по пути /opt/idp/public/templates/custom1 репозиторий. Добавить все файлы  в каталоге /opt/idp/public/templates/custom в репозиторий системы контроля версий и выполнить отправку изменений в удалённый репозиторий (remote в терминологии git).
  3. В конфигурационном файле системы config.json внести изменения в параметр templates в секции templates, указав новый путь к каталогу с шаблонами (в примере - public/templates/custom):

    "templates": {
        "templates": "public/templates/custom",
        ...
    },
  4. Выполнить перезапуск службы системы (команда зависит от ОС).

Методика первичной кастомизации шаблонов для версий 1.8 и старше

Не рекомендуется вносить изменения в файлы, расположенные по пути public/views/standard.

Общий подход:

  • Для проверки шаблонов нужно использовать развёрнутый экземпляр системы. Поэтому рекомендуется проверять шаблоны на тестовой среде с системой перед внесением изменений в шаблоны на продуктивном сервере.
  • Для контроля изменений следует использовать систему контроля версий, например, git. Для этого следует инициализировать репозиторий. Также рекомендуется хранить актуальную копию репозитория отдельно от сервера с развёрнутым приложением.

Следует придерживаться следующей методики:

  1. Скопировать файлы из каталога public/views/standard в новый каталог. Для версии 1.8 в порядке исключения нужно скопировать отдельно каталог public/views/standard и переименовать, например, в origin, а в папке standard вносить правки по шаблонам. Для версий, начиная с 1.9, создать каталог public/views/custom, где custom - произвольное имя каталога для кастомизируемых шаблонов, и переместить файлы в него:

    cp -R /opt/idp/public/views/standard /opt/idp/public/views/custom
  2. Инициализировать по пути /opt/idp/public/views/custom репозиторий. Добавить все файлы  в каталоге /opt/idp/public/views/custom в репозиторий системы контроля версий и выполнить отправку изменений в удалённый репозиторий (remote в терминологии git).
  3. В конфигурационном файле системы config.toml внести изменения в секции ui-templates (для версий FAM от 1.9 и старше), указав новый путь к каталогу с шаблонами (в примере - /opt/idp/public/views/custom):

    [ui-templates]
    dir = '/opt/idp/public/views'
    bundle = 'custom'
  4. Выполнить перезапуск службы системы (команда зависит от ОС).

Методика обновления кастомизированных шаблонов при обновлении системы

При обновлении системы следует пользоваться инструментарием системы контроля версий, который позволяет сравнить и выполнить слияние (merge) двух каталогов.

Перечень шаблонов

Таблица шаблонов, доступных для кастомизации:

Файл шаблонаФайл шаблона, версия FAM 1.8Назначение
 403.esia.htmlАктуально до версии 1.5.1Страница "Ошибка доступа" при аутентификации через ЕСИА
 403.htmlАктуально до версии 1.5.1Страница "Ошибка доступа" для стандартных сценариев аутентификации
 500.esia.html500.htmlСтраница "Внутренняя ошибка сервера" при аутентификации через ЕСИА
 500.html500.htmlСтраница "Внутренняя ошибка сервера" для стандартных сценариев аутентификации
 badrequest.htmlblocked.htmlСтраница "Некорректный запрос" для стандартных сценариев аутентификации
 certfactor.htmlcertfactor.gohtmlСтраница аутентификации по сертификату
 changepassword.badrequest.htmlblocked.htmlСтраница с ошибкой "Некорректный запрос" при выполнении смены пароля
 changepassword.htmlНе актуален.Страница смены пароля
 changepassword.invalidtoken.htmlblocked.htmlСтраница с ошибкой "Некорректный токен" при выполнении смены пароля
 changepasswordlink.htmlНе актуально.Страница со ссылкой на смену пароля
 changepassword.ok.htmlrestorepassword-change.htmlСтраница с сообщением об успешной смене пароля
 changepassword.usernotfound.htmlНе актуально.Страница с ошибкой о том, что не удалось найти пользователя при смене пароля
 factorblockederror.htmlblocked.htmlСтраница с ошибкой "Фактор заблокирован"
Не используется. Основная страница login.password.htmlidentification.htmlСтраница идентификации
 kerberos.skip.htmlkerberos.skip.htmlСтраница пропуска Kerberos-аутентификации
 login.emailOtp.codeForm.htmlemail-otp.htmlСтраница аутентификации по одноразовому коду, шаг запроса кода
 login.emailOtp.initialForm.htmlemail-otp-set-address.htmlСтраница аутентификации по одноразовому коду, шаг инициализации запроса
 login.external-provider.infoconfirmation.htmlwebauthn-login.htmlСтраница подтверждения данных пользователя при аутентификации через внешний провайдер аутентификации
 login.password.from.esia.htmlwebauthn-registration.htmlСтраница привязки учётной записи ЕСИА к пользователю, аутентифицированному через ЕСИА, посредством дополнительной аутентификации
 login.password.htmlНе используется. Основная страница identification.html.Страница аутентификации по паролю
 login.password.without-username.htmlpassword-login-without-username.htmlСтраница аутентификации по паролю без ввода имени пользователя
 login.paycontrol.prompt.htmlpaycontrol.gohtmlСтраница запроса аутентификации по PayControl
 login.totp.init.htmlinitflow-totp.htmlСтраница инициализации TOTP
 login.totp.init.with-password.htmlinitflow-totp.htmlСтраница инициализации TOTP с вводом пароля
 login.totp.passcode.htmltotp-passcode.htmlСтраница запроса одноразового кода TOTP
 login.totp.welcome.htmltotp-bind.htmlСтраница привязки TOTP-аутентификатора
 logout.htmllogout.htmlСтраница завершения сессии

shared/_LogoPartial.htmlСтраница логотипа
 mobile.init.htmlauthenticator-bind.htmlСтраница привязки мобильного аутентификатора Avanpost Authenticator
 mobile.password.htmlauthenticator-wait-approve.htmlСтраница аутентификации посредством мобильного аутентификатора Avanpost Authenticator с возможностью ввода OTP
 new.password.htmlpassword-change-on-logon.htmlСтраница замены пароля в случае его истечения
 notavailable.htmlblocked.htmlСтраница с ошибкой "Нет доступа"
 oauth2-required-claims.htmloauth2-required-claims.htmlСтраница с ожиданием появления значения дополнительного claim
 pickfactor.htmlselect-factor.htmlСтраница выбора фактора аутентификации
 pickfactor.username.htmlНе используется. Основная страница select-factor.htmlСтраница выбора фактора аутентификации с идентификацией по имени пользователя
 restorepassword.change.htmlrestorepassword-change.htmlСтраница замены пароля в сценарии восстановления доступа
 restorepassword.email.html

Не актуально.

Страница ввода E-mail в сценарии восстановления доступа
 restorepassword.error.htmlНе актуально.Страница ошибки в сценарии восстановления доступа
 restorepassword.sendlink.htmlrestorepassword-by-email-code.htmlСтраница отправки письма на почту с идентификацией по логину
 restorepassword.sendlink.withoutlogin.htmlrestorepassword-by-email-captcha.htmlСтраница отправки письма на почту без запроса логина
 restorepassword.verifycode.htmlШаблоны писем остались по прежнему адресу с таким же именем, как и раньше.Шаблон письма с кодом верификации
 reverseproxy.accountregistration.htmlselect-factor.htmlСтраница добавления учётной записи Reverse Proxy-приложения в аккаунт пользователя, у которого не привязан ни один аккаунт RP-приложения
  reverseproxy.changepassword.htmlpassword-change-on-logon.htmlСтраница замены пароля Reverse Proxy-приложения в случае если пароль истёк или не подходит
 selfregistration-emailmessage.htmlШаблоны писем остались по прежнему адресу с таким же именем, как и раньше.Шаблон письма об успешной регистрации
 selfregistration.htmlregistration.htmlСтраница с формой самостоятельной регистрации
 selfregistration-invalidtoken.htmlregistration.htmlСтраница с ошибкой о некорректном токене в сценарии самостоятельной регистрации
 selfregistration-successed.htmlregistration-result.htmlСтраница с сообщением об успешной самостоятельной регистрации
 selfregistration-verifycannotunlock.htmlwrong-password-captcha.htmlСтраница с сообщением о не пройденной проверке капчи
 selfregistration-verifysuccessed.htmlwrong-password-captcha.htmlСтраница с сообщением о пройденной проверке капчи
 session-limitexceeded.htmlsession-limitexceeded.htmlСтраница с сообщением о превышении числа доступных сессий для приложения
 sms.htmlsms-otp.htmlСтраница аутентификации посредством SMS OTP
 sms.init.htmlinitflow-sms.htmlСтраница привязки SMS OTP-аутентификатора
 sms.phone.htmlinitflow-sms.htmlСтраница ввода номера телефона для привязки SMS OTP-аутентификатора
 step.activate-by-email.htmlregistration-result.htmlСтраница с активацией аккаунта пользователя, прошедшего самостоятельную регистрацию, по E-mail
 step.sms.htmlinitflow-sms.htmlСтраница с привязкой SMS-аутентификатора в процессе сценария инициализации
 step.telegram.htmlinitflow-telegram.htmlСтраница с привязкой Telegram-аутентификатора в процессе сценария инициализации
 step.totp.htmlinitflow-totp.htmlСтраница с привязкой TOTP-аутентификатора в процессе сценария инициализации
 telegram.htmltelegram.htmlСтраница с аутентификацией посредством Telegram
 telegram.init.htmltelegram-bind.htmlСтраница с инициализацией Telegram-аутентификатора в процессе аутентификации
 webauthn.html webauthn-login.htmlСтраница с аутентификацией посредством WebAuthn-аутентификатора в процессе аутентификации
 webauthn.registration.htmlwebauthn.registration.htmlСтраница с привязкой WebAuthn-аутентификатора в процессе аутентификации

Изменение отдельных страниц

Изменение шаблона формы самостоятельной регистрации

Интерфейс формы самостоятельной регистрации, который отображается пользователям Системы, может быть настроен в части состава полей, их расположения, либо кастомизирован с учётом корпоративного стиля.

Для изменения шаблона самостоятельной регистрации выполните следующие действия:

  1. Откройте указанный каталог с шаблонами (указанный в значении параметра dir секции templates в конфигурационном файле Серверного компонента; по умолчанию он содержит значение «public/templates/default») и найдите файл шаблона selfregistration.html.
  2. Отредактируйте текст шаблона, используя любой текстовый редактор.
Изменение страницы, отображаемой пользователю при выполнении успешной регистрации

По умолчанию отображается шаблон selfregistration-successed.html, расположенный в каталоге, указанном в параметре dir секции templates в конфигурационном файле Серверного компонента. При необходимости выполнения кастомизации страницы с сообщением об успешной регистрации:

  1. Откройте указанный каталог с шаблонами (указанный в значении параметра dir секции templates в конфигурационном файле Серверного компонента; по умолчанию он содержит значение «public/templates/default») и найдите файл шаблона selfregistration-successed.html.
  2. Отредактируйте текст шаблона, используя любой текстовый редактор.

Если требуется, при выполнении успешной регистрации пользователь может быть перенаправлен на произвольную страницу, указанную в значении параметра redirectUrl секции selfregistration в конфигурационном файле Серверного компонента. Если этот параметр задан, то пользователю не будет показан шаблон страницы с сообщением об успешной регистрации, и пользователь будет сразу перенаправлен на указанный redirectUrl.

Изменение страниц аутентификации по факторам

Все файлы шаблонов в каталоге public/templates/default могут быть заменены на требуемые HTML-шаблоны в корпоративном стиле. 

В случае выполнения замены рекомендуется скопировать содержимое каталога public/templates/default в каталог соответствующей кастомизации public/templates/<custom> и выполнять внесение изменений в кастомизации.

Локализация шаблонов интерфейса и системных сообщений

Для переопределения языка стандартных локализованных сообщений следует использовать файлы extension.[lang].toml. Настройки локализации для системных сообщений расположены в директории public/messages, в public/templates/localization хранятся локализации шаблонов.

Файлы extension.[lang].toml имеют формат соответствия ключа и значения сообщения. Пример файла для локализации приведен ниже.

 

.

Обсуждение