Skip to content

Forgot password service

As of release 4.0.0, KX Platform provides an automated service allowing users to reset their password.

A user requests a password reset from the front end and then receives an email asking her to confirm the request. If she clicks on this link her password will be reset and she receives a second email containing the new password. She can immediately log on to KX Platform with the new password.

Prerequisites

  • KX Control and AppServer (version 4.0.0) running
  • Alerts workflow service running
  • JEMAIL service set up correctly (see configuration section below)

Using the service

To request a password reset for a particular user, enter a URL in the following format into a web browser: 

http://<tomcat_server>:<tomcat_port>kxuseradmin?operation=request&data=userId
If the request is successful

  • the response Password reset request received for userId XXX. Please check your email will be displayed in the browser
  • the user will receive an email confirming the password reset request.

The screenshots below show an example request and the corresponding email.

Screenshot

Screenshot

Clicking on the link in the above email will result in browser displaying Please check your email for details of new password, and the user being emailed their new password. The email link contains a token that can only be used once. If the link is clicked a second time then the browser will display Invalid Request and the user’s password will not be reset again. To reset the user's password again, make a new request; it will produce another email, with a fresh token.The token will expire after the minutes detailed in the email. The time taken for tokens to expire, can be configured via the environment variable which can be set in the delta.profile file. If this is not set the default expire time is 30 minutes 

export DELTACONTROL_RESET_TIMEOUT=30

The servlet API

  • All calls to the Forgot Password service should be HTTP GET requests to the URL http://<server>:<host>/kxuseradmin, and include values for the parameters operation and data.
  • There are two acceptable values for operation: request and confirm.
  • For request operation the value of data should be a valid user ID. If the request is successful then the response Password reset request received for userId XXXX. Please check your email. is sent; otherwise Invalid request. In the case of an invalid response, check delta.log for details of the reason for failure.
  • For confirm operation the value of data should be the value of a valid token, generated as a result of a request call. Note however that it is unlikely to ever be necessary to construct the confirm request, as the correct URL for the confirm operation is generated by KX Control and emailed to the user.
  • The data (token) value of a confirm operation can be used only once. If the same token is sent down again, the request fails with an Invalid request response.
  • Only one token at a time per user ID is valid. If two rest requests are made for the same user, only the most recent token is valid.
  • Tokens are valid for a limited period of time. The timeout period (in minutes, default 30) is configured via the DC_PASSWORD_RESET:DEFAULT parameter.
  • Only tokens that have been generated as a result of a password-reset request are valid.

Unlock user on reset

Control can be configured to unlock a user's account when a password reset is requested. This is configured via an environment variable which can be set in the delta.profile file. By default it is set to NO. 

DELTACONTROL_RESET_UNLOCK_ACCOUNT=NO
If this variable is set to YES then when a user requests a password reset their account will be unlocked if it was in a locked state.

Configuration

JEmail configuration

For emails to be sent out correctly, the JEmail service must be running (this should be the case if alerts workflow is running) and configured properly. The JEmail service can be configured to use different mail servers in different modes. The particular mode to use is defined by specifying an override in the DS_LAUNCH command line param for the ds_jemail process, and then defining the server config in a corresponding override of DS_JEMAIL_SERVER, as in the example below:

Screenshot

Screenshot

URL configuration

The default verification URL that is emailed out will start with http://<tomcat_server>:<tomcat_port> – for example, http://webdev.firstderviatives.com:14090/kxuseradmin?…. If a different URL is required (for example if all requests need to point to a public netscaler URL), this can be achieved by setting environment variable APPSERVER_BASEURL. For example, if install.config contains the line 

export APPSERVER_BASEURL=http://netscaler_host:666
then the verification URLs that are emailed out will start with http://netscaler_host:666/kxuseradmin?

Email content configuration

The email templates can be edited through the DS_AlertOverview dashboard in KX Flex. In the PasswordReset alert instance, there are notifications for the reset and the reset request. The templates can be edited there.

To create new templates, either add your own (can be against a new alert or the same one) or just edit the existing templates and save in your own package. In that case you would need to change the DC_PASSWORD_RESET:<DEFAULT> config param.

Case insensitivity

The tags in the email and config are case-insensitive. So $Url$ in the template will still match with URL in the config.

Back to top