Публичные методы входа и восстановления пароля
Статья для интеграторов и разработчиков клиентских приложений. Она описывает методы REST API v2, которые нужны странице входа: запрос кода восстановления пароля, установка нового пароля по коду, список логинов для подсказки и смена пароля вошедшим пользователем. Полные схемы запросов и ответов находятся в спецификации OpenAPI версии 1.4.9 (см. Подробная документация API).
Какие методы есть
| Метод | Адрес | Вход пользователя | Назначение | operationId |
|---|---|---|---|---|
POST | /v2/password-recovery-code | не нужен | Отправить код подтверждения на почту пользователя | postPasswordRecoveryCode |
POST | /v2/password-recovery-confirm | не нужен | Установить новый пароль по коду из письма | postPasswordRecoveryConfirm |
GET | /v2/login-users | не нужен | Получить список логинов для страницы входа | getLoginUsers |
POST | /v2/password-change | нужен (HTTP Basic) | Сменить пароль текущего пользователя, зная старый | postPasswordChange |
Первые три метода называют публичными: в спецификации у них security: [].
Адреса
Публичные методы вызываются через вторую публикацию информационной базы — отдельную публикацию со служебным пользователем, которую один раз настраивает администратор (см. Публичные методы API (вторая публикация)). Причина в том, что платформа проверяет логин и пароль до начала работы кода 1С, поэтому внутри основной публикации «анонимного» адреса быть не может.
| Что | Базовый адрес |
|---|---|
| Публичные методы (вторая публикация) | <адрес второй публикации>/hs/api_public/v2/ |
| Смена пароля вошедшим пользователем (основная публикация) | <адрес основной публикации>/hs/api/v2/password-change |
Например, при второй публикации it-public запрос кода отправляется на https://server/it-public/hs/api_public/v2/password-recovery-code.
Через вторую публикацию доступны только три публичных маршрута. Любой другой адрес или HTTP-метод, а также любой запрос с параметрами в строке адреса (?...) получает ответ 404 без тела. Например, POST /v2/login-users, GET /v2/password-recovery-code, GET /v2/login-users?limit=1 и GET /v2/login-users/ — это 404.
Те же методы физически присутствуют и в основной публикации (/hs/api/v2/), но там они требуют обычного входа: без пользователя их не вызвать.
Выключатели: что происходит, если метод выключен
Публичные методы выключены по умолчанию. Администратор включает их на странице Личный кабинет по пути Администрирование → Сервис → Настройки параметров учета → Личный кабинет, см. Настройка восстановления пароля в личном кабинете.
| Метод | Флажок | Если выключен | Если включён |
|---|---|---|---|
password-recovery-code | Разрешить восстановление пароля через API | 400, код ВосстановлениеПароля.Отключено; ответ не зависит от логина | 201 {} при любом исходе |
password-recovery-confirm | Разрешить восстановление пароля через API | 400, код ВосстановлениеПароля.Отключено; не зависит от пользователя и кода, возвращается и для JSON {} | 201 {} или ошибка 400 из таблицы ниже |
login-users | Показывать список логинов через API | 200 и пустой массив [] | 200 и массив логинов |
password-change | — | не зависит от флажков | — |
Запрос без тела отклоняется каркасом API с HTTP 400 ещё до проверки флажка. JSON {} считается переданным телом: при выключенном восстановлении такой запрос получает ВосстановлениеПароля.Отключено. Отсутствие тела и отсутствие полей внутри JSON — разные случаи.
Запрос кода восстановления
POST /v2/password-recovery-code
Тело запроса:
| Поле | Тип | Описание |
|---|---|---|
login_or_email | строка | Имя пользователя информационной базы (логин) или адрес электронной почты из карточки пользователя |
curl -X POST "https://server/it-public/hs/api_public/v2/password-recovery-code" \
-H "Content-Type: application/json" \
-d '{"login_or_email": "ivanov"}'
Ответ при включённом методе:
HTTP/1.1 201 Created
{}
Код подтверждения отправляется письмом на адрес электронной почты из карточки пользователя. Код состоит из цифр и латинских букв обоих регистров, регистр при вводе важен.
Ответ нейтрален. Метод всегда отвечает 201 {} и не раскрывает, что произошло на самом деле. Одинаково выглядят:
- успешная отправка письма;
- логин или адрес не найден;
- адрес принадлежит нескольким пользователям;
- пользователь недоступен (недействительный, служебный, без стандартной аутентификации, с запретом изменения пароля) или у него нет адреса электронной почты; при включённой платформенной отправке кода на почту учитывается также запрет восстановления пароля;
- слишком частый повторный запрос;
- активная блокировка после неверных кодов;
- сбой почтовой подсистемы.
Нейтральность распространяется на содержимое ответа, но не на время: для существующего пользователя ответ приходит заметно дольше (программа генерирует код и отправляет письмо). Если ваша интеграция чувствительна к этому, ограничивайте частоту запросов на своей стороне.
Подтверждение восстановления
POST /v2/password-recovery-confirm
Тело запроса:
| Поле | Тип | Описание |
|---|---|---|
login_or_email | строка | Тот же логин или адрес, что был указан при запросе кода |
code | строка | Код подтверждения из письма |
new_password | строка | Новый пароль; должен соответствовать политике паролей программы |
curl -X POST "https://server/it-public/hs/api_public/v2/password-recovery-confirm" \
-H "Content-Type: application/json" \
-d '{"login_or_email": "ivanov", "code": "aB3xK9", "new_password": "..."}'
При успехе ответ 201 и пустой объект {}. Ошибка выглядит так:
{
"code": "ВосстановлениеПароля.НеверныйКод",
"description": "Неверный или устаревший код подтверждения."
}
Как метод отвечает в разных ситуациях:
| Ситуация | Ответ |
|---|---|
| Код верен, пароль принят | 201 {} |
| Пользователь не найден, код не запрашивался, код неверный, прошло более 15 минут, активна блокировка, внутренний сбой | 400, ВосстановлениеПароля.НеверныйКод — одинаковый ответ для всех этих случаев |
| Код верен, но пароль не соответствует политике паролей | 400, ВосстановлениеПароля.ПарольНеСоответствуетТребованиям; в description текст о несоответствии политике |
| Код верен, но новый пароль совпадает с текущим | 400, ВосстановлениеПароля.ПарольСовпадаетСТекущим |
| Код верен, но после выдачи кода пользователю запретили менять пароль | 400, ВосстановлениеПароля.ЗапрещеноИзменятьПароль |
| Код верен, но после выдачи кода пользователь стал недоступен (стал недействительным, служебным, потерял стандартную аутентификацию; либо ему запретили восстановление пароля, если в программе включена отправка кода на почту) | 400, ВосстановлениеПароля.ПользовательНедоступен |
Что важно знать:
- Код одноразовый. Если код был верен, но пароль не подошёл (слабый пароль, совпадение с текущим), код всё равно считается использованным: для следующей попытки запросите новый код. Новый код можно получить не раньше, чем пройдёт минимальный интервал между запросами.
- До совпадения кода любой отказ выглядит одинаково (
НеверныйКод), поэтому по ответам нельзя выяснить, существует ли пользователь и выдавался ли ему код. Остальные коды ошибок возвращаются только тому, кто прислал верный код. - После успешной установки пароля сохранённый токен HTTP Basic со старым паролем перестаёт действовать: клиент должен заново выполнить вход с новым паролем.
Список логинов
GET /v2/login-users
Метод без параметров и без тела. Он нужен странице входа для подсказки в поле логина.
curl "https://server/it-public/hs/api_public/v2/login-users"
Ответ — массив объектов с единственным полем login, отсортированный по логину:
[
{ "login": "ivanov" },
{ "login": "petrov" }
]
Что попадает в список: пользователи, у которых включён флажок Показывать в списке выбора и включена аутентификация 1С:Предприятия, при условии что они не помечены на удаление, не недействительны и не служебные. В ответе нет имён, почты и идентификаторов — только login.
Когда метод возвращает пустой массив [] (клиент не должен их различать и должен предложить ввести логин вручную):
- метод выключен администратором;
- подходящих пользователей нет;
- пользователей ИБ с флажком Показывать в списке выбора и стандартной аутентификацией больше 300: предел проверяется до исключения служебных, недействительных и помеченных на удаление пользователей; список возвращается пустым целиком, без усечения.
Параметры запроса (filter, order, fields, offset, limit и любые другие) метод не поддерживает; во второй публикации запрос с любыми параметрами получает 404. Значение login выводите на странице как текст, а не как HTML-разметку.
Смена пароля вошедшим пользователем
POST /v2/password-change — метод основной публикации (/hs/api/v2/), требует авторизации HTTP Basic. Меняет пароль того пользователя, под которым выполнен запрос.
Тело запроса:
| Поле | Тип | Описание |
|---|---|---|
old_password | строка | Действующий пароль |
new_password | строка | Новый пароль; должен соответствовать политике паролей |
curl -X POST "https://server/itdemo/hs/api/v2/password-change" \
-H "Authorization: Basic <BASIC_TOKEN>" \
-H "Content-Type: application/json" \
-d '{"old_password": "...", "new_password": "..."}'
При успехе — 201 {}. После смены пароля токен со старым паролем перестаёт действовать, клиент обязан получить новый. Метод не зависит от флажков выключателей. <BASIC_TOKEN> — это Base64-кодировка строки логин:пароль.
Коды ошибок
Ошибки 400 возвращаются в виде объекта с полями code (код) и description (описание).
Восстановление пароля
| Код | Когда возвращается | Описание |
|---|---|---|
ВосстановлениеПароля.Отключено | Выключен флажок Разрешить восстановление пароля через API (оба метода восстановления) | Восстановление пароля через API отключено. |
ВосстановлениеПароля.НеверныйКод | Любой отказ подтверждения до совпадения кода | Неверный или устаревший код подтверждения. |
ВосстановлениеПароля.ПарольНеСоответствуетТребованиям | Код верен, пароль не проходит политику паролей | Текст несоответствия политике |
ВосстановлениеПароля.ПарольСовпадаетСТекущим | Код верен, новый пароль совпадает с текущим | Новый пароль совпадает с текущим паролем. |
ВосстановлениеПароля.ЗапрещеноИзменятьПароль | Код верен, у пользователя запрещено изменение пароля | Изменение пароля пользователя запрещено. |
ВосстановлениеПароля.ПользовательНедоступен | Код верен, пользователь недоступен | Пользователь недоступен. |
Смена пароля
| Код | Когда возвращается | Описание |
|---|---|---|
СменаПароля.СтарыйПарольНеверен | Неверно указан old_password | Старый пароль указан неверно. |
СменаПароля.ПарольНеСоответствуетТребованиям | Новый пароль не проходит политику паролей | Текст несоответствия политике |
СменаПароля.СтарыйПарольСовпадаетСНовым | Новый пароль совпадает с текущим | Новый пароль совпадает с текущим паролем. |
СменаПароля.ЗапрещеноИзменятьПароль | У пользователя запрещено изменение пароля | Изменение пароля пользователя запрещено. |
СменаПароля.ПользовательНедоступен | Пользователь недоступен для смены пароля | Пользователь недоступен. |
СменаПароля.ОперацияНеВыполнена | Резервный код при непредвиденном результате | Смена пароля не выполнена. |
Прочие коды ответов
| Код | Значение |
|---|---|
201 | Операция выполнена, тело {} |
200 | Список логинов (возможно, пустой) |
400 | Ошибка клиента: см. таблицы выше или ошибка в теле запроса |
401 | Не авторизован: для password-change — нет или неверен HTTP Basic |
404 | Адрес или HTTP-метод не входит в три публичных маршрута второй публикации либо в адресе есть параметры |
500 | Ошибка сервера; тело содержит поле error |
Лимиты
| Параметр | По умолчанию | Если в платформенной форме «Восстановление паролей» включена отправка кода по почте |
|---|---|---|
| Длина кода | 6 символов | значение формы, если оно от 6 до 50; иначе 6 |
| Минимальный интервал между запросами кода | 180 секунд | значение формы, если оно от 30 до 3600 секунд; иначе 180 |
| Допустимое число неверных попыток подряд | 3 | значение формы, если оно от 1 до 10; иначе 3 |
| Срок действия кода | 15 минут | не настраивается |
| Блокировка после исчерпания попыток | 180 секунд | не настраивается |
Каждое значение формы проверяется отдельно: недопустимое значение заменяется встроенным только для этого параметра. Если отправка кода по почте в форме не включена, действуют значения по умолчанию.
После исчерпания попыток ввод блокируется на 180 секунд. Код при этом не аннулируется: по окончании блокировки можно ввести тот же код, пока не истёк срок его действия. В течение блокировки верный код тоже отвергается ответом НеверныйКод, а новый код не выдаётся (при этом запрос кода по-прежнему отвечает 201 {}).
Рекомендации по реализации клиента
- Не различайте исходы запроса кода. Всегда показывайте одно и то же сообщение, например: «Если такой пользователь существует и у него указана почта, мы отправили на неё код».
- Не отправляйте запросы кода чаще минимального интервала (по умолчанию 180 секунд) и не повторяйте их автоматически.
- Показывайте текст из
descriptionдля ошибок пароля (ПарольНеСоответствуетТребованиям): он содержит конкретное требование политики. - Обрабатывайте пустой список логинов как «ручной ввод логина», не как ошибку.
- Выводите логины как текст, а не как разметку.
- Не сохраняйте и не логируйте пароли и коды подтверждения.
- Используйте HTTPS.
- Ограничьте частоту запросов к
/hs/api_public/*на веб-сервере или обратном прокси: публичные методы вызываются без входа.