Exciton Boost Authentication

This page describes how Exciton Boost handles authentication, and future plans to expand the options.

Domino and DSAPI

Exciton Boost is a Domino Web Server Application Interface (DSAPI) extension to HCL Domino 10.x/11.x and IBM Domino 8.5.x/9.x. The DSAPI extension runs as part of the Domino HTTP process, and thus both relies on and extends Domino authentication and security.

In the current version of Exciton Boost, there are currently two authentication options. The first is a session-based authentication that works with the Domino HTTP process directly. When authentication is required, the REST API call returns an HTML login page. This form, or a replacement login form with the same fields, is then POSTed to the Domino server which authenticates. The REST API is considered logged in, and the session authentication is done through a Domino-managed cookie named DomAuthSessId which contains a session id and scope. The second option is to use Basic HTTP Auth with appropriate HTTP headers passing the user id and password. In this scenario, the application is responsible for obtaining and passing the appropriate credentials, and the REST API will return error codes if the authentication is not successful or adequate for the resource requested.

In a future version of Exciton Boost, we plan to support OAUTH2 through the IAM service available on Domino 10.x and above. If this is a requirement and you are using Domino 10.x or higher, let us know. and we will accelerate the process.

User ID options

Domino authentication, whether through a posted login form or Basic Auth, authenticates from a Person document in the Domino server's Name & Address book. This may be any of the canonical or common names listed under User name: field on the Person document or the address listed as the Internet address: field on the Person document.

TLS/SSL

It is strongly recommended that TLS/SSL be used on the Domino server, especially when Basic HTTP Auth is used, as the user id and password are not secured at all. They are converted to Base64, but that is trivial to decode. TLS/SSL and the use of HTTPS will ensure that requests and responses are encrypted. Both authentication methods will work without TLS/SSL, but that should be restricted to Test/Dev servers.

Authorization cookie (Session Auth)

The recommended authentication scheme for Exciton Boost in this beta is Domino Session Auth. Additional options using the IAM service in Domino 10 and above will be made available in the near future, but Session Auth will continue to be supported.

You may use either the default Domino login page or a custom one, so long as the the Content-Type header is set to application/x-www-form-urlencoded and the Credentials header is set to same-origin and the username, password, and redirectto items are included. Upon success, the return code will be 200 OK, and there will be a cookie on the page with the name DomAuthSessId. The entire value of this cookie must be sent on all subsequent requests that use the session. If the session expires, a new login screen will be returned, though you may ignore it and use your own custom Login instead.

cookie: DomAuthSessId=6AC2B1DF39782892A965885D2AABF777; Path=/; Domain=geniisupport.com;

Authorization headers (Basic Auth)

If you decide to use Basic HTTP Auth, the application must set an Authorization: in the HTTP header of each request. For example, if the browser uses 'Aladdin' as the user id and 'OpenSesame' as the password, then the field's value is the Base64 encoding of 'Aladdin:OpenSesame', or 'QWxhZGRpbjpPcGVuU2VzYW1l'. Then the Authorization header would appear as:

Authorization: Basic QWxhZGRpbjpPcGVuU2VzYW1l