Skip to main content
Version: 2.8

Authentication and session handling in Document.One

Authenticating to your Document.One instance

Before you start
  • 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.

NameInRequiredData typeDescription
AcceptheadertruestringSpecifies the media type of the response content expected from the server.
Content-TypeheadertruestringSpecifies 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.
usernamequerytruestringThe username used for authentication.
passwordquerytruestringThe password used for authentication.
noExceptionOnFailurequeryfalseboolean
staySignedInqueryfalseboolean

Response body parameters

The table below lists the properties of the response message.

NameRequiredData typeDescription
sessionIdtruestringThe session ID returned by the D1 instance.

HTTP response codes

The table below lists HTTP responses you may encounter during authentication.

HTTP response codeContent-TypeDescription
200 OKapplication/jsonThe authentication was successful.
500 Internal Server Errorapplication/jsonThe 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:

  1. 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==
    DONE

    You can find the encrypt.sh file in your adx-deployment-package installation folder.

  2. In OpenAPI, find the /access.adx.admin/v1/session endpoint and do the following:

    1. Enter your username in the userName field.
    2. Enter your encrypted password from Step 1 in the password field.
    3. Check the passwordIsEncrypted box.

Configuring sessions in Document.One

Requirement

Follow these steps to setup your Document.One (D1) 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.

NameInRequiredData typeDescription
AcceptheadertruestringSpecifies 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-TypeheadertruestringSpecifies 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.
sessionspathtruestringAll available sessions to be called.
sessionpathtruestringA specific session to be called.

Sample requests

The table below lists all available HTTP requests you can call for session handling.

HTTP requestEndpointService descriptionReturns
POST/access.adx.admin/v1/sessionCreate a session.
GET/access.adx.admin/v1/sessionRetrieve a session.The session ID or the session object.
GET/access.adx.admin/v1/session/searchSearch all available sessions.A list of available session objects.
DELETE/access.adx.admin/v1/sessionClose a session by session ID.
DELETE/access.adx.admin/v1/sessionsClose 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.

NameRequiredData typeDescription
sessionIdtruestringThe 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 codeContent-TypeDescription
200 OKapplication/jsonThe operation was successful.
404 Not Foundapplication/jsonThe 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.

NameRequiredTypeDescription
TRIBEFIRE_USER_SESSIONS_MAX_IDLE_TIMEfalsestringSpecifies 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_STAYSIGNEDfalsebooleanWhen 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"