accountService

The account service provides lost password and verify email functionality for user management. Each function has an endpoint for sending an email. A template for the email can be specified. This requires a template service and an email service to be set up.

The email contains a link back to a site url which has a token attached. The token has a valid lifetime specified. In the case of the lost password functionality the page at the site url should contain a form for entering the new password. This then posts this information along with the token to another endpoint which checks the token and updates the password. For verify email functionality, the page just contains a message and after the message is read, it posts the token to another endpoint which then checks the token and records the user's email as having been verified.

The endpoints are as below:

  • POST lost-password/<email address>: If the email address is of an existing user, send them an email made using the template at passwordReset.emailTemplateUrl with a link back to the site with the url passwordReset.returnPageUrl including a token allowing them to reset their password. Possible errors: 400 Missing Email, 400 No Such User
  • POST reset-password/<email address> { token, password }: If the email address is of an existing user, and the token supplied in the body JSON was validly generated for a previous lost password request at most passwordReset.tokenExpiryMins minutes ago, and hasn't already been used, reset the password to the value from the body JSON. Possible errors: 400 Missing Email, 400 No Such User, 400 <JSON format error>, 401 Bad token, 401 Expired, 401 Token used.
  • POST verify-email/<email address>: If the email address is of an existing user, send them an email made using the template at emailConfirm.emailTemplateUrl with a link back to the site with the url emailConfirm.returnPageUrl including a token allowing them to verify their email. Possible errors: 400 Missing Email, 400 No Such User.
  • POST confirm-email/<email address> { token }: If the email address is of an existing user, and the token supplied in the body JSON was validly generated for a previous verify email request at most emailConfirm.tokenExpiryMins minutes ago, and hasn't already been used, set the emailVerified property on the user record to the current date and time. Possible errors: 400 Missing Email, 400 No Such User, 400 <JSON format error>, 401 Bad token, 401 Expired, 401 Token used.

Email Templates

For the lost password and verify email endpoints, emails are generated by sending to a template at the passwordReset.emailTemplateUrl or emailConfirm.emailTemplateUrl the user record of the user with an added field called returnPageUrl containing the link back to the site with the token added as a query string parameter. The result of populating the template with this data is then sent to emailSendUrlPattern as the email body.

Special configuration properties

  • userUrlPattern: This is a url pattern which can only have the substitution code ${email} within it. It determines the url where the authenticationService can read the JSON for a user record. Normally this will be in the paths space of a userService. Typically this would be /json/user/${email}.
  • emailSendUrlPattern: This is a url pattern based on the url used to call whichever endpoint. Note that means the first path segment will be the name of the endpoint above: the email is the second path segment ($>1). It gives the url of the email service that this service should use to send emails. Typically /email/$>1
  • passwordReset: Parameters object for password reset flow with properties as below:
    • tokenExpiryMins: How many minutes before the token used in this flow expires
    • returnPageUrl: The url of the page to which the link in the email directs users. The token will be attached to this as a query string parameter named token and the users email as a parameter named email.
    • emailTemplateUrl: The url of the template used to generate the markup for the email body.
  • emailConfirm: Parameters object for email verification flow with properties the same as for passwordReset.