Version 3.3 Documentation

Password reset

Overview

Users can set reset their forgotten passwords through the workflow documented in detail below. In short, a password reset link is sent to a user who clicks a link leading to a form that lets the person set his or her new password.

Process

Discussion

  • The process begins when a user realizes that he or she has forgotten the password to a particular frontend application and visits a "Password reset" page in the frontend application

  • The application asks the user for a username, email or either of the two, depending on what value the password_reset.user_search_by entry in sso.conf was set to

  • The credential is passed to Zato SSO which always replies with an OK message to the frontend application. That is, it never tells the frontend application that a username or email were invalid - this is in order to prevent attackers from discovering what usernames or emails are available in the system.

  • If the credential is valid, Zato sends an email to the user with a password link to click to reset. The name of an SMTP connection to use is configured via main.smtp_conn in sso.conf. The link contains a token which is a one-time use secret that can be used to reset the

  • The token is considered expired after sso.conf's password_reset.valid_for minutes. By default, it is 1440 minutes = 24 hours.

  • The email template is read from a file under the path of /path/to/server/config/repo/static/sso/email//password-rest-link.txt. If no preferred language is selected for the user, en_GB is used.

  • The user clicks the link received which leads to the frontend application. The frontend sends the token from the link to Zato SSO which checks if the token and user are valid.

  • If the token is invalid, e.g. it does not exist or has been previously visited, an error is returned to the frontend application.

  • If the token is valid but the user is not allowed to access SSO, e.g. the account has been locked in the meantime, an error is returned as well.

  • If both token and user are valid, the token is marked in the database as having been used and an OK status is returned to the frontend along with a reset key.

  • The reset key is a random string that can be used only once, during this very particular password reset attempt.

  • The frontend asks the user for a new password and sends to SSO all of the three: token, reset key and a new password.

  • SSO validates the token, reset key and whether the user is still allowed to access the system. If they are valid, the password is also validated according to the sso.conf's password complexity rules.

  • If the validation step fails because the token or reset key are invalid, the frontend receives error code E010001.

  • If the validation step fails because the user is rejected, the frontend receives error code E005001.

  • If the validation step fails because the password does not matches the complexity expectations, the frontend received an error code different than the two above.

  • If the validation step succeeds, the password is changed and the token and reset key are marked in the database as already used

    • Notes

    • The password-rest-link.txt template can be modified directly in the file system, without server restarts.

    • Tokens and reset keys are never deleted from the database.

    • For both tokens and reset keys, additional information is kept in the database - from what remote address they were accessed and what the user agent was. This information is not available through any API call.

    • A token can be accessed only once, i.e. it is not possible to click the same password reset link multiple times.

    • Because the token can be accessed only once, the reset key returned when the token was accessed, is guaranteed not to be returned to any other caller using the same token

    • The reset key can be sent to SSO as many times as it is needed to change the password for as long as the reset key does not expired along with the token. E.g. when a user enters a password that is too simple, SSO will return an error message and the user can be given another chance to enter a stronger password which means sending the token, reset key and the new password once more, until the password is expected (or the token and reset key expire).

    API calls summary

    • Frontend application invokes three endpoints or services:

    • First, to generate a token and send an email with a link - the link contains the token

    • Then, to validate the token from the clicked link and to generate a reset key
    • Finally, the password based on the token, reset key and a new password provided by the user

    Other ways to change a user's password

    • Passwords can be changed through REST, Python and from command line
    • Furthermore, it is possible to reset one's password from command line - a new strong one (192 bits) will be generated and printed to stdout