Назначение и управление аутентификацией по СМС
В данном разделе описывается последовательность действий для назначения метода аутентификации по одноразовым паролям, отправляемых по СМС. Все запросы выполняются от Оператора DSS.
Внимание!
Перед началом работы с Центром Идентификации, должны быть выполнены предварительные настройки сервиса Администратором DSS.
1. Назначение номера мобильного телефона пользователю
В первую очередь требуется задать номер мобильного телефона пользователя, на который будут приходить одноразовые пароли.
1.1. Получение информации о добавленых номерах телефона
Один или несколько номеров мобильного телефона пользователя могли быть уже заданы, например, при регистрации, поэтому первым шагом должно быть получение информации об уже добавленных номерах телефона пользователя.
Запрос на получение информации о номерах телефона пользователя
GET https://host/STS/ums/user/8f4406bf-bd90-4baa-9787-866656907ada/phones HTTP/1.1
Пример ответа
Метод возвращает список добавленных для этого пользователя номеров мобильных телефонов. Для каждого номера телефона указано подтвержден ли он, используется ли для входа (параметр Primary) и прочая информация об использовании данного телефона.
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 187
[{
"Type": "PhoneNumber",
"Contact": "71238889900",
"Confirmed": true,
"Primary": true,
"Notification": true,
"Usages": []
}]
1.2. Добавление нового номера мобильного телефона
Если список номеров мобильного телефона пользователя пуст или среди заданных номеров нет желаемого для вторичной аутентификации номера телефона, то необходимо добавить новый номер мобильного телефона.
Примечание
Номер мобильного телефона можно задавать в любом формате, с пробелами и без.
Запрос на добавление номера телефона
POST https://host/STS/ums/user/8f4406bf-bd90-4baa-9787-866656907ada/phones HTTP/1.1
Content-Type: application/json; charset=utf-8
Content-Length: 14
"+71238889900"
Пример ответа
Метод возвращает информацию о только что добавленном номере мобильного телефона.
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 110
{
"Type": "PhoneNumber",
"Contact": "71238889900",
"Confirmed": true,
"Primary": true,
"Notification": true,
"Usages": []
}
Типовые ошибки
| HTTP-код | Ошибка | Описание |
|---|---|---|
| 404 | user_not_found | Пользователь не найден. |
| 400 | invalid_phone | Переданное значение не является номером телефона. |
1.3. Подтверждение существующего номера телефона
Если пользователь уже имеет требуемый номер мобильного телефона, но этот номер не подтвержден (в полученной информации о номере телефона параметр Confirmed имеет значение false), то этот номер мобильного телефона необходимо подтвердить. В зависимости от настройки Центра Идентификации для подтверждения номера телефона может понадобиться одноразовый пароль, отправленный на подтверждаемый номер телефона.
Запрос на подтверждение без одноразового пароля
POST https://host/STS/ums/user/8f4406bf-bd90-4baa-9787-866656907ada/phones/71238889900/confirm HTTP/1.1
Content-Type: application/json; charset=utf-8
Content-Length: 2
{}
Пример ответа
Метод возвращает информацию о только что подтвержденном номере мобильного телефона.
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 110
{
"Type": "PhoneNumber",
"Contact": "71238889900",
"Confirmed": true,
"Primary": true,
"Notification": true,
"Usages": []
}
Типовые ошибки
| HTTP-код | Ошибка | Описание |
|---|---|---|
| 404 | user_not_found | Пользователь не найден. |
| 400 | invalid_phone | Переданное значение не является номером телефона. |
| 400 | wrong_operation | Неправильный вызов метода, например, номер телефона не добавлен пользователю или добавлен, но уже подтвержден. |
| 400 | contact_confirmation_required | Требуется подтверждение с использованием одноразового пароля из SMS. |
Запрос отправки SMS с одноразовым паролем
Примечание
Если требованиями настроек ЦИ установлено подтверждение номера телефона с использованием одноразового пароля, то сначала необходимо отправить запрос на отпраку SMS с одноразовым паролем для подтверждения, а затем передать этот одноразовый пароль в запросе на подтверждение телефона.
После вызова данного метода на номер телефона пользователя будет отправлено SMS-сообщение с одноразовым паролем.
POST https://host/STS/ums/user/8f4406bf-bd90-4baa-9787-866656907ada/phones/71238889900/requireconfirm HTTP/1.1
Content-Type: application/json; charset=utf-8
Content-Length: 2
{}
Пример ответа
Метод не имеет возвращаемого значения.
HTTP/1.1 200 OK
Типовые ошибки
| HTTP-код | Ошибка | Описание |
|---|---|---|
| 404 | user_not_found | Пользователь не найден. |
| 400 | invalid_phone | Переданное значение не является номером телефона. |
| 400 | wrong_operation | Неправильный вызов метода, например, номер телефона не добавлен пользователю или добавлен, но уже подтвержден. |
Далее следует передать этот одноразовый пароль сервису, для завершения операции подтверждения номера телефона.
Подтверждение номера телефона пользователя с помощью одноразового пароля
POST https://host/STS/ums/user/8f4406bf-bd90-4baa-9787-866656907ada/phones/71238889900/submitconfirm HTTP/1.1
Content-Type: application/json; charset=utf-8
Content-Length: 7
"05643"
Пример ответа
Метод возвращает информацию о только что подтвержденном номере мобильного телефона.
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 110
{
"Type": "PhoneNumber",
"Contact": "71238889900",
"Confirmed": true,
"Primary": true,
"Notification": true,
"Usages": []
}
Типовые ошибки
| HTTP-код | Ошибка | Описание |
|---|---|---|
| 404 | user_not_found | Пользователь не найден. |
| 400 | invalid_phone | Переданное значение не является номером телефона. |
| 400 | wrong_operation | Неправильный вызов метода, например, когда номер телефона не добавлен пользователю или добавлен, но уже подтвержден. |
1.4. Назначение номера телефона в качестве адресата получения одноразовых паролей
Сервису необходимо явно указать, какой именно номер телефона будет использоваться для вторичной аутентификации с помощью одноразовых паролей.
Запрос на назначение номера телефона в качестве адресата получения одноразовых паролей
POST https://host/STS/ums/user/8f4406bf-bd90-4baa-9787-866656907ada/phones/71238889900/secondaryauth HTTP/1.1
Content-Type: application/json; charset=utf-8
Content-Length: 2
{}
Пример ответа
Метод не имеет возвращаемого значения.
HTTP/1.1 200 OK
Типовые ошибки
| HTTP-код | Ошибка | Описание |
|---|---|---|
| 404 | user_not_found | Пользователь не найден. |
| 400 | invalid_phone | Переданное значение не является номером телефона. |
| 400 | wrong_operation | Неправильный вызов метода, например, когда номер телефона не добавлен пользователю. |
| 400 | contact_confirmation_required | Номер телефона пользователя не подтвержден. |
2. Назначение метода аутентификации
POST Назначение метода аутентификации
POST https://host/STS/ums/user/0a0eaf08-665e-452c-a5b0-e342b3c43a3c/authmethod/otpviasms?level=1 HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
Content-Length: 2
{}
Внимание!
Значение параметра level должно быть равно 1
Пример ответа
Метод не имеет возвращаемого значения.
HTTP/1.1 200 OK
Типовые ошибки
| HTTP-код | Ошибка | Описание |
|---|---|---|
| 404 | user_not_found | Пользователь не найден. |
| 400 | invalid_authentication_scheme | Указан неверный уровень метода аутентификации. |
| 400 | wrong_operation | Данный метод аутентификации уже назначен пользователю. |
| 400 | authn_method_not_confirmed | Попытка назначить метод аутентификации без указания подтвержденного номера мобильного телефона. |
3. Назначение операций, требующих подтверждения по СМС
После сохранения номера мобильного телефона пользователя и подключения метода вторичной аутентифкации по СМС необходимо задать список операций, требующих подтверждения.
Про типы операций, для которых можно настроить подтверждение по СМС, и их коды можно прочитать на странице Типы Операций.
В запросе необходимо перечислить коды операций, которые будет подтверждать пользователь.
POST назначение политик подтверждения операций пользователю
POST https://host/STS/ums/user/0a0eaf08-665e-452c-a5b0-e342b3c43a3c/operationpolicy HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
Content-Length: 5
[2, 16, 1024]
Пример ответа
Метод не имеет возвращаемого значения.
HTTP/1.1 200 OK
Типовые ошибки
| HTTP-код | Ошибка | Описание |
|---|---|---|
| 400 | wrong_operation | Оператору запрещено изменять список операций, требующих подтверждения. |
| 404 | user_not_found | Пользователь не найден. |
4. Отключение метода аутентификации и удаление номера мобильного телефона пользователя
Если у пользователя заданы политики подтверждения операций с помощью данного метода, то сначала нужно назначить другой метод для подтверждения операций или отключить подтверждение опреаций совсем. После этого можно отключить метод аутентифкации, а затем удалить номер мобильного телефона пользователя.
DELETE Удаление метода аутентификации по одноразовым паролям, отправленным в СМС
DELETE https://host/STS/ums/user/0a0eaf08-665e-452c-a5b0-e342b3c43a3c/authmethod/otpviasms HTTP/1.1
Пример ответа
Метод не имеет возвращаемого значения.
HTTP/1.1 200 OK
Если номер мобильного телефона не задан или не подтвержден, нужно добавить его. Поскольку запрос выполняется от Оператора DSS, указанный в запросе номер считается подтвержденным.
DELETE Удаление номера мобильного телефона пользоватлеля
DELETE https://host/STS/ums/user/0a0eaf08-665e-452c-a5b0-e342b3c43a3c/phones/71238889900 HTTP/1.1
Пример ответа
Метод не имеет возвращаемого значения.
HTTP/1.1 200 OK
Типовые ошибки
| HTTP-код | Ошибка | Описание |
|---|---|---|
| 400 | invalid_authentication_scheme | Указан неверный уровень метода аутентификации. |
| 404 | user_not_found | Пользователь не найден. |
| 400 | authn_method_not_confirmed | Попытка назначить метод аутентификации без указания номера мобильного телефона. |
5. Обратная совместимость с версией 2.0.3
В целях обратной совместимость с версией DSS 2.0.3 поддерживаются методы комплексного задания номера телефона и получение информации о заданном номере телефона пользователя.
Данный метод позволяет получить информацию о заданном номере мобильного телефона пользователя.
Получение информации о номере телефона пользователя
GET https://host/STS/ums/user/0a0eaf08-665e-452c-a5b0-e342b3c43a3c/phonenumber HTTP/1.1
Пример ответа
Метод возвращает номер мобильного телефона пользователя и значение, показывающее является ли номер телефона подтвержденным.
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 47
{"PhoneNumber":"79150000001","Confirmed":true}
Изменение номера телефона пользователю
Данный метод объединяет функции добавления номера телефона (если такой номер не был добавлен), назначения его в качестве логина и в качестве адресата для отправки оповещений и одноразовых паролей для вторичной аутентификации.
Примечание
Номер мобильного телефона можно задавать в любом формате без пробелов.
POST https://host/STS/ums/user/0a0eaf08-665e-452c-a5b0-e342b3c43a3c/phonenumber HTTP/1.1
Content-Type: application/json; charset=utf-8
Content-Length: 14
"+79150455647"
Пример ответа
Метод не имеет возвращаемого значения.
HTTP/1.1 200 OK
Типовые ошибки
| HTTP-код | Ошибка | Описание |
|---|---|---|
| 400 | invalid_authentication_scheme | Указан неверный уровень метода аутентификации. |
| 404 | user_not_found | Пользователь не найден. |
| 400 | authn_method_not_confirmed | Попытка назначить метод аутентификации без указания номера мобильного телефона. |
Поиск пользователя
Сервис Управления пользователями предоставляет несколько возможностей поиска пользователя:
- По логину, номеру телефона или email
- По логину пользователя во внешнем ЦИ
- По идентификатору DssUserId
- Расширенный поиск
По логину, номеру телефона или email
Пример запроса
Тип ключа поиска может принимать значения (значение параметра type):
- Login
- PhoneNumber
GET https://host/STS/ums/user?type=Login&value=DssTest-dc3bf3f5 HTTP/1.1
Accept: application/json
Host: host
Пример ответа
HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Type: application/json; charset=utf-8
Expires: -1
Content-Length: 334
{"UserId":"d1831dea-985f-4df1-a54b-2497eeace2f2","Login":"DssTest-dc3bf3f5","PhoneNumber":null,"Email":null,"PhoneConfirmed":false,"EmailConfirmed":false,"DisplayName":null,"DistinguishName":"","AccountLocked":false,"Group":"Default","CreationDate":"2018-08-24T14:36:33.02","LockoutDate":null,"LastLoginDate":"2018-08-24T14:36:33.02"}
По логину пользователя во внешнем ЦИ
Сервис управления Пользователями предоставляет возможность поиска Пользователей в DSS по внешнему логину. В данном
случае в запросе необходимо указать имя внешнего ЦИ, под которым он зарегистрирован в ЦИ КриптоПро DSS. Получить имя
внешнего ЦИ можно в выводе командлета Get-DssIdentityProvider. Имя
ЦИ соответствует информации, выведенной в поле IssuerName.
Пример запроса
GET https://host/STS/ums/user?type=Login&value=DssTest-dc3bf3f5&issuerName=ADFS HTTP/1.1
Accept: application/json
Host: host
Пример ответа
HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Type: application/json; charset=utf-8
Expires: -1
Content-Length: 334
{"UserId":"d1831dea-985f-4df1-a54b-2497eeace2f2","Login":"DssTest-dc3bf3f5","PhoneNumber":null,"Email":null,"PhoneConfirmed":false,"EmailConfirmed":false,"DisplayName":null,"DistinguishName":"","AccountLocked":false,"Group":"Default","CreationDate":"2018-08-24T14:36:33.02","LockoutDate":null,"LastLoginDate":"2018-08-24T14:36:33.02"}
По идентификатору DssUserId
Пример запроса
GET https://host/STS/ums/user/d1831dea-985f-4df1-a54b-2497eeace2f2 HTTP/1.1
Accept: application/json
Host: host
Пример ответа
HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Type: application/json; charset=utf-8
Expires: -1
Content-Length: 334
{"UserId":"d1831dea-985f-4df1-a54b-2497eeace2f2","Login":"DssTest-dc3bf3f5","PhoneNumber":null,"Email":null,"PhoneConfirmed":false,"EmailConfirmed":false,"DisplayName":null,"DistinguishName":"","AccountLocked":false,"Group":"Default","CreationDate":"2018-08-24T14:36:33.02","LockoutDate":null,"LastLoginDate":"2018-08-24T14:36:33.02"}
Расширенный поиск
Расширенный поиск позволяет применять различные фильтры для поиска пользователей. Результатом выполнения метода может быть группа пользователей, отвечающая параметрам фильтра.
Поиск пользователей можно выполнить по одному или нескольким параметрам:
| Параметр | Код | Описание |
|---|---|---|
| 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
Общее количество элементов подпадающих под критерии фильтра возвращается в параметре TotalCount.
Количество элементов отданных методом возвращается в параметре AffectedCount:
AffectedCount <= EndPosition - StartPosition
Примеры запросов
Получить пользователя с заданным логином:
POST https://host/STS/ums/users HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
Host: host
Content-Length: 101
Expect: 100-continue
{"StartPosition":1,"EndPosition":1,"Filters":[{"Column":0,"Operation":0,"Value":"DssTest-dc3bf3f5"}]}
Проверка были ли создан пользователь с заданным логином в указанным промежуток времени:
POST https://host/STS/ums/users HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
Host: host
Content-Length: 172
Expect: 100-continue
{"StartPosition":1,"EndPosition":1,"Filters":[{"Column":0,"Operation":0,"Value":"DssTest-2fa204c5"},{"Column":3,"Operation":3,"Value":"2018-08-24T15:12:12.4683672+03:00"}]}
Получить пользователей созданных в указанный промежуток времени:
POST https://host/STS/ums/users HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
Host: host
Content-Length: 161
Expect: 100-continue
{"StartPosition":1,"EndPosition":10,"Filters":[{"Column":3,"Operation":4,"Value":"2018-08-25T04:24:50"},{"Column":3,"Operation":3,"Value":"2018-08-23T04:24:50"}]}
Пример ответа
HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Type: application/json; charset=utf-8
Expires: -1
Content-Length: 386
{"UserInfos":[{"UserId":"d1831dea-985f-4df1-a54b-2497eeace2f2","Login":"DssTest-dc3bf3f5","PhoneNumber":null,"Email":null,"PhoneConfirmed":false,"EmailConfirmed":false,"DisplayName":null,"DistinguishName":"","AccountLocked":false,"Group":"Default","CreationDate":"2018-08-24T14:36:33.02","LockoutDate":null,"LastLoginDate":"2018-08-24T14:36:33.02"}],"TotalCount":2047,"AffectedCount":1}
Типовые ошибки
| HTTP-код | Ошибка | Описание |
|---|---|---|
| 404 | user_not_found | Пользователь не найден. |
| 500 | An error has occurred | Неверно указано значение или тип фильтра. |