Быстрый старт¶

Назначение и архитектура JC-WebClient¶

JC-WebClient представляет из себя приложение на основе технологии локального веб-сервера, которое работает на стороне клиента. Приложение:

принимает локальные HTTPS-запросы от браузера
на основе этих запросов отправляет команды токену и/или Антифрод-терминалу либо выполняет программные функции;
возвращает результат работы в браузер.

JC-WebClient поддерживает:

все популярные платформы: Microsoft Windows, macOS, Linux;
все популярные браузеры: Google Chrome, Opera, Mozilla Firefox, Яндекс.Браузер, Apple Safari, Microsoft IE, Microsoft Edge, Спутник.

В качестве средства строгой двухфакторной аутентификации и электронной подписи JC-WebClient поддерживает USB-токены/смарт-карты JaCarta и eToken с аппаратно реализованными российскими и западными криптоалгоритмами. В их числе:

JaCarta ГОСТ, JaCarta PRO, комбинированные токены семейства JaCarta, поддерживающие функциональность PRO и/или GOST;
eToken ГОСТ, eToken PRO (Java), eToken ГОСТ/USB с апплетом PRO.

В качестве доверенного Trust Screen-устройства JC-WebClient поддерживает Антифрод-терминал – собственный продукт компании «Аладдин Р.Д.».

Архитектура JC-WebClient приведена на рисунке ниже:

Основные компоненты JC-WebClient:

Локальный веб-сервер
- обеспечивает взаимодействие между веб-страницей и токеном/Антифрод-терминалом по протоколу HTTPS;
- обеспечивает разделение PC/SC контекстов для различных вкладок браузера.
Клиентский скрипт JCWebClient.js
- предоставляет веб-страницам JavaScript API для работы с методами JC-WebClient;
- загружается на веб-страницу с локального веб-сервера;
- при вызове из контекста страницы веб-приложения методов объектов, реализованных в файле JCWebClient.js, управление передаётся на локальный веб-сервер и далее к токену.
Сервис мониторинга, выполненный в виде службы ОС
- запускает локальный веб-сервер при загрузке ОС;
- контролирует целостность локального веб-сервера;
- перезапускает локальный веб-сервер в случае нештатных ситуаций/сбоев в ОС.

Пошаговое руководство по доработке веб-страниц¶

Подключение и инициализация JC-WebClient¶

Для возможности работы с JC-WebClient через JavaScript API на веб-странице подключите скрипт JCWebClient.js с локального адреса: https://localhost:24738/JCWebClient.js:
```
<script type="text/javascript" src="https://localhost:24738/JCWebClient.js"></script>
```

Определите, установлен ли JC-WebClient. Для этого добавьте в код веб-страницы следующий фрагмент:

if((typeof JCWebClient != 'undefined') && (typeof JCWebClient.id == 'undefined')) {
    // Модуль JC-WebClient установлен, можно работать с его методами
}
else {
    // Модуль JC-WebClient не установлен. Необходимо предложить пользователю сделать установку
}

Если JC-WebClient не установлен:
1. Отобразите пользователю информационное сообщение о необходимости установить JC-WebClient. В этом же сообщении сообщите о том, что загрузка инсталлятора JC-WebClient на ПК пользователя начнётся автоматически, но если не началась в течение, например, 5 секунд, предложите нажать на специальную ссылку для скачивания инсталлятора с веб-сервера.
2. Выполните автоматическую загрузку инсталлятора JC-WebClient на ПК пользователя с веб-сервера вашего приложения.
3. Если пользователь работает на платформе Microsoft Windows, Linux, то для работы с JC-WebClient не требуется перезагрузка браузера или ПК. В этом случае сразу после загрузки инсталлятора начните проверять в цикле установлен ли JC-WebClient. Как только будет определено, что установлен, следует перейти к пункту 4.
4. Если пользователь работает на платформе macOS, то после установки JC-WebClient потребуется перезагрузка ПК. Инсталлятор JC-WebClient уведомит об этом пользователя.
Если JC-WebClient установлен, инициализируйте его работу на веб-странице вызовом метода initialize():
```
JCWebClient().initialize();
```
Метод initialize() помимо прочего инициирует события, которые формирует приложение JC-WebClient и отправляет на веб-страницу. Данные события можно обрабатывать с помощью методов addEventListener() и removeEventListener().

Базовые методы для работы с токенами¶

При работе с USB-токенами и смарт-картами (далее – токенами) необходимо выбрать на токене криптографическое приложение (далее – апплет). На одном токене может быть несколько апплетов. Различные апплеты обладают различной функциональностью: например, апплет GOST реализует российские криптоалгоритмы, а апплет PRO – западные. Для работы с апплетами в JC-WebClient API предусмотрены слоты – абстрактные идентификаторы апплетов.

