ваш код активации ключа в приложении криптопро mydss
Ваш код активации ключа в приложении криптопро mydss
Раздел содержит руководство разработчика по работе с myDSS на Сервисе Управления Пользователями. В разделе приведены основные сценарии использования, примеры HTTP-запросов и ответов REST Сервиса Управления Пользователями.
Так же в разделе приведены рекомендации Администраторам по настройке DSS для реализации различных сценариев работы с myDSS.
Перед началом интеграции с Сервисом Управления Пользователями Администратору DSS необходимо:
Сценарии должны выполняться учётной записью с ролью Оператора DSS.
Аутентификация Операторов DSS на Сервисе Управления Пользователями осуществляется по сертификату (двухстороннее TLS-соединение).
Последовательность шагов по регистрации пользователя:
Регистрация логина пользователя
В качестве идентификатора (логина) пользователя могут выступать:
Внимание!
По умолчанию на DSS в качестве идентификатора разрешён только Логин.
Разрешить/запретить другие идентификаторы пользователя может Администратор DSS выполнив команду в консоли PowerShell:
Примеры запросов
Пример ответа
В ответ DSS вернёт идентификатор созданного пользователя (DssUserId). DssUserId используется при вызове любых методов Сервиса Управления Пользователями:
Вызывающая система может сохранить DssUserId. Это позволит ускорить последующие обращения к Сервису Управления Пользователями, так как не потребуется получать DssUserId повторно.
Типовые ошибки
| HTTP-код | Ошибка | Описание |
|---|---|---|
| 400 | invalid_identifiers | Переданный идентификатор запрещённый на DSS. |
| 400 | invalid_phone | Пользователь с указанным номер телефона уже зарегистирован. |
| 400 | invalid_email | Пользователь с указанным email уже зарегистирован. |
| 400 | invalid_login | Пользователь с указанным логином уже зарегистирован. |
| 500 | An error has occurred | 1. В поле Login указан номер телефона или email. 2. Неверно сформирован email. 3. Неверно сформирован номер телефона. |
Назначение метода первичной аутентификации
После регистрации логина пользователя необходимо назначить метод первичной аутентификации. Пользователю может быть назначен один или несколько методов первичной аутентификации:
| Метод | Описание |
|---|---|
| /user/ | Только идентификация |
| /user/ | Аутентификация по паролю |
| /user/ | Аутентификация по сертификату |
| /user/ | Аутентификация через сторонний Центр Идентификации |
Чаще всего при использовании myDSS в качестве метода первичной аутентификации назначают «Только идентификация».
Внимание!
Назначаемый метод аутентификации должен быть разрешён на DSS. Включить или отключить метод аутентификации должен Администратор на сервере DSS.
Разрешить/запретить метод аутентификации можно на Сервере DSS командами:
Внимание!
Совместное включение методов idonly и password допустимо, но использоваться будет метод «Только идентификация».
Примеры запросов
Назначение метода первичной аутентификации «Только идентификация»
Пример ответа
Назначение метода аутентифиации не имеет возвращаемого значения.
Типовые ошибки
| HTTP-код | Ошибка | Описание |
|---|---|---|
| 400 | wrong_operation | Метод аутентификации уже назначен. |
| 400 | invalid_authn_method | Метод аутентификации запрещён на сервере DSS. |
| 404 | user_not_found | Пользователь не найден. |
Получение QR-кода с ключом аутентификации myDSS
Перед назначением пользователю метода аутентификации myDSS необходимо получить QR-код, содержащий ключ аутентификации пользователя. QR-код должнен быть передан пользователю. Отсканировав QR-код пользователь загрузит ключ аутентификации в мобильное приложение myDSS.
Ключ аутентификации, передаваемый в QR-коде, может быть защищён на коде активации. Код активации передаётся пользователю в SMS или email сообщении.
Требование защиты ключа аутентификации на коде активации настраивается Администратором на сервере DSS и распространяется на всех пользователей.
Изменить длину кода активации может Администратор DSS выполнив команду в консоли PowerShell:
Примечание
Для отправки кода активации в SMS или Email Администратору необходимо подключить и настроить соответствующий модуль оповещения на сервере DSS.
Примеры запросов
В параметре UserContactInfo передаётся адрес электронной почты или номер телефона.
Если используется собственное мобильное приложение на основе PayControl SDK, то ключ аутентификации можно запросить в виде XML. Для получения ключа аутентификации в виде XML в запросе необходимо указать параметр NeedXmlKeyInfo со значением true и код активации KeyInfoPinCode
Пример ответа
Сервер возвращает следующие данные:
Типовые ошибки
| HTTP-код | Ошибка | Описание |
|---|---|---|
| 400 | invalid_contact_info | 1. Требуется предоставить номер телефона или email для отправки кода активации. 2. Указан неверный тип данных для отправки кода активации. |
| 404 | user_not_found | Пользователь не найден. |
| 400 | wrong_operation | Попытка повторно получить QR-код. Для обнолвения ключа пользователя необходимо отправить PATCH запрос. |
| 500 | An error has occurred | 1. Метод аутентификации myDSS запрещен на сервере DSS. 2. Истекла лицензия на myDSS на сервере DSS. |
Назначение myDSS в качестве второго фактора аутентификации
После того как пользователю создан ключ аутентификации необходимо назначить метод аутентификации myDSS.
Пример запроса
Внимание!
Значение параметра level должно быть равно 1
Пример ответа
Метод не имеет возвращаемого значения.
Типовые ошибки
| HTTP-код | Ошибка | Описание |
|---|---|---|
| 400 | invalid_authentication_scheme | Указан неверный уровень метода аутентификации. |
| 404 | user_not_found | Пользователь не найден. |
| 400 | authn_method_not_confirmed | Попытка назначить метод аутентификации не получив QR-код. |
Назначение операций, требующие подтверждения через myDSS
После получения QR-кода и назначения пользователю myDSS необходимо задать список операций требующий подтверждения с помощью myDSS.
Про типы операций, для которых можно настроить подтверждение, и их идентифкаторы можно прочитать на странице Типы Операций. В запросе необходимо перечислить коды операций, которые будет подтверждать пользователь.
Пример запроса
Пример ответа
Метод не имеет возвращаемого значения
Типовые ошибки
| HTTP-код | Ошибка | Описание |
|---|---|---|
| 400 | invalid_authentication_scheme | Указан неверный уровень метода аутентификации. |
| 404 | user_not_found | Пользователь не найден. |
| 400 | wrong_operation | Оператору запрещено изменять список операций, требующих подтверждения. |
Обновление ключа аутентификации пользователя
Ключ аутентификации пользователя имеет ограниченный срок действия. Ключ аутентификации необходимо переодически обновлять. Процедура смены ключа аналогична получению первого ключа аутентификации
Примечание
Флаг DelayedActivation отвечает за режим активации нового ключа пользователя:
Пример запроса
Пример запроса с отложенной активацией ключа
Пример ответа
Типовые ошибки
| HTTP-код | Ошибка | Описание |
|---|---|---|
| 400 | invalid_authentication_scheme | Указан неверный уровень метода аутентификации. |
| 404 | user_not_found | Пользователь не найден. |
| 400 | wrong_operation | Оператора запрещено изменять список операций, требующий подтверждения. |
Повторная отправка кода активации пользователю
Если ключ аутентификации уже назначен пользователю и защищён на коде активации, то можно сделать повторную отправку кода активации ключа.
Требование защиты ключа аутентификации на коде активации настраивается Администратором на сервере DSS и распространяется на всех пользователей.
В параметре UserContactInfo передаётся адрес электронной почты или номер телефона пользователя.
Пример запроса
Метод не имеет возвращаемого значения.
Пример ответа
Типовые ошибки
| HTTP-код | Ошибка | Описание |
|---|---|---|
| 400 | invalid_contact_info | 1. Нет возможности отправить вторую часть ключевой информации: не задана контактная информация пользователя. 2. Неизвестный тип контактной информации: «EmailAddrfess». |
| 400 | wrong_operation | Код активации не требуется в соответствии с настройками сервиса. |
| 404 | user_not_found | Пользователь не найден. |
Поиск пользователя
Сервис Управления пользователями предоставляет несколько возможностей поиска пользователя:
По логину, номеру телефона или email
Пример запроса
Тип ключа поиска может принимать значения (значение параметра type ):
Пример ответа
По логину пользователя во внешнем ЦИ
Пример запроса
Пример ответа
По идентификатору DssUserId
Пример запроса
Пример ответа
Расширенный поиск
Расширенный поиск позволяет применять различные фильтры для поиска пользователей. Результатом выполнения метода может быть группа пользователей, отвечающая параметрам фильтра.
Поиск пользователей можно выполнить по одному или нескольким параметрам:
| Параметр | Код | Описание |
|---|---|---|
| Login | 0 | Логин пользователя |
| PhoneNumber | 1 | Номер телефона |
| 2 | Адрес электронной почты | |
| CreateDate | 3 | Дата создания учётной записи |
| GroupId | 4 | Идентификаторы группы пользователя |
Код параметра указывается в поле Column
Операции сравнения могут быть следующих типов:
| Тип | Код | Описание |
|---|---|---|
| Equal | 0 | Строгое равенство |
| NotEqual | 1 | Не равно |
| Like | 2 | Содержит |
| Greater | 3 | Больше |
| Less | 4 | Меньше |
Код операции указывается в поле Operation
Тип cравнения Like определяет, совпадает ли указанная символьная строка с заданным шаблоном. Шаблон может включать обычные символы и символы-шаблоны. Во время сравнения с шаблоном необходимо, чтобы его обычные символы в точности совпадали с символами, указанными в строке. Символы-шаблоны могут совпадать с произвольными элементами символьной строки.
Поддерживаются следующие символы шаблоны:
| Символ-шаблон | Описание | Пример |
|---|---|---|
| % | Любая строка, содержащая ноль или более символов. | %вано% |
| (подчеркивание) | Любой одиночный символ. | _етров |
| [ ] | Любой одиночный символ, содержащийся в диапазоне ([a-f]) или наборе ([abcdef]). | [Л-С]омов |
| [^] | Любой одиночный символ, не содержащийся в диапазоне ([^a-f]) или наборе ([^abcdef]). | ‘ив[^а]% |
Параметры StartPosition и EndPosition определяют начальную и конечную позицию из итоговой выборки. Данные параметры могут быть использованы для постраничной выборки пользователей
При поиске пользователей по времени создания значение фильтра должно иметь следующий формат: yyyy-MM-ddThh:mm:ss
Вопросы о сервисе
Для вашего удобства мы подготовили ответы на вопросы, которые часто поступают от пользователей сервиса Synerdocs.
Вопрос:
Как привязать сертификат и подписывать документы с помощью приложения “MyDSS”?
Ответ:
Для подписания документов в сервисе обмена Synerdocs с помощью облачной ЭП, необходимо мобильное приложение MyDSS для смартфона под управлением Apple iOS или Google Android. Оно обеспечивает криптографическую аутентификацию пользователей КриптоПроDSS, безопасное взаимодействие, отображение документа и подтверждение операций подписания. Это позволяет соответствовать требованиям к безопасности и использовать квалифицированную электронную подпись для подписания документов по технологии DSS. Ниже содержится порядок установки и использования приложения MyDSS при работе в Synerdocs. Для того чтобы иметь возможность подписывать документы, необходимо следующее:
1. Установка приложения MyDSS.
2. Аутентификация в Synerdocs.
3. Привязка сертификата ЭП к мобильному приложению MyDSS.
После подписания или отказа в подписании документа в Synerdocs необходимо подтвердить
операцию в приложении MyDSS.
1.Установка приложения MyDSS
Для работы приложения необходимо устройство под управлением операционной системы Google Android версии 4.0 и новее или Apple iOS версии 8.0 и новее.
1.1 Установка на iOS
1. На мобильном устройстве откройте приложение APP Store.
2. В строке поиска введите «MyDSS» и нажмите кнопку поиска.
3. В результатах поиска выберите приложение «MyDSS КриптоПро», последовательно нажмите на кнопки Загрузить и Установить.
После завершения установки на экране мобильного устройства появится значок установленного приложения:
1.2 Установка на Android
1. На мобильном устройстве откройте приложение Play Маркет.
2. В строке поиска введите «MyDSS» и нажмите кнопку поиска.
3. В результатах поиска выберите приложение «MyDSS КриптоПро» и нажмите на кнопку Установить. После завершения установки на экране мобильного устройства появится значок установленного приложения:
2. Аутентификация в Synerdocs
1. Откройте браузер и перейдите на сайт веб-клиента. Откроется страница «Аутентификация».
2. На закладке «По паролю» введите логин либо адрес электронной почты и пароль.
3. Нажмите на кнопку Войти.
В результате откроется страница веб-клиента Synerdocs. При первом входе в веб-клиент откроется окно с инструкцией привязки сертификата ЭП по технологии подписания DSS к мобильному приложению MyDSS с помощью QR-кода. Привяжите сертификат к приложению MyDSS.
При необходимости QR-код доступен повторно в профиле пользователя по кнопке Привязать сертификат. После привязки пользователь сможет подписывать и отправлять документы с использованием сертификата облачной ЭП по технологии подписания DSS.
3. Запрос нового QR-кода в личном кабинете
Запрос нового QR-кода может занимать до 5 минут (в это время не рекомендуется обновлять страницу), после чего, SMS-сообщение с новым кодом для привязки приложения может прийти с задержкой до 20 минут, просьба учитывать это при отправке запроса. После отсканировать QR-код с помощью приложения на мобильном телефоне и ввести код из СМС.
4. Привязка сертификата ЭП к мобильному приложению MyDSS
1. На мобильном устройстве запустите приложение MyDSS.
2. Наведите камеру мобильного устройства на QR-код, который был получен при аутентификации в Synerdocs, и нажмите на кнопку Сканировать:
3. Укажите код активации, который был получен по СМС, а затем нажмите на кнопку Продолжить.
4. При необходимости задайте имя ключу авторизации и пароль для доступа к нему.
5. В окне с информацией о том, что ключ сохранен, нажмите на кнопку Закрыть.
В результате в мобильном приложении на вкладке «Управление ключами» появится информация о созданном ключе.
5. Подписание и отказ в подписании документов
Порядок подписания некоторых типов документов аналогичен, поэтому можно выделить группы:
Подробнее о подписании каждого типа документов см. в справке Synerdоcs, раздел «Подписание документов».
Если используется облачный сертификат ООО «Астрал-М» по технологии подписания DSS, то при подписании или отказе в подписании документа в Synerdocs операция подтверждается в мобильном приложении.
6. Подтверждение операций по подписанию/отказа в подписании документа в приложении MyDSS
Если есть операции подписания, требующие подтверждения, в приложении MyDSS отобразится уведомление об этом. Чтобы подтвердить операцию:
1. В уведомлении нажмите на кнопку Подтвердить:
2. Если при активации ключа был задан пароль, укажите его.
3. Ознакомьтесь с информацией о документе, который необходимо подписать и нажмите на кнопку Подтвердить.
4. В уведомлении об успешном подтверждении операции нажмите на кнопку Продолжить.