Authentication and session handling in Document.One
Authenticating to your Document.One instance
- Download and install your Document.One instance
Once installation is complete, choose one of the following two ways to authenticate to your Document.One (D1) instance:
Authenticating with username and password
To authenticate to your D1 instance, send a POST HTTP request to the https://[host]:[port]/access.adx.admin/v1/session
endpoint, with your username and password included.
cURL example for authentication
The HTTP POST request below returns a session ID from the D1 instance running on https://[host]:[port]
.
curl -X POST "https://[host]:[port]/access.adx.admin/v1/session" -H "accept: application/json" -H "Content-Type: multipart/form-data" -F "user=[username]" -F "password=[password]" -F "noExceptionOnFailure=false" -F "staySignedIn=false"
Replace [host]
, [port]
, [username]
, and [password]
with the actual values in your request.
URI parameters for authentication
The table below lists the properties of the URI parameters.
Name | In | Required | Data type | Description |
---|---|---|---|---|
Accept | header | true | string | Specifies the media type of the response content expected from the server. |
Content-Type | header | true | string | Specifies the media type of the request being sent from the client to the server. Possible values: multipart/form-data , application/x-www-form-urlencoded , application/json . |
username | query | true | string | The username used for authentication. |
password | query | true | string | The password used for authentication. |
noExceptionOnFailure | query | false | boolean | |
staySignedIn | query | false | boolean |
Response body parameters
The table below lists the properties of the response message.
Name | Required | Data type | Description |
---|---|---|---|
sessionId | true | string | The session ID returned by the D1 instance. |
HTTP response codes
The table below lists HTTP responses you may encounter during authentication.
HTTP response code | Content-Type | Description |
---|---|---|
200 OK | application/json | The authentication was successful. |
500 Internal Server Error | application/json | The server encountered an internal error or misconfiguration and was unable to complete your request. |
Authenticating with encrypted passwords
Document.One enables you to authenticate by providing an encrypted password. To do this, follow these steps:
To encrypt your password, open your command line, and run the
./encrypt.sh --value mypassword
script. (If you are using Windows, run the./encrypt.bat --value mypassword
script.) The response contains the encrypted password:$ ./encrypt.sh --value 's3cur3p455w0rd'
cNRVe5T5gOB0o3NXxjCdRkiMGbNKWpAsbGFWFVKCVjZ0Jh1yUwyaZxPJ1WjFYbXABc6qiw==
DONEYou can find the
encrypt.sh
file in youradx-deployment-package
installation folder.In OpenAPI, find the
/access.adx.admin/v1/session
endpoint and do the following:- Enter your username in the
userName
field. - Enter your encrypted password from Step 1 in the
password
field. - Check the
passwordIsEncrypted
box.
- Enter your username in the
Configuring sessions in Document.One
Follow these steps to setup your Document.One (D1) instance:
- Downloading and installing your Document.One instance
- Authenticating to your Document.One instance
Once the authentication to your D1 instance is complete, you can use the session ID returned to you to modify, close, delete, or search within the session.
cURL example for session handling
The HTTP POST request below retrieves a session object or a session ID from the D1 instance running on https://[host]:[port]
.
curl -X POST "https://[host]:[port]/access.adx.admin/v1/session" -H "accept: application/json" -H "Content-Type: multipart/form-data"
Replace [host]
and [port]
with the actual values in your request.
URI parameters for session handling
The table below lists the properties of the URI parameters.
Name | In | Required | Data type | Description |
---|---|---|---|---|
Accept | header | true | string | Specifies the media type of the response content expected from the server. With the D1 Administration API, only the application/json content type is allowed. |
Content-Type | header | true | string | Specifies the media type of the request being sent from the client to the server. Possible values: multipart/form-data , application/x-www-form-urlencoded , application/json . |
sessions | path | true | string | All available sessions to be called. |
session | path | true | string | A specific session to be called. |
Sample requests
The table below lists all available HTTP requests you can call for session handling.
HTTP request | Endpoint | Service description | Returns |
---|---|---|---|
POST | /access.adx.admin/v1/session | Create a session. | |
GET | /access.adx.admin/v1/session | Retrieve a session. | The session ID or the session object. |
GET | /access.adx.admin/v1/session/search | Search all available sessions. | A list of available session objects. |
DELETE | /access.adx.admin/v1/session | Close a session by session ID. | |
DELETE | /access.adx.admin/v1/sessions | Close multiple sessions by session ID. |
OpenAPI
For code samples, see:
Retrieve a session
Create a session
Close a session by session ID
Response body parameters for session handling
The table below lists the properties of the response message.
Name | Required | Data type | Description |
---|---|---|---|
sessionId | true | string | The session ID returned by the D1 instance. |
HTTP response codes for session handling
The table below lists HTTP responses you may encounter during session handling.
HTTP response code | Content-Type | Description |
---|---|---|
200 OK | application/json | The operation was successful. |
404 Not Found | application/json | The requested session was not found. |
Keeping your session alive after closing the browser
To keep the session alive after you close the browser, configure the maximum idle time and the usage of session cookies. To do it, modify the TRIBEFIRE_USER_SESSIONS_MAX_IDLE_TIME
and TRIBEFIRE_RUNTIME_OFFER_STAYSIGNED
parameters' runtime properties in accordance with your needs when installing Document.One.
Name | Required | Type | Description |
---|---|---|---|
TRIBEFIRE_USER_SESSIONS_MAX_IDLE_TIME | false | string | Specifies how long a user session should remain active when there is no activity on the session. After the specified inactive time has passed (for example, no request with the corresponding session ID has been received by the server), the session is flagged as inactive and consequently removed by a periodic cleanup process. The time span can be specified as a human-readable string, using numbers and the time unit, as in 12h, 30m, 3600s, etc. Example: TRIBEFIRE_USER_SESSIONS_MAX_IDLE_TIME: "30m" |
TRIBEFIRE_RUNTIME_OFFER_STAYSIGNED | false | boolean | When this is set to true, the login dialog will offer an option to stay signed-in after a browser restart. If this is set to false, the user session will always be closed when the browser is closed. This is achieved by using a session cookie that stores the user's session ID until the browser is closed. Example: TRIBEFIRE_RUNTIME_OFFER_STAYSIGNED: "true" |