Общая информация
RutokenKeyBox API — это набор функций, который позволяет управлять устройствами (токенами, смарт-картами) средствами клиентских приложений.
Доступ к этим функциям реализован через веб-приложение icmapi, входящее в состав сервера RutokenKeyBox.
Для взаимодействия с RutokenKeyBox через API необходимо создать сервисную роль и включить в нее учетную запись, от имени которой будет производиться обращение по API, и определить для роли список привилегий:
- Поиск пользователей;
- Просмотр репозитория устройств;
- Отзыв устройства;
- Выключение устройства;
- Включение устройства;
- Обновление устройства.
Запросы
Получить список устройств
Card — получить список устройств, добавленных в систему.
Тип запроса:
GET
Параметры:
- без указания параметров;
- offset — сдвиг на указанное количество устройств;
- count — количество выводимых устройств;
- filter.serialNumber — серийный номер устройства;
- filter.cardTypeName — тип устройств;
- filter.userName — имя пользователя устройства в формате Логин (sAMAccountName) или UPN (userPrincipalName);
- filter.comment — комментарий к устройствам;
- filter.tags — теги устройств;
- filter.state — состояние устройств:
— Clean — пустое;
— Assigned — назначено;
— Pending — в ожидании;
— Issued — выпущено;
— Disabled — выключено;
— Revoked — отозвано; - filter.contentExpirationStatus - статус истечения содержимого устройства:
— None — нет истекающих или истекших сертификатов;
— ManagedCertificatesExpiring — управляемые сертификаты истекают;
— ManagedCertificatesExpired — управляемые сертификаты истекли;
— CommonCertificatesExpiring — общие сертификаты истекают;
— CommonCertificatesExpired — общие сертификаты истекли;
— TracedCertificatesExpiring — отслеживаемые сертификаты истекают;
— TracedCertificatesExpired — отслеживаемые сертификаты истекли.
Возвращаемые значения (список объектов CardInfo):
- id — идентификатор устройства;
- serialNumber — серийный номер устройства;
- cardTypeName — тип устройства;
- cardModelName — модель устройства (доступна только для устройств JaСarta, eToken PRO Java 72K и IDPrime MD, если в разделе Типы устройств для данных карт добавлено разделение по различным моделям);
- atr — Answer To Reset устройства;
- label — метка устройства;
- comment — комментарий к устройству;
- tags — теги устройства;
- state — состояние устройства;
- formFactor — форм-фактор устройства;
- pacNumber — HID-метка устройства;
- expirationDate — срок действия устройства.
Примеры запросов
вывод всех устройств:
http://localhost/icmapi/Cards
вывод 50 устройств без сдвига:
http://localhost/icmapi/Cards?offset=0&count=50
Отозвать устройство
Cards/{id}/Revoke — отозвать устройство пользователя.
Тип запроса:
POST
Параметры:
- id — идентификатор устройства;
reason - причина отзыва устройства:
— 0 — None;
— 1 — CardBroken;
— 2 — CardLost;
— 3 — CardUpgrade;
— 4 — CardExpired;
— 5 — CardWithdraw;
— 6 — UserRemoved;
— 7 — CardCompromised.
Возвращаемые значения: нет.
Пример запроса
http://localhost/icmapi/cards/1/revoke
Отключить устройство на время
Cards/{id}/Disable — отключить устройство пользователя на время.
Тип запроса:
POST
Параметры:
- id — идентификатор устройства.
Возвращаемые значения: нет.
Пример запроса
http://localhost/icmapi/cards/1/disable
Включить устройство
Cards/{id}/Enable — отключить устройство пользователя на время.
Тип запроса:
POST
Параметры:
- id — идентификатор устройства.
Возвращаемые значения: нет.
Пример запроса
http://localhost/icmapi/cards/1/enable
Отозвать неактуальный сертификат пользователя
Cards/{id}/Preupdate — отозвать неактуальный сертификат пользователя.
Метод Preupdate необходим при изменении политики использования устройств. Если выпущенный сертификат не поддерживается в новой политике и включена опция Отзывать сертификат при отзыве/выключении устройства в шаблоне сертификата в старой политике, то он будет отозван.
Метод Preupdate нельзя выполнить для выключенного, назначенного, отозванного и ожидающего выпуск или обновление устройства.
Тип запроса:
POST
Параметры:
- id — идентификатор устройства.
Возвращаемые значения: нет.
Пример запроса
http://localhost/icmapi/cards/1/preupdate