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

[ ] [ Общие сведения ] [ Методика первичной кастомизации шаблонов для версий FAM 1.7 и младше ] [ Методика первичной кастомизации шаблонов для версий FAM 1.8 и старше ] [ Методика обновления кастомизированных шаблонов при обновлении системы ] [ Перечень шаблонов ] [ Изменение отдельных страниц ] [ Изменение шаблона формы самостоятельной регистрации ] [ Изменение страницы, отображаемой пользователю при выполнении успешной регистрации ] [ Изменение страниц аутентификации по факторам ] [ Изменение писем восстановления доступа ] [ Переопределение сообщений локализации ]

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

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

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

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

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

Путь к файлам шаблона задаётся в конфигурационном файле системы config.toml (config.toml используется вместо конфигурационного файла config.json с версии FAM v1.8.7.346) в параметре 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'

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

При кастомизации шаблонов стоит придерживаться следующих рекомендаций:

1. Не рекомендуется вносить изменения в файлы, расположенные по пути public/templates/default. 
2. Для проверки шаблонов нужно использовать развёрнутый экземпляр продукта. Поэтому рекомендуется проверять шаблоны на тестовой среде с Avanpost FAM перед внесением изменений в шаблоны на продуктивном сервере.
3. Чтобы контролировать изменения, следует использовать систему управления версиями (например, Git). Для этого в системе управления версиями необходимо инициализировать репозиторий.
4. Рекомендуется хранить актуальную копию репозитория системы управления версиями отдельно от сервера с развёрнутым Avanpost FAM.

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

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. Выполнить перезапуск службы системы (команда зависит от ОС).

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

При кастомизации шаблонов стоит придерживаться следующих рекомендаций:

1. Не рекомендуется вносить изменения в файлы, расположенные по пути public/views/standard.
2. Для проверки шаблонов нужно использовать развёрнутый экземпляр продукта. Поэтому рекомендуется проверять шаблоны на тестовой среде с Avanpost FAM перед внесением изменений в шаблоны на продуктивном сервере.
3. Чтобы контролировать изменения, следует использовать систему управления версиями (например, Git). Для этого в системе управления версиями необходимо инициализировать репозиторий.
4. Рекомендуется хранить актуальную копию репозитория системы управления версиями отдельно от сервера с развёрнутым Avanpost FAM.

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

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 в терминологии Git) двух каталогов.

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

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

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

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

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

• настройка состава и расположения полей формы регистрации; 
• кастомизация с учётом корпоративного стиля.

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

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

Изменение страницы, отображаемой пользователю при выполнении успешной регистрации

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

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

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

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

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

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

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

Изменение писем восстановления доступа

Для редактирования тела письма восстановления необходимо в файле локализации /opt/idp/public/templates/localization/active.ru.toml отредактировать раздел [RestorePasswordMailBody].

[RestorePasswordMailBody]
description = "Restore password mail body"
other = "Вы запросили восстановление вашего пароля. Код для восстановления -"

[PasswordRestoreMessage]
description = "Password restore"
other = "Восстановление пароля"

Для редактирования письма Email OTP следует отредактировать следующие разделы:

[EmailOTPMessageTitle]
description = "Title of the email with a passcode and(or) a link"
other = "Подтвердите вход в систему"

[EmailOTPPasscodeAndLinkMessage]
description = "Passcode to enter the system"
other = "Для входа в систему воспользуйтесь кодом %s или перейдите <a href=\"%s\">по ссылке</a>"

[EmailOTPPasscodeMessage]
description = "Passcode to enter the system"
other = "Для входа в систему воспользуйтесь кодом %s"

После внесения изменений в файл локализации необходимо перезапустить сервис idp: 

sudo systemctl restart idp

Переопределение сообщений локализации

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

Файлы локализации располагаются по следующему пути:

• для шаблонов: public/templates/localization/active.{lang}.toml;
• для системных сообщений: public/messages/active.{lang}.toml

где {lang} - язык (например, для русского языка файл будет носить имя active.ru.toml)

Необходимо учитывать, что изменения, внесенные в данный файл, будут удалены и заменены на стандартные при очередном обновлении продукта. Чтобы избежать утраты изменений следует:

1. Вручную создать файл extension.{lang}.toml, расположив его по тому же пути, что и active.{lang}.toml.
2. Найти сообщение, которое требуется исправить, исходном файле active.{lang}.toml.
3. Создать аналогичную запись в extension.{lang}.toml.

Кастомизированные сообщения, содержащиеся в extension.{lang}.toml обладают приоритетом над стандартными сообщениями из active.{lang}.toml.

.