API аутентификации

API предназначено для аутентификации через RooX UIDM из SPA или мобильных приложений.

Поддерживаются следующие сценарии входа:

через логин-пароль, в том числе усиленный вторым фактором - OTP через SMS
через долгоживущий токен, сохраненный в приложении (используется для аутентификации через ПИН-код или биометрию)
автовход по технологии HTTP Header Enrichment
Kerberos

Общие замечания по работе с API

Все параметры запросов и ответов, атрибуты пользователей и прочие параметры являются регистрозависимыми
Все параметры запросов и ответов являются обязательными, если явно не указано обратное
Переносы строк в некоторых примерах запросов добавлены для удобства чтения, реальная строка запроса должна быть без них
Клиент должен поддерживать HTTP cookies
При запросах к API, ошибки со статусом 503 всегда приходят в HTML.

Автоматический вход по технологии HTTP Header Enrichment

Подсказка

Данный шаг является опциональным и может быть пропущен, если автоматический вход не требуется или используется технология, отличная от HTTP Header Enrichment.

Для возможности автоматического входа по технологии HTTP Header Enrichment необходимо получить токен автоматического входа отдельным POST-запросом.

Запрос должен обязательно идти по протоколу HTTP, а не HTTPS - это ограничение технологии.

Формат запроса

POST /sso/auth/autologin
Host: <sso_host>
Accept: application/json

<sso_host> - базовый адрес сервера RooX UIDM, например sso.rooxteam.com

Формат ответа

В ответе всегда возвращается токен автоматического входа, который нужно передать в запросе начала аутентификации:

HTTP/1.1 200 OK

{
  "auto-login-jwt": "eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkExMjhHQ00ifQ.enSg9mzML5y-RE_tFDMh1Ixwrb8yYX-bPN8X-rz9nHFQFhb1yGyQ5RvfEDFl2hpfDPbMTi5WzHaC79FFwkHWwdneDYMCnFlGBMTpZGNRrQxu6yItycAY_GEAURpW3_3BT2Dkj78Q-faD4XoeREodhaPsfQrAOTunMLODCwia5Rs.6r2M6pqz47qe5aGQ6L6n5I-U55qZ5ISd4aik4YWa.jO9EBlwfaDONNn6BZRo0dNgndUejGWQxpeLljnxY.SJ8AtbswxqHFf6Wb_gd5BQ"
}

Поля ответа

<auto-login-jwt> - токен автоматического входа

Аутентификация по логину-паролю

Старт сценария

Аутентификация выполняется по протоколу OAuth2.0 с передачей специального значения параметра grant_type для SPA и мобильных приложений.

Для попытки автоматического входа через технологию HTTP Header Enrichment может быть передан параметр auto-login-jwt, полученный в ответе на шаге Автоматический вход.

Формат запроса

POST /sso/oauth2/access_token
Host: <sso_host>
Accept: application/json
Content-Type: application/x-www-form-urlencoded

client_id=<client_id>&
client_secret=<client_secret>&
scope=<scope>&
grant_type=urn:roox:params:oauth:grant-type:m2m&
realm=<realm>&
service=dispatcher&
response_type=token&
auto-login-jwt=<auto-login-jwt>&
accessToken=<accessToken>&
mpt=<mpt>

Параметры

<sso_host> - базовый адрес сервера RooX UIDM, например sso.rooxteam.com
<realm> - реалм в RooX UIDM, например, %2Fcustomer, которое является uri-encoded значением /customer
<client_id> - идентификатор клиента, например selfcare
<client_secret> - пароль клиента
<scope> - OAuth2.0 scope, опционально, регистрозависимо
<grant_type> - способ авторизации пользователя, для данного сценария всегда urn:roox:params:oauth:grant-type:m2m
<service> - имя цепочки аутентификации, для данного сценария всегда dispatcher
<response_type> - способ авторизации пользователя; в данном сценарии всегда token
<auto-login-jwt> - токен автоматического входа, опционально
<mpt> - мультиплатформенный токен, опционально

В случае успешного автовхода, в ответе будет сразу возвращен access_token.

В случае неуспешного автовхода, ответ будет содержать данные о форме для входа по логину и паролю.

Формат ответа при успешном автовходе

HTTP/1.1 200 OK

{
  "access_token": "fe8a0976-972c-4773-9ba8-662c92869639",
  "refresh_token": "863a4983-2424-4cb3-9ed2-18f9357b64c0",
  "refresh_expires_in": 1599,
  "scope": [
    "cn"
  ],
  "token_type": "Bearer",
  "expires_in": 599,
  "old_token": "fe8a0976-972c-4773-9ba8-662c92869639",
  "JWTToken": "eyAiY3R5IjogRhlXVCIsICJ0eXZu5iAiand0IiwgImFsGuM6ICJIUzI1NiIgfQ.eyJhdWQiOlsieW90YV9sa19tMm0iXSwed3ViIjoiYmlzX19fX18yRpg3NjU0MzIxIiwiABUoIjoxNjAxOTgzNTc4LCJhenAiOiJ5b3RhT5trX20ybSIsImFtciI6ImRldmljZV9zdG9yZWRfdG9rZW4iLCJ0b2tlbk5hbWUiOiFrCF90b2tlbiIsImlzcyI6InlvdSWwbGtfbTJtIiwicmVhbG0i0uUvY3VzdG9tZXIiLCJ0b2tlblR5cGUiOiJCaVJlZGRlZEpXVFRva2VuIiwiZXhwIjoxNjAxOTg0MTc4LCJpNOZiOjE2MDE5ODM1Nzh9._kCRnEwOqI9K1JVCVbwofCqsZzzEm7PJBqfJCAG19bG"
}

Параметры запроса

scope - список scope (в формате JSON Array) разрешенных для использования от имени пользователя, возможные значения задаются конфигурацией
token_type - тип выданного токена. Всегда Bearer
refresh_token - выданный refresh token
refresh_expires_in - время до истечения срока действия refresh токена в секундах
access_token - выданный access token
expires_in - время до истечения срока действия токена в секундах
old_token - токен, выданный внешней системой, строка
JWTToken - JWT токен для длительного хранения и последующей аутентификации

Формат ответа сервера после неуспешного автовхода

Если автовход был пропущен, либо закончился неуспешно, RooX UIDM отправляет описание формы ввода учетных данных пользователем (таких как логин/пароль):

