When users forget their passwords, they start the password reset process by entering their email address into a form. This form should be simple and clear, guiding users to input the email address associated with their account.
\nOnce the email is submitted, the backend checks if the email exists in the database. Regardless of whether the email exists or not, the system should display a message stating that an email has been sent. This prevents attackers from determining if an email address is valid.
\nIf the email exists, a new password reset token is generated. Using a secure random source, the token should be a long (at least 64 characters) random string to prevent brute force attacks.
\nThe generated token is then hashed using SHA-256 and stored in the database along with the user’s ID and an expiration time. This ensures that the token is only valid for a limited period, mitigating the risk of attacks using expired tokens. Here’s an example schema for storing password reset tokens:
\nCREATE TABLE password_reset_tokens (\n user_id VARCHAR(36) NOT NULL,\n token VARCHAR(128) NOT NULL UNIQUE,\n token_expiry BIGINT UNSIGNED NOT NULL,\n PRIMARY KEY (user_id, token)\n);A password reset link containing the token is sent to the user’s email address. The link should redirect the user to a secure page on the website where they can enter their new password. An example link might look like this:
\nhttps://example.com/reset-password?token=<Token here>When the user clicks the link and submits the new password, the backend verifies the token. If the token’s hash matches the one stored in the database and it hasn’t expired, the user’s password is updated. Here’s a pseudo code example of the backend logic:
\nfunction redeemToken(passwordResetToken, newPassword) {\n hashedToken = hash_sha256(passwordResetToken);\n rowFromDb = db.getRowTheContains(hashedToken);\n if (rowFromDb == null) {\n throw Error(\"Invalid password reset token\");\n }\n userId = rowFromDb.user_id;\n\n db_startTransaction(() => {\n allTokensForUser = db_getAllTokensBasedOnUser(userId);\n\n matchedRow = allTokensForUser.find(row => row.token == hashedToken);\n if (matchedRow == null) {\n throw Error(\"Invalid password reset token\");\n }\n\n if (matchedRow.token_expiry < time_now()) {\n db_rollback();\n throw Error(\"Token has expired. Please try again\");\n }\n\n db_deleteAllRowsForUser(userId);\n\n hashedAndSaltedPassword = hashAndSaltPassword(newPassword);\n db_saveNewPassword(userId, hashedAndSaltedPassword);\n db_commitTransaction();\n });\n}This is a common threat for all web applications. Attackers may attempt to detect patterns in the password reset tokens - like if it’s derived from a user’s userId, time they signed up, their email or any other information. Attackers may also try all possible combinations of letters and numbers (brute force), and may even succeed if the generated tokens are not long or random enough (i.e. have low entropy).
\nSolution: Generate tokens using a secure random source and ensure they are long enough to be unguessable. Implement rate limiting to prevent repeated attempts.
\nThere are several ways an attacker can gain access to an application’s database: SQL injection attacks, targeting unpatched database vulnerabilities, and exploiting unused database services. They could even gain access if someone hasn’t updated the default login credentials.
\nWhile there are plenty of problems with an attacker getting database access, one of them is their ability to get users’ password reset tokens, like in this research on Paleohacks. To mitigate this risk, we store only the hashed version of tokens in the database. Passwords are hashed and stored and it’s important that password reset tokens are too (for the same reasons).
\nAnother related attack vector is the use of JWTs as the password reset token. Whilst this makes development easy, a major risk is that if the secret key used to sign them is compromised, the attacker can use that to generate their own valid JWT. This would allot them to reset any user’s password. The JWT secret key (or signing key) must be carefully protected and hence we do not recommend using JWTs as the password reset token.
\nFor simplicity of development, it may be tempting to store a “static” password reset token per user. This token might be randomly generated on user sign up, or based on their password’s hash or some other information.
\nThis in turn implies that these tokens cannot be stored in a hashed form in the database - since we will need to send this token over email (because if we hash it, we can’t unhash it at the time). Therefore, if the database is compromised, these tokens can be used to reset a user’s password.
\nAnother risk of reusing tokens is that if a token somehow gets leaked, even if it has been redeemed by the actual user, it can still be used by an attacker to change that user’s password.
\nWhat actually happens on the backend (pseudo code)
\nApplications need to account for the frequency with which users forget their passwords. This opens a potential attack vector because anyone can request a new password on behalf of the legitimate user. Resetting a password requires sending a token to a user’s email address and this provides an opening for attackers. Making sure you have a secure process for handling the password reset tokens will ensure your users’ accounts remain safe from attackers.
\nThis is a common threat for all web applications. Attackers may attempt to detect patterns in the password reset tokens - like if it’s derived from a user’s userId, time they signed up, their email or any other information. Attackers may also try all possible combinations of letters and numbers (brute force), and may even succeed if the generated tokens are not long or random enough (i.e. have low entropy).
\nTo prevent this, we must ensure that tokens are generated using a secure random source, and that they are long enough (we recommend >= 64 characters). Later on in this blog, we will see one such method.
\nThere are several ways an attacker can gain access to an application’s database: SQL injection attacks, targeting unpatched database vulnerabilities, and exploiting unused database services. They could even gain access if someone hasn’t updated the default login credentials.
\nWhile there are plenty of problems with an attacker getting database access, one of them is their ability to get users’ password reset tokens, like in this research on Paleohacks. To mitigate this risk, we store only the hashed version of tokens in the database. Passwords are hashed and stored and it’s important that password reset tokens are too (for the same reasons).
\nAnother related attack vector is the use of JWTs as the password reset token. Whilst this makes development easy, a major risk is that if the secret key used to sign them is compromised, the attacker can use that to generate their own valid JWT. This would allot them to reset any user’s password. The JWT secret key (or signing key) must be carefully protected and hence we do not recommend using JWTs as the password reset token.
\nFor simplicity of development, it may be tempting to store a “static” password reset token per user. This token might be randomly generated on user sign up, or based on their password’s hash or some other information.
\nThis in turn implies that these tokens cannot be stored in a hashed form in the database - since we will need to send this token over email (because if we hash it, we can’t unhash it at the time). Therefore, if the database is compromised, these tokens can be used to reset a user’s password.
\nAnother risk of reusing tokens is that if a token somehow gets leaked, even if it has been redeemed by the actual user, it can still be used by an attacker to change that user’s password.
\nImplementing a secure password reset flow requires attention to detail and a thorough understanding of security best practices. By generating secure tokens, storing them safely, and using additional authentication measures, you can protect your users’ accounts from common threats. At SuperTokens, we provide easy-to-use, open-source authentication solutions to help you secure your applications and save development time.
","frontmatter":{"date":"July 13, 2024","title":"How to Implement a Forgot Password Flow? Complete Guide","cover":"implementing-a-forgot-password-flow.png","author":"Joel Coutinho","description":"What should happen on the backend when a user forgets their password? Read to find a pseudo code implementation of the simplest way to reset passwords securely."},"fields":{"slug":"/implementing-a-forgot-password-flow/"}},"site":{"siteMetadata":{"title":"SuperTokens Blog"}}},"pageContext":{"id":"ad480c67-67de-5ee7-afbf-085ae0f55186","fields__slug":"/implementing-a-forgot-password-flow/","__params":{"fields__slug":"implementing-a-forgot-password-flow"}}}, "staticQueryHashes": []}