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
• Authenticating with encrypted passwords

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:

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:

• 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"