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

Назначение и архитектура 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 с аппаратно реализованными российскими и западными криптоалгоритмами. В их числе:

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

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

../../../../_images/webclient1.png

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

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

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

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

  1. Для возможности работы с JC-WebClient через JavaScript API на веб-странице подключите скрипт JCWebClient.js с локального адреса: https://localhost:24738/JCWebClient.js:

    <script type="text/javascript" src="https://localhost:24738/JCWebClient.js"></script>
    
  2. Определите, установлен ли JC-WebClient. Для этого добавьте в код веб-страницы следующий фрагмент:

    if((typeof JCWebClient != 'undefined') && (typeof JCWebClient.id == 'undefined')) {
        // Модуль JC-WebClient установлен, можно работать с его методами
    }
    else {
        // Модуль JC-WebClient не установлен. Необходимо предложить пользователю сделать установку
    }
    
  3. Если 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 уведомит об этом пользователя.
  4. Если JC-WebClient установлен, инициализируйте его работу на веб-странице вызовом метода initialize():

    JCWebClient().initialize();
    

    Метод initialize() помимо прочего инициирует события, которые формирует приложение JC-WebClient и отправляет на веб-страницу. Данные события можно обрабатывать с помощью методов addEventListener() и removeEventListener().

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

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

  1. Для получения массива идентификаторов всех апплетов, поддерживаемых JC-WebClient, на всех подключенных к ПК токенах используйте метод getAllTokens():

    var TokenIDs = JCWebClient().getAllTokens();
    

    Например, если к ПК подключен один токен JaCarta PRO/ГОСТ (на нём 2 поддерживаемых JC-WebClient апплета – PRO и GOST), то метод getAllTokens() вернёт массив из двух идентификаторов: один – для апплета PRO, второй – для апплета GOST.

  2. После получения массива всех идентификаторов выберите апплет, с которым вы хотите продолжать работать. Используйте метод 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;
       }
    }
    
  3. Далее получите информацию о сертификатах, загруженных на токен в данный апплет. Для этого используйте следующие методы:

    1. getCertificateList(), getCertificateListAsync() – получение списка всех идентификаторов сертификатовl;
    2. getCertificateListEx(), getCertificateListExAsync() – получение списка идентификаторов сертификата, выполняющих условия поиска;
    3. readCertificateEx() - чтение сертификата по идентификатору;
    4. parseCertificate(), parseCertificateEx() – вывод полной информации сертификата по идентификатору;
    5. getCertificateInfo(), getCertificateInfoEx() - получение общей информации о сертификате по идентификатору.
  4. Полученную о сертификатах информацию необходимо отфильтровать и

    1. либо выбрать сертификат для работы с системой автоматически на основе известных веб-приложению фильтров и критериев;
    2. либо предоставить пользователю возможность выбрать сертификат из отфильтрованного списка, который он хочет использовать для работы с системой.
  5. После выбора сертификата, необходимо аутентифицироваться в апплете с помощью PIN-кода пользователя. Без аутентификации апплет будет работать в гостевом режиме с ограниченным функционалом: нельзя генерировать ключевые пары, создавать изменять удалять объекты на токене, создавать подпись. Для аутентификации необходимо запросить у пользователя PIN-код пользователя и использовать его в методах bindToken(), bindTokenAsync() или bindTokenUI().

  6. После успешной аутентификации токен переходит в режим пользователя, все пользовательские операции становятся доступными.

  7. Узнать в каком режиме работает токен можно:

    1. с помощью метода getLoggedInState().
    2. с помощью события loginStateChangedEvent().
  8. Методы JC-WebClient возвращают коды ошибок согласно данному списку. Для получения информации об ошибках реализованы методы getLastError() и getErrorMessage().

  9. С дополнительными примерами работы с токеном можно ознакомиться в соответствующем разделе.

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

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

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

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

JCWebClient().saveSession = false;

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

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

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

Примечание

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

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

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

Примеры

Справочник API