Sessions (sessions)
Requests
| HTTP verb | Endpoint | Description |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Creating a session (login)
Authenticates the user in the domain, creates a session and sets a cookie (EraSession), or returns a token (session_token) in the response.
Subsequently all requests containing the EraSession cookie with the session identifier are associated with this session.
If session_type is specified, the client (web application) receives a token (session_token) in the response, must read and remember it, and then send the header Authorization: Bearer <session_id> for API requests in the context of this individual session.
Applies an IP address ban filter to counter account brute-forcing.
Rejects the request without processing if within the previous 3 minutes 5 failed authorization attempts occurred (an incorrect combination of domain, login, pwd parameters).
When requests with a nonexistent session identifier arrive, applies the ban filter by the same rules.
Request
| Specification | Description |
|---|---|
|
Domain for authorization. |
|
User account login in the domain. |
|
User account password in the domain. |
Type of session to create. Possible values:
|
|
|
External token. If the parameter is set, then instead of password verification the service script for external token verification installed in the system is run (master domain parameter 'iam_token_svcscript_code'). The 'domain', 'login', 'pwd' parameters are not required and are ignored. To confirm authentication, the script must return in specially named variables the name of an existing domain and the login of a user existing in the domain. |
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"
}
Response
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; Secure; HttpOnly
HTTP/1.1 200 OK
{
"session_token": "e2479460-0174-01d8-6638-e0d55e0cd13e"
}
Getting current session data
The session is identified first by token (Authorization header) if present and valid (lifetime has not expired), otherwise by cookie.
Returns data for the current session:
| Field | Type | Description |
|---|---|---|
|
|
current domain name |
|
|
|
|
|
list of domains to which the user can switch without additional authorization |
|
|
authorized user login |
|
|
authorized user name |
|
|
single string containing the authorized user’s name and login |
|
|
list of authorized user roles in the current domain |
|
|
current domain type (constant type 'era' or 'master'). |
|
|
tags of the authorized user account |
|
|
authorized user identifier |
|
|
list of web applications available to the authorized user |
The domains field. Each domain is specified as an object:
| Field | Type | Description |
|---|---|---|
|
|
domain name |
|
|
|
The webapps field. Each web application is specified as an object:
| Field | Type | Description |
|---|---|---|
|
|
application name |
|
|
application description |
|
|
output order |
|
|
URL of the application icon resource |
|
|
font-awesome format icon name |
|
|
list of user roles that can access the application |
|
|
URL of the application launch point |
Web application objects may contain additional fields supplied directly from metadata files (webapps.json in the metadata folder for system applications and in the role application metadata file).
Response
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": "incoplax",
"tags": [],
"user_id": "71374fef-42f1-4e49-2069-faab905d4be2",
"webapps": [
{
"name": "Objects",
"order": 130,
"fa-icon": "fa-paw",
"icon": "/main_icons/objects.svg",
"roles":["admin"],
"url": "/objects"
},
{
"name": "Scripts",
"order": 150,
"fa-icon": "fa-pencil-square-o",
"icon": "/main_icons/scripteditor.svg",
"roles":["scripteditor","admin"],
"url": "/scripteditor"
}
]
}
Modifying the current session
Rebinds the current session to another domain, one of those available for direct switching without authorization. Session work is performed either only by token if the Authorization header is present, or only by cookie. If the token is present but invalid, no work with the cookie occurs.
Deleting the current session (logout)
Deletes the current session.
-
If the request contains the Authorization header, an attempt is made to delete the session specified in it, bound to the token. The session bound to the cookie is not affected.
-
If the Authorization header is absent, the session specified in the cookie is deleted.
Deleting the user’s other sessions
Deletes all sessions of the current user except the current one (Authorization header or cookie, as for Deleting the current session (logout)).
For an integration channel token session — 400; without a session — 404.
DELETE /rest/v1/iam/sessions/others HTTP/1.1
HTTP/1.1 204 No Content
See also
-
API for managing sessions of an arbitrary user (rest/v1/iam/users/UserId/sessions)