Сессии (sessions)

Запросы

HTTP verb Endpoint Описание

POST

/rest/v1/iam/sessions

Создание сессии (логин)

GET

/rest/v1/iam/sessions/current

Получение данных по текущей сессии

PATCH

/rest/v1/iam/sessions/current

Изменение текущей сессии

DELETE

/rest/v1/iam/sessions/current

Удаление текущей сессии (логаут)

Создание сессии (логин)

Производит аутентификацию пользователя в домене, создает сессию и устанавливает cookie (RSession) либо возвращает токен (session_token) в ответ на запрос.

В дальнейшем все запросы, содержащие cookie RSession с идентификатором сессии, ассоциируются с этой сессией.
В случае указания session_type, клиент (веб-приложение) получает в ответе токен (session_token), должно его прочитать и запомнить, а затем для работы API-запросов в контексте этой индивидуальной сессии отправлять хедер Authorization: Bearer <session_id>.

Применяет бан-фильтр IP-адресов для борьбы с перебором учетных записей.
Отклоняет запрос без обработки, если в течение 3 предыдущих минут 5 раз происходила неудачная попытка авторизоваться (неверная комбинация параметров domain, login, pwd).

При поступлении запросов с несуществующим идентификатором сессии применяет бан-фильтр по тем же правилам.

Запрос

Table 1. Параметры запроса
Спецификация Описание

Имя: domain
Тип: str

Домен для авторизации.

Имя: login
Тип: str

Логин учетной записи пользователя в домене.

Имя: pwd
Тип: str

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

Имя: session_type
Тип: str
По умолчанию: отсутствует

Тип создаваемой сессии. Возможные значения:

  • token – будет создана индивидуальная сессия, идентификатор которой вернётся в теле ответа вместо заголовка куки.

  • token_clone_cookie – открывает новую сессию, копируя учётные данные из сессии по куке (которая шлётся браузером автоматически). В случае указания параметры domain,login,pwd не требуются, они будут проигнорированы.

Пример запроса на создание сессии
POST /rest/v1/iam/sessions HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "domain": "docs.okteller.ru",
  "login": "peter",
  "pwd": "123"
}
Пример запроса на создание индивидуальной сессии
POST /rest/v1/iam/sessions HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "session_type": "token",
  "domain": "kzn.tele.dom",
  "login": "username",
  "pwd": "userpass"
}
Пример запроса на клонирование куковской сессии в индивидуальную
POST /rest/v1/iam/sessions HTTP/1.1
Cookie: RSession=07f49a96-0178-a220-2e37-e0d55e0cd303
Content-Type: application/json; charset=utf-8

{
  "session_type": "token_clone_cookie"
}

Ответ

Создание сессии
HTTP/1.1 204 No Content
set-cookie: RSession=6ef97511-0178-a21d-bd9a-e0d55e0cd303; Expires=Mon, 19 Apr 2021 12:59:21 GMT; Path=/; SameSite=Strict
Создание индивидуальной сессии или клонирование
HTTP/1.1 200 OK

{
  "session_token": "e2479460-0174-01d8-6638-e0d55e0cd13e"
}

Получение данных по текущей сессии

Сессия идентифицируется сначала по токену (хедер Authorization) если он присутствует и валиден (время жизни не истекло), иначе по cookie.

Возвращает данные по текущей сессии:

Поле Тип Описание

domain

str

имя текущего домена

domain_is_master

bool

true, если текущий домен является мастером, иначе false

domains

array<object>

список доменов, в которые пользователь может переключиться без проведения дополнительной авторизации

login

str

логин авторизованного пользователя

name

str

имя авторизованного пользователя

name_login

str

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

roles

array<str>

список ролей авторизованного пользователя в текущем домене

solution

str

тип солюшена текущего домена

tags

array<str>

тэги учетной записи авторизованного пользователя

user_id

uuid

идентификатор авторизованного пользователя

webapps

array<object>

список веб-приложений, доступных авторизованному пользователю

Поле domains. Каждый домен указывается в виде объекта:

Поле Тип Описание

domain

str

имя домена

is_master

bool

true, если домен является мастером, иначе false

Поле webapps. Каждое веб-приложение указывается в виде объекта:

Поле Тип Описание

name

str

название приложения

description

str

описание приложения

order

int

порядок вывода

icon

str

URL ресурса пиктограммы приложения

fa-icon

str

название иконки в формате font-awesome

roles

array<str>

список пользовательских ролей, которым доступно приложение

url

str

URL точки запуска приложения

Объекты веб-приложений могут содержать дополнительные поля, которые подставляются непосредственно из файлов-метаданных (webapps.json в папке метаданных солюшена для системных приложений и в файле метаданных ролевого приложения).

Запрос

Пример запроса
GET /rest/v1/iam/sessions/current HTTP/1.1

Ответ

Пример ответа
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "domain": "docs.okteller.ru",
  "domain_is_master": false,
  "domains": [
    {
      "domain": "okteller.ru",
      "is_master": true
    },
    {
      "domain": "test.okteller.ru",
      "is_master": false
    }
  ],
  "login": "peter",
  "name": "Peter Bukashin",
  "name_login": "Peter Bukashin (peter)",
  "roles": [
    "admin"
  ],
  "solution": "xunit",
  "tags": [],
  "user_id": "71374fef-42f1-4e49-2069-faab905d4be2",
  "webapps": [
    {
      "name": "Объекты",
      "order": 130,
      "fa-icon": "fa-paw",
      "icon": "/main_icons/objects.svg",
      "roles":["admin"],
      "url": "/objects"
    },
    {
      "name": "Сценарии",
      "order": 150,
      "fa-icon": "fa-pencil-square-o",
      "icon": "/main_icons/scripteditor.svg",
      "roles":["scripteditor","admin"],
      "url": "/scripteditor"
    }
  ]
}

Изменение текущей сессии

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

Запрос

Пример запроса
PATCH /rest/v1/iam/sessions/current HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "domain": "test.okteller.ru"
}

Ответ

HTTP/1.1 204 No Content
set-cookie: RSession=07f49a96-0178-a220-2e37-e0d55e0cd303; Expires=Mon, 19 Apr 2021 13:02:24 GMT; Path=/; SameSite=Strict

Удаление текущей сессии (логаут)

Уничтожает текущую сессию. Удаляет cookie в ответ на запрос.
Работа с сессией происходит либо только по токену если хедер Authorization присутствует, либо только по куке.
Если токен присутствует, но не валилден, работы с кукой не происходит.

Запрос

Пример запроса
DELETE /rest/v1/iam/sessions/current HTTP/1.1

Ответ

HTTP/1.1 204 No Content
set-cookie: RSession=deleted; Expires=Thu, 01 Jan 1970 00:00:00 GMT; Path=/; SameSite=Strict