Для получения массива идентификаторов всех апплетов, поддерживаемых JC-WebClient, на всех подключенных к ПК токенах используйте метод getAllTokens():
```
var TokenIDs = JCWebClient().getAllTokens();
```
Например, если к ПК подключен один токен JaCarta PRO/ГОСТ (на нём 2 поддерживаемых JC-WebClient апплета – PRO и GOST), то метод getAllTokens() вернёт массив из двух идентификаторов: один – для апплета PRO, второй – для апплета GOST.
После получения массива всех идентификаторов выберите апплет, с которым вы хотите продолжать работать. Используйте метод getTokenInfo() для получения информации об апплете токена. Отсортировать массив апплетов по их типу можно следующим образом:
```
var TokenPRO = [];
var TokenGOST = [];
for (i = 0; i < TokenIDs.length; i++) {
   switch(JCWebClient().getTokenInfo(TokenIDs[i])[3]) {
   case "PRO":
      TokenPRO.push(i);
      break;
   case "GOST":
      TokenGOST.push(i);
      break;
   }
}
```
Далее получите информацию о сертификатах, загруженных на токен в данный апплет. Для этого используйте следующие методы:
1. getCertificateList(), getCertificateListAsync() – получение списка всех идентификаторов сертификатовl;
2. getCertificateListEx(), getCertificateListExAsync() – получение списка идентификаторов сертификата, выполняющих условия поиска;
3. readCertificateEx() - чтение сертификата по идентификатору;
4. parseCertificate(), parseCertificateEx() – вывод полной информации сертификата по идентификатору;
5. getCertificateInfo(), getCertificateInfoEx() - получение общей информации о сертификате по идентификатору.
Полученную о сертификатах информацию необходимо отфильтровать и
1. либо выбрать сертификат для работы с системой автоматически на основе известных веб-приложению фильтров и критериев;
2. либо предоставить пользователю возможность выбрать сертификат из отфильтрованного списка, который он хочет использовать для работы с системой.
После выбора сертификата, необходимо аутентифицироваться в апплете с помощью PIN-кода пользователя. Без аутентификации апплет будет работать в гостевом режиме с ограниченным функционалом: нельзя генерировать ключевые пары, создавать изменять удалять объекты на токене, создавать подпись. Для аутентификации необходимо запросить у пользователя PIN-код пользователя и использовать его в методах bindToken(), bindTokenAsync() или bindTokenUI().
После успешной аутентификации токен переходит в режим пользователя, все пользовательские операции становятся доступными.
Узнать в каком режиме работает токен можно:
1. с помощью метода getLoggedInState().
2. с помощью события loginStateChangedEvent().
Методы JC-WebClient возвращают коды ошибок согласно данному списку. Для получения информации об ошибках реализованы методы getLastError() и getErrorMessage().
С дополнительными примерами работы с токеном можно ознакомиться в соответствующем разделе.

Разделение контекста между вкладками браузера¶

В JC-WebClient реализовано разделение контекста (сеансов работы с токеном) при работе из различных вкладок браузера. Это означает, что сеанс работы с токеном, установленный из одной вкладки, недоступен для сеанса работы с токеном, установленного из другой вкладки.

Контекст по умолчанию сохраняется при переходе с одной страницы на другую в рамках одной и той же вкладки браузера, а также при обновлении страницы (нажатие клавиши F5).

JC-WebClient предоставляет возможность явного указания на необходимость обнуления контекста при выходе за пределы данной веб-страницы. Для этого установите на этой веб-странице значение параметра JCWebClient().saveSession в false:

JCWebClient().saveSession = false;

Указанное значение параметра будет действовать только в пределах данной веб-страницы.

В JC-WebClient реализован таймаут в размере 1 минуты, по истечении которого контекст автоматически обнуляется, если приложение определило, что веб-страница перестала отвечать. При этом также удаляется и сеанс работы с токеном. Это произойдёт, например, в следующих случаях:

после закрытии веб-страницы (в том числе средствами DOM и jQuery) или браузера;
после перехода в данной вкладке на любую другую веб-страницу, которая не поддерживает работу с JC-WebClient.

Примечание

Если в текущем сеансе работы с токеном был введён PIN-код и токен находится в состоянии “залогиненности”, то после обнуления контекста состояние “залогиненности” будет недоступно веб-приложению, т.е. PIN-код потребуется вводить заново.

Более детальная информация по работе с JC-WebClient представлена в следующих разделах:

Руководство по работе с SDK

Примеры

Справочник API

Навигация