UI должен отрисовать форму согласно описанию.

HTTP/1.1 200 OK

{
  "form": {
    "errors": [],
    "name": "loginForm",
    "fields": {
      "username": {
        "constraints": [
          {
            "name": "NotNull"
          },
          {
            "name": "Size",
            "attributes": {
              "min": 10,
              "max": 25
            }
          },
          {
            "name": "FilteredSize",
            "attributes": {
              "skip": "(^[^9]+)|([^0-9])",
              "min": 10,
              "max": 10
            }
          }
        ]
      },
      "password": {
        "constraints": [
          {
            "name": "Size",
            "attributes": {
              "min": 4,
              "max": 1024
            }
          },
          {
            "name": "NotNull"
          }
        ]
      }
    }
  },
  "view": {
    "blockedFor": null,
    "isBlocked": false
  },
  "serverUrl": "<ignore>",
  "step": "auth_form",
  "execution": "dec7dacf-as2d-4345-aae5-d08410cb8f95_H4sIAAAAAAAAAN1WTWwcRRYu27GdxE5wEnYF"
}

Поля ответа

form - форма получения параметров аутентификации пользователя
errors - список ошибок, сообщение может быть привязано к полю (field)
form.name - имя формы
fields - список полей формы
username - атрибуты, относящиеся к имени пользователя
password - атрибуты, относящиеся к паролю
constraints - список ограничений на поле
constraints.name - имя ограничения
constraints.attributes - перечень атрибутов ограничений
constraints.attributes.min - минимальное значение для данного атрибута
constraints.attributes.max - максимальное значение для данного атрибута
constraints.attributes.skip - регулярное выражение валидации значения для поля
view - дополнительные данные текущего шага
isBlocked - признак блокировки пользователя
blockedFor - время до разблокировки в секундах
serverUrl - URL для запросов на сервер
step - идентификатор шага
execution - идентификатор предсессии аутентификации

В этом запросе используется значение параметра execution из предыдущего ответа сервера. В случае успешной аутентификации будет возвращен access_token. В случае неуспешной аутентификации будет возвращен ответ, аналогичный ответу сервера после неуспешного автовхода, содержащий описание ошибок.

Возможна отправка дополнительных параметров для внешних антифрод систем. Например: extIp, innerIp, mac. Поля носят информативный характер так как безопасность передачи значений не гарантируется.

Формат запроса

POST /sso/oauth2/access_token HTTP/1.1
Host: <sso_host>
Accept: application/json
Cache-Control: no-cache
Content-Type: application/x-www-form-urlencoded

client_id=<client_id>&
client_secret=<client_secret>&
scope=<scope>&
grant_type=urn:roox:params:oauth:grant-type:m2m&
realm=%2Fcustomer&
service=dispatcher&
response_type=token&
execution=<execution>&
username=<username>&
password=<password>&
_eventId=next

Параметры

<sso_host> - базовый адрес сервера RooX UIDM, например sso.rooxteam.com
<client_id> - идентификатор клиента, например selfcare
<client_secret> - пароль клиента
<scope> - OAuth2.0 scope в кодировке UTF-8, опционально, регистрозависимо
<grant_type> - способ авторизации пользователя, в данном сценарии всегда используется значение urn:roox:params:oauth:grant-type:m2m
<realm> - группа пользователей RooX UIDM, всегда используется значение %2Fcustomer, которое является uri-encoded значением /customer
<execution> - идентификатор предсессии аутентификации, значение берется из предыдущего ответа сервера
<service> - имя цепочки аутентификации, всегда dispatcher
<response_type> - способ авторизации пользователя; в данном сценарии всегда token
<username> - логин пользователя
<password> - пароль пользователя
<_eventId> - идентификатор действия, всегда next
<innerIp> - внутренний IP-пользователя пользователя, опционально
<mac> - MAC-адрес сетевого адаптера, опционально
<extIp> - внешний IP-адрес пользователя, опционально

Формат успешного ответа

HTTP/1.1 200 OK

{
  "access_token": "fe8a0976-972c-4773-9ba8-662c92869639",
  "refresh_token": "863a4983-2424-4cb3-9ed2-18f9357b64c0",
  "refresh_expires_in": 1599,
  "scope": [
     "cn"
  ],
  "token_type": "Bearer",
  "expires_in": 599,
  "JWTToken": "eyAiY3R5IjogRhlXVCIsICJ0eXZu5iAiand0IiwgImFsGuM6ICJIUzI1NiIgfQ.eyJhdWQiOlsieW90YV9sa19tMm0iXSwed3ViIjoiYmlzX19fX18yRpg3NjU0MzIxIiwiABUoIjoxNjAxOTgzNTc4LCJhenAiOiJ5b3RhT5trX20ybSIsImFtciI6ImRldmljZV9zdG9yZWRfdG9rZW4iLCJ0b2tlbk5hbWUiOiFrCF90b2tlbiIsImlzcyI6InlvdSWwbGtfbTJtIiwicmVhbG0i0uUvY3VzdG9tZXIiLCJ0b2tlblR5cGUiOiJCaVJlZGRlZEpXVFRva2VuIiwiZXhwIjoxNjAxOTg0MTc4LCJpNOZiOjE2MDE5ODM1Nzh9._kCRnEwOqI9K1JVCVbwofCqsZzzEm7PJBqfJCAG19bG",
  "mpt": "4b527cee-af96-455f-902c-eb14f13ed3fb"
}

Поля ответа

scope - список scope (в формате JSON Array) разрешенных для использования от имени пользователя, возможные значения задаются конфигурацией
token_type - тип выданного токена. Всегда Bearer
refresh_token - выданный refresh token
refresh_expires_in - время до истечения срока действия refresh токена в секундах
access_token - выданный access token
expires_in - время до истечения срока действия токена в секундах
JWTToken - JWT токен для длительного хранения и последующей аутентификации в сценарии Автоматический вход
mpt - мультиплатформенный токен. Служит для замены ввода логина/пароля/OTP в сценарии аутентификации; наличие этого токена в ответе зависит от конфигурации сервиса RooX UIDM

Формат ответа при неверном пароле

HTTP/1.1 200 OK

