Resetting Passwords with Aptify Services API

The password reset functionality allows you to reset a Web User's passwords using the Aptify Javascript API or direct passwords.  It is a two-step process.  The first step involves validating a Web User's userid and email address.  If the provided items match the Web User record in Aptify, a Password Reset Token is generated and the owner of the userid is notified of the request via email.  This request contains a URL where the user can go to reset their password.  Performing the actual password reset requires the token that was generated, the userid and the new password value.  

Supporting Entities

The majority of the supporting entities are found under the Web Services application, except where noted.

• Password Reset Requests: This entity stores information about password reset requests that have successfully been created.  It is here where you will find the token required to actually reset the password, what Web User record that entity is for, the authentication provider that generated the request, when the request expires, and audit information about the request.  The Audit Information subtype logs information about state changes in the request, such as when it was created, when it expires, when it is consumed, and what ip addresses performed these actions.
• Password Reset Token Managers: This entity can be used to configure certain aspects of the Password Reset Requests that are generated.  It points to a .NET plugin that is responsible for manipulating the records in the Password Reset Requests entity.  One provider exists by default.  It supports an attribute subtype name, TokenDuration.  The value of this attribute should be the number of minutes that the token is valid. 
• Password Reset Notifiers: The entity configures notifying the owner of the userid about password reset requests.  Notifiers use a message template to send notifications.  Message templates are driven off entities, and the default message template uses the 'Web User Password Reset Stagings' entity to as the Message Source for obtaining information to put in the message.  It is the job of the Password Reset Notifier plugin to create the entity record for the Message Source's entity, and to create the Message Run record that will generate the notification. 
• Password Requirements Provider: An entity that lists .NET plugins that validate certain password requirements.  By default, a single default provider exists that checks for a minimum password length.  If additional or different password requirements are required, a new plugin can be created that enforces these requirements.  Multiple plugins can be associated with the Authentication Provider record in question. 
• Authentication Providers: This entity has been updated to allow overrides at the authentication provider record for the Password Reset Token Manager, Password Reset Notifiers and Password Requirements Providers. 
• Web User Password Reset Stagings: The out of the box staging entity that is used as a Message Source to notify users of Password Reset related information.  

Password Reset Methods

There are two new methods to support password resets:

• Aptify.framework.utility.passwordResetRequest(options)
  • Purpose:  This method generates the token for reset. 
  • Parameters:  options - a javascript object with the following properties:
    • authenticationProvider - an optional property that states what authentication provider this request is for.  This should be the lookup name of the provider.
    • data - a javascript object that has properties and values necessary to generate a password reset request.  For Web Users the default required properties are:
      • username - the Web User userid 
      • email - the email address associated with the Web User record for the userid
        
        
  • Returns: a promise that resolves when the reset request has completed. 
  • Important:  the promise for this object almost always resolves, even if there is no username email combination that matches in the system.  This is to prevent using this end point as an attack vector.  An appropriate message to generate back to the user would be along the lines of 'Your request has been submitted. If your userid and email matches you will receive an email to reset your password shortly.  If you do not receive this email contact support.'  Errors with this request are logged on the server.
     

  For example:

  Aptify.framework.utility.passwordResetRequest({
        data:  {
               username: "webuser1",
               email:  "some.user@aptify.com"
        }
  }); 

• Aptify.framework.utility.passwordReset(options)
  • Purpose: This method changes a user's password
  • Parameters:  options - a javascript object with the following properties:
    • authenticationProvider - an optional property that states what authentication provider this request is for.  This should be the lookup name of the provider.
    • data - a Javascript object that has properties and values necessary to change the user's password.  For Web Users the default required properties are:
      • token - the token generated for the Password Reset Request record.
      • userid - the Web User userid this token is for
      • password - the new password
        
        
  • Returns:  a promise that resolves if the password change is successful, and rejects if otherwise.  If the password change was rejected due to password requirements, the rejection will be a javascript object that contains the error messages generated by the Password Requirements Provider plugins that failed. 
     

  For example:

  Aptify.framework.utility.passwordReset({
         data:  {
                username: "webuser1",
                password:  "babyappleowlface",
                token:  "585d441a-b890-48fd-a779-d8a34c03b367"
                }
  });