How We Roll – Chapter 1: Passwords

Welcome to How We Roll! This series is meant to help product owners, developers, and security professionals understand exactly how we implement (or, roll) authentication at Clerk.

Many consider passwords to be the "original" form of authentication. They have been used in software since long before the internet existed and are championed for their ease-of-use.

Despite being such a common authentication strategy, implementing passwords is a surprisingly complex task. Decades of trial-and-error have taught us best practices for:

Let's learn how Clerk handles it all!

Users can choose passwords in three different scenarios: signing up, changing their password, and resetting their password.

In each scenario, Clerk presents the password field:

This field is designed to provide feedback as the user types, and offers three variants of feedback:

As with every authentication factor, we first referenced NIST 800-63B to determine our password requirements. The National Institute of Standards and Technology (NIST) maintains this document specifically to help authentication professionals maintain the security of digital accounts.

There, we learned that 8 characters is the optimal minimum password length, and so we apply this requirement across every Clerk application.

NIST guidance also states that passwords which have been breached should not be used again. Password database leaks are unfortunately all-too-common, and many of those databases store passwords in an unsafe manner.

As a result, billions of passwords have been breached and cannot be used again. To determine whether a password can be used, Clerk leverages the well-maintained corpus from Have I Been Pwned.

Though it's not suggested by NIST, we implement zxcvbn to measure password strength as a user types. zxcvbn is a battle-tested complexity estimation algorithm, originally developed within Dropbox.

We allow developers to enforce a minimum level of complexity (low, medium, or high), as determined by zxcvbn.

Within Clerk's dashboard, developers can customize the requirements for users choosing a password:

Although not recommended because they frustrate users and because NIST advises against them, this screenshot shows how Clerk also allows LUDS-based password strength requirements (lowercase, uppercase, digits, symbols).

When changing or resetting passwords, we help users keep their accounts secure with two requirements:

Here's an example in Clerk's forgot password flow:

We use the industry-standard, one-way password hashing function called bcrypt to hash passwords before they are saved to our database. This is essential to prevent passwords from being leaked, even in the unlikely event that Clerk's database leaks.

Counterintuitively, bcrypt adds security by being computationally expensive. Trying to break a bcrypt hash by brute-force is impractical, because it would cost too much money (e.g. trying every possible combination of characters).

Although bcrypt is the standard today, it's important to recognize that the standard changes with some regularity. We monitor those changes and will update our preferred strategy as needed.

Although bcrypt is our preferred hashing algorithm, we support importing passwords that previously used a wide variety of alternative hashing algorithms, like argon2, scrypt, and pbkdf2_sha256.

These hashes will stay in their original format until the user signs in again with their password. At that time, we will replace the hash to use bcrypt going forward. This ensures that even if passwords are migrated from a weaker format, they are continually upgraded to a modern best-practice.

Though simple in concept, implementing passwords for authentication is a complex task. Clerk's components and APIs offer best practices in security and user experience out-of-the-box, so developers can stop worrying about authentication and focus on what truly differentiates their business.