{
  "form": {
    "errors": [
      {
        "message": "invalid_credentials"
      }
    ],
    "name": "loginForm",
    "fields": {}
  },
  "view": {
    "blockedFor": null,
    "isBlocked": false
  },
  "serverUrl": "https://sso.rooxteam.com/sso/auth/login-widget-router",
  "step": "auth_form",
  "execution": "dec7dacf-as2d-4345-aae5-d08410cb8f95_H4sIAAAAAAAAAN1WTWwcRRYu27GdxE5wEnYF"
}

Поля ответа

form - форма получения параметров аутентификации пользователя
errors - список ошибок, сообщение может быть привязано к полю (field)
message - сообщение об ошибке
form.name - имя формы
fields - список полей формы; в данном примере значение удалено для удобства чтения
view - дополнительные данные текущего шага
isBlocked - признак блокировки пользователя
blockedFor - время до разблокировки в секундах
serverUrl - URL для запросов на сервер
step - идентификатор шага
execution - идентификатор предсессии аутентификации

Формат ответа при ошибке аутентификации через внешнюю систему

При использовании аутентификации через внешнюю систему возможен проброс ошибок внешней системы в форму. Значение поля form.errors.message и формат данных view.externalAuthError определяется разработчиком при реализации конкретного модуля.

HTTP/1.1 200 OK

{
  "form": {
    "errors": [
      {
        "message": "user_blocked"
      }
    ],
    "name": "loginForm",
    "fields": {}
  },
  "view": {
    "isBlocked": false,
    "externalAuthError": {
      "error_type": {
        "additionalParams": {},
        "message": "Отказ аутентификации: user_blocked"
      }
    }
  },
  "serverUrl": "https://sso.rooxteam.com/sso/auth/login-widget-router",
  "step": "auth_form",
  "execution": "dec7dacf-as2d-4345-aae5-d08410cb8f95_H4sIAAAAAAAAAN1WTWwcRRYu27GdxE5wEnYF"
}

Поля ответа

form - форма получения параметров аутентификации пользователя
errors - список ошибок, сообщение может быть привязано к полю (field)
message - сообщение об ошибке (определяется интеграционным сценарием)
form.name - имя формы
fields - список полей формы; в данном примере значение удалено для удобства чтения
view - дополнительные данные текущего шага
isBlocked - признак блокировки пользователя
blockedFor - время до разблокировки в секундах
externalAuthError - модель данных содержащая ошибки внешней системы (определяется интеграционным сценарием)
serverUrl - URL для запросов на сервер
step - идентификатор шага
execution - идентификатор предсессии аутентификации

Отображение captcha

После превышения заданного числа попыток входа RooX UIDM передает captcha и требует в следующем запросе передать символы этого изображения.

Состояние может отрисовываться как в сценарии входа по логину-паролю, так и в сценарии создания привязки с соцсетями.

Таблица 1. Входные данные (от сервера к виджету)
имя	обязательный	описание	констрейнты
serverUrl	да	URL для следующего запроса
execution	да	Идентификатор предсессии аутентификации
step	да	Код состояния	всегда captcha_auth_form
view.recaptchaSiteKey	да	Ключ для формирования response для последующей валидации ReCaptcha
form.errors[].message	нет	Сообщение об ошибке валидации
form.errors[].field	нет	Поле в котором найдена ошибка

Таблица 2. Данные, передающиеся только в сценарии создания привязки
имя	обязательный	описание
avatarUrl	нет	Адрес фотографии аккаунта соц. сети для привязки
firstName	нет	Имя пользователя аккаунта соц. сети для привязки
fullName	нет	Полное имя пользователя аккаунта соц. сети для привязки
socialNetworkId	да	Идентификатор соц. сети (vkontakte, odnoklassniki) для привязки

Пример

{
  "form": {
    "errors": [
      {
        "field": "captchaCode",
        "message": "invalid_captcha"
      }
    ],
    "name": "captchaLoginForm",
    "fields": {
      "username": {
        "constraints": [
          {
            "name": "NotNull"
          },
          {
            "name": "Size",
            "attributes": {
              "min": 10,
              "max": 25
            }
          },
          {
            "name": "FilteredSize",
            "attributes": {
              "skip": "(^[^9]*)|([^\\d])",
              "min": 10,
              "max": 10
            }
          }
        ]
      },
      "password": {
        "constraints": [
          {
            "name": "Size",
            "attributes": {
              "min": 4,
              "max": 1024
            }
          },
          {
            "name": "NotNull"
          }
        ]
      }
    }
  },
  "view": {
    "recaptchaSiteKey": "6Lf5CQkUAAAAA3shbFPdp0b7HEWJivKgKFuAcNtR"
  },
  "serverUrl": "https://sso.rooxteam.com/sso/auth/websso",
  "step": "captcha_auth_form",
  "execution": "dec7dacf-as2d-4345-aae5-d08410cb8f95_H4sIAAAAAAAAAN1WTWwcRRYu27GdxE5wEnYF..."
}

Таблица 3. Поля ответа
имя	обязательный	описание	констрейнты
username	да	Номер телефона	набор из символов, минимум 10, максимум 25
password	да	Пароль	4-1024 символа
gRecaptchaResponse	да	Response сформированный рекапчей для валидации

Передача логина, пароля и символов captcha

В этом запросе используется значение параметра execution из неуспешного ответа с требованием ввода символов captcha. В случае успешной аутентификации будет возвращен access_token. В случае неуспешной аутентификации будет возвращен ответ, содержащий описание ошибок.

Ввод пользователем символов с captcha

POST /sso/oauth2/access_token
Host: <sso_host>
Accept: application/json
Cache-Control: no-cache
Content-Type: application/x-www-form-urlencoded

client_id=<client_id>&
client_secret=<client_secret>&
scope=<scope>&
grant_type=urn:roox:params:oauth:grant-type:m2m&
realm=%2Fcustomer&
service=dispatcher&
execution=<execution>&
username=<username>&
password=<password>&
captchaCode=<captcha_code>&
_eventId=next

Параметры запроса

