Passwords

Using passwords to authenticate users is a tried-and-tested method to give your users access to your application. Supabase Auth provides you with secure configuration options and uses best practices to store and verify your user's passwords.

Password security#

A password is more secure if it is harder to guess or brute-force. In theory, a password is harder to guess if it is longer. It is also harder to guess if it uses a larger set of characters (for example, digits, lowercase and uppercase letters, and symbols).

This table shows the minimum number of guesses that need to be tried to access a user's account:

In reality though, passwords are not always generated at random. They often contain variations of names, words, dates, and common phrases. Malicious actors can use these properties to guess a password in fewer attempts.

There are hundreds of millions (and growing!) known passwords out there. Malicious actors can use these lists of leaked passwords to automate login attempts (known as credential stuffing) and steal or access sensitive user data.

Password strength and leaked password protection#

To help protect your users, Supabase Auth allows you fine-grained control over the strength of the passwords used on your project. You can configure these in your project's Auth settings:

• Set a large minimum password length. Anything less than 8 characters is not recommended.
• Set the required characters that must appear at least once in a user's password. Use the strongest option of requiring digits, lowercase and uppercase letters, and symbols.
• Prevent the use of leaked passwords. Supabase Auth uses the open-source HaveIBeenPwned.org Pwned Passwords API to reject passwords that have been leaked and are known by malicious actors.

Additional recommendations#

In addition to choosing suitable password strength settings and preventing the use of leaked passwords, consider asking your users to:

• Use a password manager to store and generate passwords.
• Avoid password reuse across websites and apps.
• Avoid using personal information in passwords.
• Use Multi-Factor Authentication.

Resetting a user's password (forgot password)#

Strong passwords are difficult to remember, so Supabase Auth provides you with APIs to build a secure password reset flow.

Overview#

To add a secure password reset flow to your application:

1. Build the password reset page:
   • Should be publicly accessible and contain a form asking for the user's email address.
   • Use the supabase.auth.resetPasswordForEmail API to request a password reset link for a user's email address.
   • Specify the redirectTo parameter when calling this API to point to the URL of the change password page.
2. Build the password change page:
   • Should be accessible only to authenticated users.
   • Add its URL to the allowed Redirect URLs settings.
   • Show a form or other prompt asking the user to choose a new password.
   • Call the supabase.auth.updateUser API to set a new password for the user.

The email link sent to your users works in the same way as passwordless authentication:

1. After a user visits the reset password page, they are sent a reset password link.
   • If you use PKCE (default), this link only works on the device or browser where the original reset request was made. Display a message to the user to make sure they don't change devices or browsers.
   • If you use the implicit grant flow, the link can be opened on any device.
2. A user clicks the link. They are taken to Supabase Auth, which validates the link.
   • If the link is valid, it redirects to the change password page, which you specified in the redirectTo parameter.
   • If the change password page's URL is not properly registered in the Redirect URLs configuration, the user is taken to the default Site URL page.
3. Supabase Auth redirects to the change password page including session information in the URL.
   • If you used PKCE (default), the redirect contains the code query param.
   • If you are not using official Supabase libraries, or have a custom setup, extract the code from the URL and call the supabase.auth.exchangeCodeForSession API.
   • Official Supabase libraries handle code the code exchange for you.
   • If you used the implicit flow, the redirect contains a URL fragment encoding the user's session.

Example: Request a password reset email#

Example: Updating a user's password#

Frequently asked questions#

How are passwords stored?#

Supabase Auth uses bcrypt, a strong password hashing function, to store hashes of users' passwords. Only hashed passwords are stored. You cannot impersonate a user with the password hash. Each hash is accompanied by a randomly generated salt parameter for extra security.

The hash is stored in the encrypted_password column of the auth.users table. The column's name is a misnomer (cryptographic hashing is not encryption), but is kept for backward compatibility.

How will strengthened password requirements affect current users?#

Existing users can still sign in with their current password even if it doesn't meet the new, strengthened password requirements. However, if their password falls short of these updated standards, they will encounter a WeakPasswordError during the signInWithPassword process, explaining why it's considered weak. This change is also applicable to new users and existing users changing their passwords, ensuring everyone adheres to the enhanced security standards.