В данном разделе описан интерфейс, который должен быть предоставлен Proxy-сервером для Pro компоненты iDa Mobile. В качестве базового типа веб-сервиса, который должен предоставлять Proxy выбран Axis2 Web Service. При необходимости в Pro может быть реализована работа с сервисами других типов. Для удобства понимания в данном разделе протокол описывается в терминах Java-кода, на основе которого было сгенерировано wsdl описание Proxy web service.
Каждый запрос передает на сервер один объект RequestDTO и получает ответ в виде объекта ResponseDTO. Ниже описаны семантика каждого из методов, а также структура параметров и результатов запросов.
Requests description
Запросы, принимающие bankClientId должны производить проверку допустимости доступа клиента с данным идентификатором к запрашиваемым сущностям. Например, при запросе транзакций счета с идентификатором productId необходимо проверить, является ли пользователь с данным идентификатором productId владельцем счета. При нарушении условий безопасности выполнение может завершаться ошибкой – данная ситуация невозможна при использовании поставляемого клиентского приложения и какая-то осмысленная обработка на клиенте не является необходимой.
blockCard
Запрос на блокировку карты
key
type
status
comment
Request:
bankClientId
string
1..1
идентификатор клиента
cardId
string
1..1
идентификатор карты для блокировки
Response:
result
string
1..1
результат операции {OK, ERROR}
faultMessage
string
0..1
сообщение об ошибке
Exception:
BankClientNotExistsException
string
0..1
клиент с запрошенным bankClientId не существует
CardNotExistsException
string
0..1
карта с запрошенным cardId не существует
changePassword
www.websequencediagrams.com
participant Bank proxy as b
participant iDa Pro as p
participant Mobile as m
note over p,m,b: --- var 1 ---
m->p:
p->b: login { login, password }
b->p: loginResult { bankClientId, PASSWORD_CHANGING_REQUIRED }
m->p:
p->b: changePassword { newPassword }
b->p: ok
p->m: ok
note over p,m,b: --- var 1 ---
m->p:
p->b: login { login, password }
b->p: loginResult { bankClientId, VALIDATION_REQUIRED }
p->m:
b->m: send SMS
m->p:
p->b: login { login, password, validationCode }
b->p: loginResult { bankClientId, PASSWORD_CHANGING_REQUIRED }
p->b: changePassword { newPassword }
b->p: ok
p->m: ok
Запрос на смену пароля при логине. Фактически пользователь логинится под старым паролем (или временным), но банк принудительно заставляет его сменить пароль на новый.
Варианты использования
Смена пароля без 2х факторного подтверждения смс
Смена пароля с 2х факторной процедурой
key
type
status
comment
Request:
newPassword
string
1..1
новый пароль в открытом виде
Response:
result
string
1..1
результат выполнения команды {OK, ERROR}
message
string
0..1
расширенное сообщение об ошибке
checkClient
www.websequencediagrams.com
participant Bank proxy as b
participant iDa Pro as p
participant Mobile as m
note over p,m,b: use PIN code first time
m->p: loginWithPassword { login, password, deviceInfo }
p->b: login { login, password, deviceInfo }
b->p: bankClientId
p->m: sessionId
m->p: isPinEstablished { deviceInfo, login }
alt NO PIN
m->+p: establishPin { pin }
p-->>p: PostgreSQL [ login, pin, sessionId ]
p->-m: OK
end
note over p,m,b: use PIN code second time
m->p: loginWithPin { pin, login, deviceInfo }
p->b: checkClient { bankClientId }
Запрос на проверку валидности клиента во время авторизации по ПИН-коду
Краткое описание схемы
Отправляется запрос IsPinEstablishedRequest с текущим логином и кодом из ответа на запрос GetDeviceVerificationCodeRequest.
В случае не 2xx HTTP ответа от сервера установка пина прерывается, пользователь переходит в pro-часть приложения.
Если в ответе на IsPinEstablishedRequest вернулось, что пин уже установлен, то пользователю показывается сообщение об этом, в настройках приложения сохраняется маркер, что для пользователя с таким логином пин установлен. Пользователь переходит в pro-часть приложения.
Если пин до этого не был установлен, пользователю показывается интерфейс для ввода пина. После того, как он нажмет на кнопку “Установить”, на сервер отправится запрос EstablishSecurityKeyRequest с ключами из алгоритма Диффи- Хеллмана.
В случае, если запрос вернул ошибку, пользователю покажется сообщение об ошибке, и он остается на экране установки пина.
В случае успешного ответа, пин шифруется с помощью алгоритма Диффи-Хеллмана с полученным из ответа на EstablishSecurityKeyRequest публичным ключем от сервера. Зашифрованный пин отправляется на сервер запросом EstablishPinRequest.
В случае, если запрос вернул ошибку, пользователю показывается сообщение. Он остается на экране установки пина.
Успешный ответ означает, что пин установлен на сервере. В настройках приложения сохраняется маркер, что для пользователя с таким логином пин установлен. Пользователь переходит в pro-часть приложения.
Запрос на получение следующей формы в цепочке форм. Принимает заполненную пользователем форму, выдает следующую форму в цепочке вместе с предзаполненными данными для нее
Запрос на получение следующего вопроса по цепочке. Принимает идентификатор предыдущего вопроса и код ответа на предыдущий вопрос, выдает следующий вопрос, результат операции и сообщение.
получатель с запрошенным beneficiaryId не существует
getPersonalNews
Запрос на получение личных уведомлений и новостей для пользователя. Физически попадает в отдельный раздел меню. Наличие раздела управляется через ключ PERSONAL_NEWS в BANKCLIENTDTO
В запрос передается набор фильтров, результатом является список транзакций, отсортированный в порядке убывания даты их выполнения. Каждая из выбранных транзакций удовлетворяет каждому условию фильтра в запросе
key
type
status
comment
Request:
bankClientId
string
1..1
идентификатор клиента
productId
string
1..1
идентификатор продукта
cardId
string
0..1
идентификатор карты
fromIndex
int
1..1
начиная с какой позиции нужно передать транзакции (при первом запросе - 0)
идентификатор обьекта из поля type (если не указан, то проверяется то обновляется весь список)
Response:
haveUpdates
bool
1..1
нужно ли обновлять
ObjectType
key
comment
BENEFICIARY_CATEGORIES
раздел платежей
STANDARD_FORMS
список стандартных форм
PAYMENT_FORM
форма и наследник формы
login
Запрос проверяет корректность пары login/password, если пара верна – возвращает идентификатор клиента bankClientId, соответствующий логину на стороне бэка
key
type
status
comment
Request:
login
string
1..1
логин
password
string
1..1
пароль
validationCode
string
0..1
код из SMS, который передаётся только в случае ответа на команду логин с результатом VALIDATION_REQUIRED
двухфакторная аутентификация с ожиданием кода из СМС
makeTransfer
www.websequencediagrams.com
participant Bank proxy as b
participant iDa Pro as p
participant Mobile as m
participant PiGeon as pi
p->+b: query form
b->-p: form ( hasNext = false )
p->m:
m->p:
p->b: makeTransfer
alt needConfirmation = true, transferCode = tcode
b->p:
b->pi: send confirmCode = ccode
pi->m:
m->p:
p->b: confirmTransfer ( transferCode = tcode, confirmCode = ccode)
b->p: ok
p->m:
else needConfirmation = false
b->p: ok
p->m:
end
Запрос на совершение платежа, поддерживает два режима – с подтверждением и без. Если необходимо подтверждение платежа, признак needConfirmation должен быть выставлен в true и присутствовать код перевода в transferCode, данный код используется в confirmTransfer для обозначения того, какой перевод мы подтверждаем
список идентификаторов уведомлений (персональных новостей), которые нужно пометить как прочитанные
Response:
result
string
0..1
статус выполнения запроса {OK, ERROR}
Exception:
BankClientNotExistsException
string
0..1
клиент с запрошенным bankClientId не существует
removeTemplate
Удаление шаблона
key
type
status
comment
Request:
bankClientId
string
1..1
идентификатор клиента
templateId
string
1..1
идентификатор шаблона
Response:
result
string
1..1
результат выполнения команды {OK, ERROR}
message
string
0..1
сообщение об ошибке или иное сообщение
Exception:
BankClientNotExistsException
string
0..1
клиент с запрошенным bankClientId не существует
requestCommission
Запрос на расчет комиссии по платежу – отправляется заполненная форма с информацией о платеже, результатом работы является ответ, содержащий размер комиссии и валюту
Запрос проверяет наличие пользователя, если пользователь присутствует – возвращает информацию, необходимую для проверки пароля. Метод используется при построении банком облачной системы, когда проксирующий сервер iDaPro вынесен за периметр банка и необходимо не передавать пароль. В обычной ситуации применяется метод login
от пароля взят hash по алгоритму SHA2 (без использования salt)
Data Structs
Используются в общении iDa Pro сервера и Proxy банка
Все платежи, переводы, шаблоны в iDa архитектуре представлены с помощью «ФОРМ». Все данные, которые пользователь может вводить для совершения операций описываются в виде форм, а конкретные введенные пользователем данные – в виде заполненных форм.
Ниже излагается универсальная структура описания форм в системе iDa Mobile. Каждая форма (например, форма денежного перевода) задается кортежем, на который ссылается набор полей формы formField. На кортеж formField может ссылаться некоторое количество кортежей comboBoxValue, которые задают допустимые значение поля формы в случае, если formField.fieldClass = COMBO_BOX.
Следует обратить внимание, что данная структура описывает и хранит не конкретные значения полей форм, а описание структуры формы и типов полей. Конкретные значения хранятся в паре filledForm – formValue.
С помощью форм также можно создавать элемент обратной связи, заявки на продукты и другие распоряжения килента банку
тип формы для переходов или идентификатор (может быть не уникальный)
hasNext
bool
1..1
признак наличия следующей формы. Если значение поля равно TRUE, то при заполнении данной формы клиент запросит с сервера следующую форму вместо запроса на осуществление платежа
requiresCommission
bool
0..1
признак необходимости запроса комиссии с сервера с помощью метода requestCommission
список идентификаторов продуктов в виде ComboBoxValueDTO выбора 1..*
TARGET_ACCOUNT
string
список идентификаторов продуктов в виде ComboBoxValueDTO выбора 1..*
SINGLE_LINE_TEXT
string
однострочный текст
MULTI_LINE_TEXT
string
многострочный текст
CHECK_BOX
bool
чекбокс {true, false} (поддерживает в name ссылку в формате <a href="http://www.idamob.ru">iDa Mobile</a>)
PASSWORD
string
однострочный текст маскированный при вводе
MONTH_YEAR
string
UNIXTIME в милисекундах
DATE
int
UNIXTIME в милисекундах (например 1394582400000)
COMBO_BOX
string
список строк для comboBoxValues выбора 1..*
AMOUNT
int
ddddd (умноженное на 100) с валютой и проверкой на остаток средств из SOURCE_ACCOUNT
MONEY
int
ddddd (умноженное на 100) с валютой из SOURCE_ACCOUNT
PHONE
int
номер телефона (например 71231231212)
PRINTED_TEXT
string
текст пояснение без возможности редактирования пользователем
PHOTO_CARD
string
ввода номера карты с элементом фотографирования карты библиотекой card.io и маской **** **** **** ****, так же в дополнение для поля используется проверка алгоритмом Луна
URL для доступа к логотипу распознает параметр для удобства расположения на сервере и оптимизации размеров - http://…/${image.type}/name.png и будет автоматически в зависимости от платформы подменять его на ios-small или android-small
size
.type
comment
64х64
small
картинка для списка форм
90х60
small
картинка логотипа карты (VISA, MasterCard…) отображаемая на карте и в списке продуктов
640х380
big
картинка фона пластиковой карты
640х320
big
картинка баннера в форме
640х320
small
картинка баннера в новостях
640х128
big
картинка фона формы (используется в SPECIAL_ORDERS) для большей наглядности
наличие раздела в боковом меню с именем String, в который собираются формы с признаком PRODUCT_ORDER
FINANCIAL_REPORTS
string
наличие в меню раздела финансовой аналитики, запрос на аналитику идет через getTransactionsByDateRange с полем id продукта FINANCIAL_REPORTS
PERSONAL_NEWS
string
наличие в меню раздела персональных новостей или уведомлений о событиях
AccountDTO, CardDTO, DepositDTO, LoanDTO support MarkerDTO:
<tagstype="MarkerDTO"><key>BUTTON_1_TEXT</key><value>Payments</value></tags><tagstype="MarkerDTO"><key>BUTTON_1_TARGET</key><value>payment_short</value></tags><tagstype="MarkerDTO"><key>BUTTON_2_TEXT</key><value>Transfer by phone</value></tags><tagstype="MarkerDTO"><key>BUTTON_2_TARGET</key><value>form</value></tags>
ссылка, которая должна быть открыта при выборе данного действия
PersonalNewsDTO
<details><entry><key>logo_url</key><value>http://www.idamob.ru/ic.png</value></entry><entry><key>push_description</key><value>Текстовый блок с некоторым описанием</value></entry><entry><key>name</key><value>Заголовок сообщения</value></entry><entry><key>currency</key><value>100000000</value></entry><entry><key>fxAmount</key><value>RUR</value></entry><entry><key>Период</key><value>3 года</value></entry><entry><key>Процент</key><value>3%</value></entry></details>
Открыть файл .war при помощи ZIP-архиватора и перейти в подпапку “.war\WEB-INF\classes\META-INF”
Открыть файл persistence.xml и внести соответствующие правки, необходимые для подключения к БД (параметры: hibernate.connection.url, hibernate.connection.username, hibernate.connection.password).
Заменить в *.war файле persistence.xml на тот, который был отредактирован в п.3
Запустить Apache Tomcat (в случае с linux - ./tomcat/bin/startup.sh, в случае с windows вомпользоваться специальной системной службой)
Установка iDa Pro
В подпапке pro.war\WEB-INF\classes\config открыть конфигурационный файл банка (Например, bank.properties) и проверить корректность значений параметров proxy.wsdl, proxy.service, proxy.endpoint а так же проверить доступность значения параметра proxy.wsdl с машины, на которой будет запущен iDa Pro. В случае внесения изменений в файл *.properties - сохранить новую версию этого файла в pro.war
Скопировать файл pro.war в папку /tomcat/webapps и дождаться пока будет автоматически создана подпапка /Pro
Открыть через pgAdmin требуемую БД и проверить, что в схеме proschema добавились таблицы
Проверить работоспособность приложения с помощью настроенного мобильного клиента
Порядок обновления серверной части iDa Mobile (*.war)
Получить новую сборку в виде файла *.war
Открыть файл .war при помощи ZIP-архиватора и перейти в подпапку “.war\WEB-INF\classes\META-INF”
Открыть файл persistence.xml и внести соответствующие правки, необходимые для подключения к БД (параметры: hibernate.connection.url, hibernate.connection.username, hibernate.connection.password).
Заменить в *.war файле persistence.xml на тот, который был отредактирован в п.3
Убедится, что серверй приложений Tomcat запущен (в linux - ps -ef|grep tomcat</code>). Если не запущен - запустить его (в linux - ./tomcat/bin/startup.sh).
Перейти в папку tomcat/webapps
В случае наличия в ней старой версии iDa - удалить файл *.war и дождаться пока папка обновляемого приложения удалится автоматически (~ 15 секунд)
Скопировать в папку /tomcat/webapps/ полученный в п.4 файл *.war
Дождаться пока в папке /tomcat/webapps появится папка с наименованием приложения (~ 15 секунд)
Осуществить проверку работы приложения при помощи настроенного мобильного клиента
Рекомендация по развертыванию нескольких серверов на одной машине
Повторно выполнить шаги 3, 4, 5 из раздела ‘Порядок установки серверной части iDa Mobile’ для создания ещё одной копии схемы БД
В Apache TomCat задеплоить копии pro.war и light.war предварительно переименовав их, например в pro_new.war и light_new.war
Установить фронт-серверное приложение, например, nginx или Apache HTTPD
Настроить дополнительный домен, например, если у вас используется домен ida.mybank.com для мобильных приложений, то нужно создать домен ida_new.mybank.com, который так-же будет ссылаться на IP настраиваемого сервера
Произвести настройку фронт-сервера таким образом, что бы траффик для домена ida.mybank.com перенаправлялся на localhost:8080/pro (8080 - порт TomCat по умолчанию), а траффик ida_new.mybank.com направлялся на localhost:8080/pro_new. Пример подобной настройки nginx
Все настройки сервиса задаются через файл конфигурирования, который расположен по адресу pro.war\WEB-INF\classes\config\bank.properties путём добавления следующих параметров:
key
type
comment
smarttransactions.enabled
bool
наличие модуля SmartTransactions
proxy.timeout
int
время ожидания отвера сервера из бэка, в милесекундах (должно быть так же установлено в мобильной апликации)
proxy.login.case.insensitive
bool
признак чуствительности к регистру для логина
-
proxy.wsdl
string
${bank.proxy.wsdl}
proxy.service
string
IdaMobProxyServiceFacade
proxy.endpoint
string
IdaMobProxyServiceFacadeHttpSoap12Endpoint
-
security.password.hash
bool
наличие запроса хэш пароля и алгоритм как он был получен requestHashedPassword. на сервере pro происходит проверка совпадают ли хеши полученные с клиента и с сервера банка
security.password.encrypt
bool
расшифровывать пароль, зашифрованный на мобильном криенте
security.verification.encrypt
bool
расшифровывать код из запроса confirmTransfer, зашифрованный на мобильном криенте
security.incorrect_login_attempts
int
количество неверных попыток ввода ПИН кода
-
pigeon.url
string
сервер пушей http://dev.idamob.ru/pigeon
pigeon.enabled
bool
наличие связки с сервером пуш сообщений PiGeon
pigeon.twoFactorAuth
bool
наличие процесса двухфакторной аутентификации при подписке пользователя на пуш уведомления
Все настройки базы задаются через файл конфигурирования, который расположен по адресу pro.war/WEB-INF/classes/META-INF/persistence.xml путём добавления следующих параметров:
key
type
comment
hibernate.connection.url
string
адрес расположения базы банных
hibernate.connection.username
string
логин к базе
hibernate.connection.password
string
пароль к базе
Удаление сессий пользователя
В случае если у пользователя сменился логин, но не поменялся bankClientId, вход под новым логином будет невозможен. Для того что бы очистить данные по старому логну LOGIN нужно выполнить скрипт в proschema:
select id from proschema.bank_user usr where usr.login = 'LOGIN'
от результата этого запроса подставьте вместо #ID# нижеследующих запросах
delete from proschema.secret_key sc where sc.session_id in (select id from proschema.user_session ses where ses.user_id = '#ID#')
delete from proschema.user_session ses where ses.user_id = '#ID#'
delete from proschema.device_verification_code dvc where dvc.user_id = '#ID#'
delete from proschema.device_verification_code_salt dvc where dvc.user_id = '#ID#'
delete from proschema.bank_user usr where usr.id = '#ID#'