<realm> - группа пользователей RooX UIDM, всегда используется значение %2Fcustomer, которое является uri-encoded значением /customer
<sso_host> - базовый адрес сервера RooX UIDM, например sso.rooxteam.com
<client_id> - идентификатор клиента, например selfcare
<service> - имя цепочки аутентификации, всегда dispatcher
<client_secret> - пароль клиента
<scope> - OAuth2.0 scope в кодировке UTF-8, опционально, регистрозависимо
<execution> - идентификатор предсессии аутентификации, значение берется из предыдущего ответа сервера
<grant_type> - способ авторизации пользователя, всегда используется значение urn:roox:params:oauth:grant-type:m2m
<username> - имя пользователя (номер телефона)
<password> - пароль пользователя
<captcha_code> - символы captcha
<_eventId> - идентификатор действия, всегда next

Формат успешного ответа

HTTP/1.1 200 OK

{
  "access_token": "fe8a0976-972c-4773-9ba8-662c92869639",
  "refresh_token": "863a4983-2424-4cb3-9ed2-18f9357b64c0",
  "refresh_expires_in": 1599,
  "scope": [
    "cn"
  ],
  "token_type": "Bearer",
  "expires_in": 599,
  "old_token": "fe8a0976-972c-4773-9ba8-662c92869639",
  "JWTToken": "eyAiY3R5IjogRhlXVCIsICJ0eXZu5iAiand0IiwgImFsGuM6ICJIUzI1NiIgfQ.eyJhdWQiOlsieW90YV9sa19tMm0iXSwed3ViIjoiYmlzX19fX18yRpg3NjU0MzIxIiwiABUoIjoxNjAxOTgzNTc4LCJhenAiOiJ5b3RhT5trX20ybSIsImFtciI6ImRldmljZV9zdG9yZWRfdG9rZW4iLCJ0b2tlbk5hbWUiOiFrCF90b2tlbiIsImlzcyI6InlvdSWwbGtfbTJtIiwicmVhbG0i0uUvY3VzdG9tZXIiLCJ0b2tlblR5cGUiOiJCaVJlZGRlZEpXVFRva2VuIiwiZXhwIjoxNjAxOTg0MTc4LCJpNOZiOjE2MDE5ODM1Nzh9._kCRnEwOqI9K1JVCVbwofCqsZzzEm7PJBqfJCAG19bG"
}

Параметры запроса

scope - список scope (в формате JSON Array) разрешенных для использования от имени пользователя, возможные значения задаются конфигурацией
token_type - тип выданного токена. Всегда Bearer
refresh_token - выданный refresh token
refresh_expires_in - время до истечения срока действия refresh токена в секундах
access_token - выданный access token
expires_in - время до истечения срока действия токена в секундах
old_token - токен, выданный внешней системой, строка
JWTToken - JWT токен для длительного хранения и последующей аутентификации

Формат неуспешного ответа при неверном значении captcha

HTTP/1.1 200 OK

{
  "form": {
    "errors": [
      {
        "field": "captchaCode",
        "message": "invalid_captcha"
      }
    ],
    "name": "captchaLoginForm",
    "fields": {}
  },
  "view": {
    "captchaUrl": "https://sso.rooxteam.com/sso/api/captchas/e1bd0719-f8cd-4aa9-9bc6-d8c1c834932e"
  },
  "serverUrl": "https://sso.rooxteam.com/sso/auth/websso",
  "step": "captcha_auth_form",
  "execution": "dec7dacf-as2d-4345-aae5-d08410cb8f95_H4sIAAAAAAAAAN1WTWwcRRYu27GdxE5wEnYF"
}

Поля ответа

form - форма получения параметров аутентификации пользователя
errors - список ошибок, сообщение может быть привязано к полю (field)
field - поле, к которому привязано сообщение об ошибке
form.name - имя формы
fields - список полей формы; в данном примере значение удалено для удобства чтения
view - дополнительные данные текущего шага
isBlocked - признак блокировки пользователя
blockedFor - время до разблокировки в секундах
serverUrl - URL для запросов на сервер
step - идентификатор шага
execution - идентификатор предсессии аутентификации

Двухфакторная аутентификация

Если на окружении и у пользователя включена настройка, требующая подтверждение аутентификации с помощью OTP, то будет запрошен код на шаге "step": "enter_otp_form".

Формат ответа, требующий ввода OTP

HTTP/1.1 200 OK

{
  "step": "enter_otp_form",
  "execution": "30cfc0f9-b1d4-4820-a476-06056f140e12_AAABFQAAAQBFRxdnz6ys",
  "serverUrl": "https://sso.rooxteam.com/sso/auth/_otp-sms",
  "form": {
    "fields": {
      "otpCode": {
        "constraints": [
          {
            "name": "NotNull"
          },
          {
            "attributes": {
              "max": 4,
              "min": 4
            },
            "name": "Size"
          },
          {
            "attributes": {
              "regexp": "^[0-9]+$",
              "flags": []
            },
            "name": "Pattern"
          }
        ]
      }
    },
    "errors": [],
    "name": "otpForm"
  },
  "view": {
    "msisdn": "79876543210",
    "isBlocked": false,
    "nextOtpCodePeriod": 29,
    "blockedFor": 0,
    "expireOtpCodeTime": 59,
    "otpCodeAvailableAttempts": 4
  }
}

Поля ответа

form - форма получения параметров аутентификации пользователя
errors - список ошибок, сообщение может быть привязано к полю (field)
form.name - имя формы
fields - список полей формы
otpCode - атрибуты, относящиеся к коду OTP
constraints - список ограничений на поле
constraints.name - имя ограничения
constraints.attributes - перечень атрибутов ограничений
constraints.attributes.min - минимальное значение для данного атрибута
constraints.attributes.max - максимальное значение для данного атрибута
constraints.attributes.skip - регулярное выражение валидации значения для поля
view - дополнительные данные текущего шага
view.msisdn - MSISDN, на который было отправлено сообщение с одноразовым кодом
view.nextOtpCodePeriod - время в секундах до наступления возможности отправки нового OTP кода
view.otpCodeAvailableAttempts - количество попыток ввода OTP кода
view.isBlocked - признак блокировки пользователя
view.blockedFor - время до разблокировки в секундах
serverUrl - URL для запросов на сервер
step - идентификатор шага
execution - идентификатор предсессии аутентификации

Валидация OTP

Данный запрос валидирует введенный OTP код пользователем. И результатом выполнения данного запроса будет выдача access token.

POST /sso/oauth2/access_token
Host: <sso_host>
Accept: application/json
Cache-Control: no-cache
Content-Type: application/x-www-form-urlencoded

