Сессии (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 (EraSession) либо возвращает токен (session_token) в ответ на запрос.

В дальнейшем все запросы, содержащие cookie EraSession с идентификатором сессии, ассоциируются с этой сессией. В случае указания 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' – будет создана индивидуальная сессия, идентификатор которой вернётся в теле ответа вместо заголовка куки. В дальнейшем это значение следует передавать в заголовке "Authorization: Bearer TOKEN".

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

  • 'cookie' - будет создана стандартная сессия и установлена в заголовке cookie.

  • если значение отсутствует, то это эквивалентно 'cookie'

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

Внешний токен. Если параметр задан, то вместо проверки пароля запускается служебный сценарий проверки внешнего токена, установленный в системе (параметр мастер-домена 'iam_token_svcscript_code'). Параметры 'domain', 'login', 'pwd' не требуются, они будут проигнорированы. Для подтверждения аутентификации сценарий должен вернуть в переменных со специальными именами имя существующего домена и логин существующего в домене пользователя.
Пример запроса на создание сессии
POST /rest/v1/iam/sessions HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "domain": "docs.rootdomain.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: EraSession=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: EraSession=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.rootdomain.ru",
  "domain_is_master": false,
  "domains": [
    {
      "domain": "rootdomain.ru",
      "is_master": true
    },
    {
      "domain": "test.rootdomain.ru",
      "is_master": false
    }
  ],
  "login": "peter",
  "name": "Peter Bukashin",
  "name_login": "Peter Bukashin (peter)",
  "roles": [
    "admin"
  ],
  "solution": "era",
  "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.rootdomain.ru"
}

Ответ

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

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

Удаляет текущую сессию.

  • Если в запросе присутствует заголовок Authorization, то будет произведена попытка удаления указанной в нём сессии, привязанной к токену. При этом сессия, привязанная к cookie, не затрагивается.

  • Если заголовок Authorization отсутствует, то будет удалена сессия указанная в cookie.

Запрос

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

Ответ

HTTP/1.1 204 No Content
set-cookie: EraSession=deleted; Expires=Thu, 01 Jan 1970 00:00:00 GMT; Path=/; SameSite=Strict
  • Персонализация
  • Увеличить шрифт
  • Уменьшить шрифт