Web login procedure

There is a new web session login procedure available in the Neuron®. From build 2025-08-18, clients performing web session login must follow this new procedure. For users using the browser to login, this is accomplished by simply refreshing the page to ensure the most recent javascript file is loaded when logging in.

Note: Web session login is used to access the administrative page. Agent API uses another type of login, based on JWT bearer tokens.

The client calls the /Login web resource with a JSON object payload as follows:

{
	"UserName": Required(Str(PUserName)),
	"PasswordHash": Required(Str(PPasswordHash)),
	"Nonce": Required(Str(PNonce))
}

While the web resource is the same as before, the following is new:

• A PasswordHash property is sent instead of a Password in clear text (albeit over an obligatory encrypted channel, i.e. basic authentication over HTTPS). How this password hash is computed is described below.
• A Nonce value is available. This value must be unique, and cannot be reused. It is recommended this is a base64-encoding of a sufficiently large random number, for instance a 32-byte random number, to generate sufficient entropy. Reusing a nonce value will result in an error being returned.
• The respone of the web resource is another JSON object, instead of the earlier redirection response if successful, and a session variable state change, if an error occurred.

The purpose of the change is twofold:

• Secure the login endpoint
• Allow third party clients to login using the web login.

The response to the call is a JSON object as follows:

{
	"ok": Required(Bool(POk)),
	"message": Optional(Str(PMessage))
}

If ok is false, the message will contain an error message. Note that the login will be available in the current session. To enable sessions, cookies must be enabled.

Hash Digest computation

The client needs to perform the following computations to generate the hash digest to send to the Neuron®:

1. Compute H1 = SHA3-256(UserName + ":" + Domain + ":" + Password), where Domain is the host name or main domain name of the Neuron®. It cannot be an alternative domain name, it must be the main domain name of the Neuron®.

2. Compute H2 = HMAC-SHA-256(UTF8Encode(Nonce),H1), where the UTF-8 encoded Nonce is used as key to the HMAC-SHA-256 algorithm, and H1 is used as the data whose digest is to be computed. Note that the UTF-8 encoding must not include a preamble or byte-order-mark (BOM).

3. Compute PasswordHash = BASE64(H2).

Note: For a reference implementation, see the /Login.js javascript resource on an updated Neuron®.

#new, #api, #security