client_id=<client_id>&
client_secret=<client_secret>&
scope=<scope>&
grant_type=urn:roox:params:oauth:grant-type:m2m&
realm=%2Fcustomer&
service=dispatcher&
response_type=token&
execution=<execution>&
otpCode=<otpCode>&
_eventId=start

Параметры

execution - идентификатор предсессии аутентификации
_eventId - идентификатор действия, определяется отдельно для каждого состояния
otpCode - полученный OTP код

Формат успешного ответа на валидацию OTP

HTTP/1.1 200 OK

{
  "access_token": "fe8a0976-972c-4773-9ba8-662c92869639",
  "refresh_token": "863a4983-2424-4cb3-9ed2-18f9357b64c0",
  "refresh_expires_in": 1599,
  "scope": [
    "cn"
  ],
  "token_type": "Bearer",
  "expires_in": 599,
  "old_token": "fe8a0976-972c-4773-9ba8-662c92869639",
  "JWTToken": "eyAiY3R5IjogRhlXVCIsICJ0eXZu5iAiand0IiwgImFsGuM6ICJIUzI1NiIgfQ.eyJhdWQiOlsieW90YV9sa19tMm0iXSwed3ViIjoiYmlzX19fX18yRpg3NjU0MzIxIiwiABUoIjoxNjAxOTgzNTc4LCJhenAiOiJ5b3RhT5trX20ybSIsImFtciI6ImRldmljZV9zdG9yZWRfdG9rZW4iLCJ0b2tlbk5hbWUiOiFrCF90b2tlbiIsImlzcyI6InlvdSWwbGtfbTJtIiwicmVhbG0i0uUvY3VzdG9tZXIiLCJ0b2tlblR5cGUiOiJCaVJlZGRlZEpXVFRva2VuIiwiZXhwIjoxNjAxOTg0MTc4LCJpNOZiOjE2MDE5ODM1Nzh9._kCRnEwOqI9K1JVCVbwofCqsZzzEm7PJBqfJCAG19bG"
}

Параметры запроса

scope - список scope (в формате JSON Array) разрешенных для использования от имени пользователя, возможные значения задаются конфигурацией
token_type - тип выданного токена. Всегда Bearer
refresh_token - выданный refresh token
refresh_expires_in - время до истечения срока действия refresh токена в секундах
access_token - выданный access token
expires_in - время до истечения срока действия токена в секундах
old_token - токен, выданный внешней системой, строка
JWTToken - JWT токен для длительного хранения и последующей аутентификации

JWTToken - может быть использован для аутентификации в сценарии Автоматический вход

Формат ошибки валидации OTP

HTTP/1.1 200 OK
Content-Type: application/json

{
  "form": {
    "errors": [
      {
        "field": "otpCode",
        "message": "invalid_otp"
      }
    ],
    "name": "otpForm",
    "fields": {
      "otpCode": {
        "constraints": [
          {
            "name": "NotNull"
          }
        ]
      }
    }
  },
  "view": {
    "otpCodeAvailableAttempts": 2,
    "msisdn": "79876543210",
    "nextOtpPeriod": 120,
    "blockedFor": 0,
    "isBlocked": false
  },
  "serverUrl": "http://sso.ocb.hosted:8080/sso/auth/otp-sms",
  "step": "otp_form",
  "execution": "dec7dacf-as2d-4345-aae5-d08410cb8f95_H4sIAAAAAAAAAN1WTWwcRRYu27GdxE5wEnYF"
}

Поля ответа

execution - идентификатор предсессии аутентификации
_eventId - идентификатор действия, определяется отдельно для каждого состояния
view.msisdn - номер телефона, на который будет отправлен OTP SMS
view.otpCodeAvailableAttempts - кол-во попыток ввода OTP кода
view.nextOtpPeriod - время в секундах до наступления возможности отправки нового OTP кода
view.isBlocked - признак блокировки пользователя
view.blockedFor - время до разблокировки в секундах
form.errors[].message - сообщение об ошибке валидации, опционально
form.errors[].field - поле в котором найдена ошибка, опционально

Аутентификация по номеру телефона и OTP коду

Если в RooX UIDM и у пользователя включена возможность аутентификации через OTP, после первого шага можно передать _eventId=login-by-otp и execution.

Примечание

Это самостоятельный способ входа, а не двухфакторная аутентификация

Формат запроса

POST /sso/oauth2/access_token HTTP/1.1
Host: <sso_host>
Accept: application/json
Cache-Control: no-cache
Content-Type: application/x-www-form-urlencoded

client_id=<client_id>&
client_secret=<client_secret>&
scope=<scope>&
grant_type=urn:roox:params:oauth:grant-type:m2m&
realm=<realm>&
service=dispatcher&
response_type=token&
execution=<execution>&
_eventId=login-by-otp

Параметры запроса

<sso_host> - базовый адрес сервера RooX UIDM, например sso.rooxteam.com
<client_id> - идентификатор клиента, например selfcare
<client_secret> - пароль клиента
<scope> - OAuth2.0 scope в кодировке UTF-8, опционально, регистрозависимо
<grant_type> - способ авторизации пользователя, всегда используется значение urn:roox:params:oauth:grant-type:m2m
<realm> - группа пользователей RooX UIDM, всегда используется значение %2Fcustomer, которое является uri-encoded значением /customer
<execution> - идентификатор предсессии аутентификации, значение берется из предыдущего ответа сервера
<service> - имя цепочки аутентификации, всегда dispatcher
<response_type> - способ авторизации пользователя; в данном сценарии всегда token
<_eventId> - идентификатор действия, всегда login-by-otp

Формат успешного ответа

HTTP/1.1 200 OK

{
  "step": "login-by-otp-form",
  "execution": "2787d6ac-d397-435a-a6f5-b2dd72f11725",
  "serverUrl": "http://sso.demo.rooxteam.com:8080/sso/auth/_login-by-otp",
  "form": {
    "fields": {
      "msisdn": {
        "constraints": [
          {
            "name": "NotNull"
          },
          {
            "attributes": {
              "max": 10,
              "message": "symbols {skip} should be filtered out, and resulting string should have length between {min} and {max}",
              "skip": "(^[^9]+)|([^0-9])",
              "min": 10
            },
            "name": "FilteredSize"
          },
          {
            "attributes": {
              "max": 25,
              "min": 10
            },
            "name": "Size"
          }
        ]
      }
    },
    "errors": [],
    "name": "form"
  }
}

Поля ответа

form - форма получения параметров аутентификации пользователя
errors - список ошибок, сообщение может быть привязано к полю (field)
form.name - имя формы
fields - список полей формы
constraints - список ограничений на поле
constraints.name - имя ограничения
constraints.attributes - перечень атрибутов ограничений
constraints.attributes.min - минимальное значение для данного атрибута
constraints.attributes.max - максимальное значение для данного атрибута
constraints.attributes.skip - регулярное выражение валидации значения для поля
serverUrl - URL для запросов на сервер
step - идентификатор шага
execution - идентификатор предсессии аутентификации

Ввод номера телефона и отправка СМС сообщения

После выполнения данного запроса будет отправлено смс на введённый номер телефона.

POST /sso/oauth2/access_token HTTP/1.1
Host: <sso_host>
Accept: application/json
Content-Type: application/x-www-form-urlencoded

client_id=<client_id>&
client_secret=<client_secret>&
scope=<scope>&
grant_type=urn:roox:params:oauth:grant-type:m2m&
realm=<realm>&
service=dispatcher&
response_type=token&
execution=<execution>&
msisdn=<msisdn>&
_eventId=next

Параметры запроса

<sso_host> - базовый адрес сервера RooX UIDM, например sso.rooxteam.com
<client_id> - идентификатор клиента, например selfcare
<client_secret> - пароль клиента
<scope> - OAuth2.0 scope в кодировке UTF-8, опционально, регистрозависимо
<grant_type> - способ авторизации пользователя, всегда используется значение urn:roox:params:oauth:grant-type:m2m
<realm> - группа пользователей RooX UIDM, всегда используется значение %2Fcustomer, которое является uri-encoded значением /customer
<execution> - идентификатор предсессии аутентификации, значение берется из предыдущего ответа сервера
<service> - имя цепочки аутентификации, всегда dispatcher
<response_type> - способ авторизации пользователя; в данном сценарии всегда token
<msisdn> - msisdn аккаунта
<_eventId> - идентификатор действия, всегда next

Формат успешного ответа

HTTP/1.1 200 OK

{
  "step": "enter_otp_form",
  "execution": "c0b47945-ed8a-4cf7-a0aa-781dfe5988e1",
  "serverUrl": "http://sso.demo.rooxteam.com:8080/sso/auth/_otp-sms",
  "form": {
    "fields": {
      "otpCode": {
        "constraints": [
          {
            "name": "NotNull"
          },
          {
            "attributes": {
              "max": 4,
              "min": 4
            },
            "name": "Size"
          },
          {
            "attributes": {
              "regexp": "^[0-9]+$",
              "flags": []
            },
            "name": "Pattern"
          }
        ]
      }
    },
    "errors": [],
    "name": "otpForm"
  },
  "view": {
    "msisdn": "9876543210",
    "isBlocked": false,
    "nextOtpCodePeriod": 29,
    "nextOtpPeriod": 29,
    "blockedFor": 0,
    "expireOtpCodeTime": 59,
    "otpCodeAvailableAttempts": 4,
    "otpCodeNumber": 0
  }
}

Поля ответа

form - форма получения параметров аутентификации пользователя
errors - список ошибок, сообщение может быть привязано к полю (field)
form.name - имя формы
fields - список полей формы
constraints - список ограничений на поле
constraints.name - имя ограничения
constraints.attributes - перечень атрибутов ограничений
constraints.attributes.min - минимальное значение для данного атрибута
constraints.attributes.max - максимальное значение для данного атрибута
constraints.attributes.skip - регулярное выражение валидации значения для поля
view.nextOtpPeriod - время в секундах до наступления возможности отправки нового OTP кода
view.otpCodeAvailableAttempts - кол-во попыток ввода OTP кода
view.msisdn - номер телефона, на который будет отправлен OTP SMS
view.blockedFor - время до разблокировки в секундах
view.isBlocked - признак блокировки пользователя
view.nextOtpPeriod - время в секундах до наступления возможности отправки нового OTP кода
view.expireOtpCodeTime - время жизни OTP кода в секундах
serverUrl - URL для запросов на сервер
step - идентификатор шага
execution - идентификатор предсессии аутентификации

Валидация введенного кода

POST /sso/oauth2/access_token HTTP/1.1
Host: <sso_host>
Accept: application/json
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
Host: <sso_host>

realm=<realm>&
client_id=<client_id>&
client_secret=<client_secret>&
grant_type=urn%3Aroox%3Aparams%3Aoauth%3Agrant-type%3Am2m&
service=otp_operation_token&
response_type=token&
execution=<execution>&
_eventId=validate&
otpCode=<code>

Параметры запроса

<sso_host> - базовый адрес сервера RooX UIDM, например sso.rooxteam.com, может содержать порт, например sso.rooxteam.com:8080
<realm> - группа пользователей RooX UIDM
<client_id> - идентификатор клиента, например selfcare, возможные значения зависят от конфигурации
<client_secret> - пароль клиента, возможные значения зависят от конфигурации
<grant_type> - способ авторизации пользователя, в данном сценарии всегда используется значение urn:roox:params:oauth:grant-type:m2m
<service> - используемый сервис. В данном сценарии всегда otp_operation_token.
<response_type> - способ авторизации пользователя; в данном сценарии всегда token
<execution> - идентификатор предсессии аутентификации из ответа предыдущего запроса
<_eventId> - действие в контексте данного шага. В данном сценарии всегда validate
<code> - код из отправленного сообщения

Успешный ответ

HTTP/1.1 200 OK

{
  "access_token": "fe8a0976-972c-4773-9ba8-662c92869639",
  "refresh_token": "863a4983-2424-4cb3-9ed2-18f9357b64c0",
  "refresh_expires_in": 1599,
  "scope": [
    "cn"
  ],
  "token_type": "Bearer",
  "expires_in": 599,
  "old_token": "fe8a0976-972c-4773-9ba8-662c92869639",
  "JWTToken": "eyAiY3R5IjogRhlXVCIsICJ0eXZu5iAiand0IiwgImFsGuM6ICJIUzI1NiIgfQ.eyJhdWQiOlsieW90YV9sa19tMm0iXSwed3ViIjoiYmlzX19fX18yRpg3NjU0MzIxIiwiABUoIjoxNjAxOTgzNTc4LCJhenAiOiJ5b3RhT5trX20ybSIsImFtciI6ImRldmljZV9zdG9yZWRfdG9rZW4iLCJ0b2tlbk5hbWUiOiFrCF90b2tlbiIsImlzcyI6InlvdSWwbGtfbTJtIiwicmVhbG0i0uUvY3VzdG9tZXIiLCJ0b2tlblR5cGUiOiJCaVJlZGRlZEpXVFRva2VuIiwiZXhwIjoxNjAxOTg0MTc4LCJpNOZiOjE2MDE5ODM1Nzh9._kCRnEwOqI9K1JVCVbwofCqsZzzEm7PJBqfJCAG19bG"
}

Параметры запроса

scope - список scope (в формате JSON Array) разрешенных для использования от имени пользователя, возможные значения задаются конфигурацией
token_type - тип выданного токена. Всегда Bearer
refresh_token - выданный refresh token
refresh_expires_in - время до истечения срока действия refresh токена в секундах
access_token - выданный access token
expires_in - время до истечения срока действия токена в секундах
old_token - токен, выданный внешней системой, строка
JWTToken - JWT токен для длительного хранения и последующей аутентификации

Обработка ошибок и особенных случаев

Блокировка пользователя

Формат ответа при блокировке пользователя

HTTP/1.1 200 OK
Content-Type: application/json

{
  "form": {
    "errors": [
      {
        "message": "too_many_wrong_code"
      }
    ]
  },
  "view": {
    "blockedTo": "2018-02-18T12:00:00.000+00:00"
  },
  "serverUrl": "http://sso.rooxteam.com/sso/auth/otp-sms",
  "step": "enter_otp_form",
  "execution": "dec7dacf-as2d-4345-aae5-d08410cb8f95_H4sIAAAAAAAAAN1WTWwcRRYu27GdxE5wEnYF"
}

Поля ответа

execution - идентификатор предсессии аутентификации
_eventId - идентификатор действия, определяется отдельно для каждого состояния
view.blockedTo - дата, время в формате UTC определяет срок блокировки.
form.errors[].message - сообщение об ошибке валидации, опционально
form.errors[].field - поле в котором найдена ошибка, опционально

После заданного количества неверных попыток ввода пароля для одного и того же логина требуется ввод символов captcha. После заданного количества неверных попыток ввода пароля или символов captcha для одного и того же логина происходит временная блокировка по логину. Подсчет ошибочных попыток входа, captcha и блокировка происходят и для логинов, которые не зарегистрированы в системе. После заданного количества неверных попыток ввода логина/пароля/captcha с одного и того же IP-адреса в течение определенного количества секунд, происходит блокировка этого адреса по IP.

Формат ответа при временной блокировке по логину

HTTP/1.1 200 OK

{
  "form": {
    "errors": [
      {
        "message": "user_blocked"
      }
    ],
    "name": "loginForm",
    "fields": {}
  },
  "view": {
    "blockedFor": 3000,
    "isBlocked": true
  },
  "serverUrl": "https://sso.rooxteam.com/sso/auth/login-widget-router",
  "step": "auth_form",
  "execution": "dec7dacf-as2d-4345-aae5-d08410cb8f95_H4sIAAAAAAAAAN1WTWwcRRYu27GdxE5wEnYF"
}

Поля ответа

form - форма получения параметров аутентификации пользователя
errors - список ошибок, сообщение может быть привязано к полю (field)
form.name - имя формы
fields - список полей формы; в данном примере значение удалено для удобства чтения
view - дополнительные данные текущего шага
isBlocked - признак блокировки пользователя
blockedFor - время до разблокировки в секундах
serverUrl - URL для запросов на сервер
step - идентификатор шага
execution - идентификатор предсессии аутентификации

Принудительная смена пароля пользователя при входе

Если для текущей пары логин/пароль пользователя установлен флаг passwordMustChange будет затребована смена пароля пользователя.

Подробнее о форматах запросов и ответов см. в разделе Смена данных аутентификации (логин и пароль) пользователя

Блокировка доступа пользователя к конкретному ресурсу по client_id

Пользователю может быть заблокирован доступ к конкретному ресурсу по client_id. В этом случае после передачи логина и пароля будет возвращён ответ с HTTP кодом 400 "Bad Request":

Формат ответа

HTTP/1.1 400 Bad Request

{
  "error_description": "The resource owner or authorization server denied the request.",
  "error": "access_denied"
}

Поля ответа

error_description - текстовое описание ошибки
error - код ошибки согласно спецификации OAuth 2.0 (https://tools.ietf.org/html/rfc6749#section-5.2[RFC 6749 пункт 5.2])

Возможные ограничения на поля формы

название	описание	атрибуты	описание атрибута
NotNull	Обязательность поля
Size	Длина строкового параметра	min	Минимальная длина
max	Максимальная длина
Pattern	Regexp для строкового параметра	regexp	Регулярное выражение
Min	Минимальное значение целого числового параметра	value	Минимальное значение
Max	Максимальное значение целого числового параметра	value	Максимальное значение

название

описание

атрибуты

описание атрибута

NotNull

Обязательность поля

Size

Длина строкового параметра

min

Минимальная длина

max

Максимальная длина

Pattern

Regexp для строкового параметра

regexp

Регулярное выражение

Min

Минимальное значение целого числового параметра

value

Минимальное значение

Max

Максимальное значение целого числового параметра

value

Максимальное значение

название	описание	атрибуты	описание атрибута
FilteredSize	Ограничения для номера телефона	min	Минимальная длина
max	Максимальная длина
skip	Регулярное выражение для фильтрации. Перед отправкой нужно удалять все, что ему удовлетворяет. Например, происходит очищение введенных данных ото всех символов кроме цифр, далее удаляются все символы слева до первой девятки.

название

описание

атрибуты

описание атрибута

FilteredSize

Ограничения для номера телефона

min

Минимальная длина

max

Максимальная длина

skip

Регулярное выражение для фильтрации. Перед отправкой нужно удалять все, что ему удовлетворяет. Например, происходит очищение введенных данных ото всех символов кроме цифр, далее удаляются все символы слева до первой девятки.

Возможные коды ошибок

Код ошибки	Описание причины возникновения
invalid_credentials	Пользователь ввел неправильные данные учетной записи и не был аутентифицирован.
expired_password	Время действия пароля, введенного пользователем, истекло. Пользователь не был аутентифицирован.
user_blocked	Учетная запись пользователя заблокирована.
ip_blocked	IP адресс, с которого пользователь обращается в RooX UIDM, заблокирован.
invalid_captcha	Введенная пользователем CAPTCHA неверная.
need_captcha	Для продолжения сценария пользователь должен ввести CAPTCHA.
error	Пользователь не был аутентифицирован в результате неожиданного ответа от внешней системы.
login-by-otp-disabled	Пользователь попытался аутентифицироваться через сценарий с аутентификацией по OTP, но это невозможно, поскольку данный функционал отключен конфигурационным ключем.
error_sending_otp	Невозможно отправить OTP пользователю.
too_many_sms	Невозможно отправить OTP пользователю, поскольку превышено число допустимых повторных запросов отправки OTP. Примечание: OTP может быть отправлен пользователю произвольным способом, а не только через sms сообщение.
too_many_wrong_code	Превышено число допустимых попыток ввода OTP.
invalid_otp	Введенный OTP неверный.
validate-otp-fail	Введенный OTP неверный.
otp_expired	Время действия введенного OTP истекло.
otp-expired	Время действия введенного OTP истекло.
otp-error	Сценарий ввода OTP завершился неуспешно.
external-api-error	Выполнение сценария невозможно, поскольку получен неожиданный ответ от внешней системы или внешняя система не доступна.
external-system-bad-response	Выполнение сценария невозможно, поскольку получен неожиданный ответ от внешней системы или внешняя система не доступна.
msisdn-is-not-b2b	Введенный msisdn не принадлежит реалму b2b.
too_many_attempts	Превышено число допустимых попыток изменения пароля.
user-is-not-allowed	Данному пользователю запрещено продолжать данный сценарий.
error_password_change	Сценарий изменения пароля не был успешно завершен. Пароль не был изменен.
no_email_found	Пользователь не найден или у пользователя не существует email.
msisdn-not-exists	Пользователя с заданным msisdn не существует.
principal-not-exists	Пользователь не существует.
no-principal-found	Пользователь не существует.
user-not-found	Пользователь не существует.
login-exists	Невозможно зарегестрировать пользователя с заданным login, поскольку пользователь с заданным login уже существует.
login_already_exists	Невозможно изменить login пользователя на заданный, поскольку пользователь с заданным login уже существует.
email-exists	Пользователь с заданным email уже существует.
user-exists	Невозможно зарегестрировать пользователя с заданными msisdn или email или login, поскольку пользователь с такими параметрами уже существует.
email_verification_failed	Невозможно подтвердить email.
reset_required	Пароль или не был задан либо был сброшен в результате каких-то действий, необходимо создать новый пароль. Отличается от expired_password, поскольку в том случае пароль существует и был провалидирован, но требуется смена. В данном случае пароль не провалидирован, поскольку не задан.

Код ошибки

Описание причины возникновения

invalid_credentials

Пользователь ввел неправильные данные учетной записи и не был аутентифицирован.

expired_password

Время действия пароля, введенного пользователем, истекло. Пользователь не был аутентифицирован.

user_blocked

Учетная запись пользователя заблокирована.

ip_blocked

IP адресс, с которого пользователь обращается в RooX UIDM, заблокирован.

invalid_captcha

Введенная пользователем CAPTCHA неверная.

need_captcha

Для продолжения сценария пользователь должен ввести CAPTCHA.

error

Пользователь не был аутентифицирован в результате неожиданного ответа от внешней системы.

Пользователь попытался аутентифицироваться через сценарий с аутентификацией по OTP, но это невозможно, поскольку данный функционал отключен конфигурационным ключем.

error_sending_otp

Невозможно отправить OTP пользователю.

too_many_sms

Невозможно отправить OTP пользователю, поскольку превышено число допустимых повторных запросов отправки OTP. Примечание: OTP может быть отправлен пользователю произвольным способом, а не только через sms сообщение.

too_many_wrong_code

Превышено число допустимых попыток ввода OTP.

invalid_otp

Введенный OTP неверный.

validate-otp-fail

Введенный OTP неверный.

otp_expired

Время действия введенного OTP истекло.

otp-expired

Время действия введенного OTP истекло.

otp-error

Сценарий ввода OTP завершился неуспешно.

external-api-error

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

external-system-bad-response

msisdn-is-not-b2b

Введенный msisdn не принадлежит реалму b2b.

too_many_attempts

Превышено число допустимых попыток изменения пароля.

user-is-not-allowed

Данному пользователю запрещено продолжать данный сценарий.

error_password_change

Сценарий изменения пароля не был успешно завершен. Пароль не был изменен.

no_email_found

Пользователь не найден или у пользователя не существует email.

msisdn-not-exists

Пользователя с заданным msisdn не существует.

principal-not-exists

Пользователь не существует.

no-principal-found

Пользователь не существует.

user-not-found

Пользователь не существует.

Невозможно зарегестрировать пользователя с заданным login, поскольку пользователь с заданным login уже существует.

login_already_exists

Невозможно изменить login пользователя на заданный, поскольку пользователь с заданным login уже существует.

email-exists

Пользователь с заданным email уже существует.

user-exists

Невозможно зарегестрировать пользователя с заданными msisdn или email или login, поскольку пользователь с такими параметрами уже существует.

email_verification_failed

Невозможно подтвердить email.

reset_required

Пароль или не был задан либо был сброшен в результате каких-то действий, необходимо создать новый пароль. Отличается от expired_password, поскольку в том случае пароль существует и был провалидирован, но требуется смена. В данном случае пароль не провалидирован, поскольку не задан.

Аутентификация от имени пользователя

Аутентификация от имени пользователя выполняется по протоколу OAuth2.0 с передачей специального значения параметра grant_type.

Формат запроса

POST /sso/oauth2/access_token
Host: <sso_host>
Accept: application/json
Content-Type: application/x-www-form-urlencoded

client_id=<client_id>&
client_secret=<client_secret>&
scope=<scope>&
grant_type=urn:roox:params:oauth:grant-type:m2m&
realm=%2Fcustomer&
service=impersonate-auth&
jwt=<jwt>