How We Roll – Chapter 1: Passwords

Category: Company
Published: May 19, 2023

How We Roll is a deep-dive into how Clerk implements authentication. In this first chapter, we discuss passwords – the original form of authentication.

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.

Chapter 1: Passwords

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:

Choosing passwords
Changing passwords
Storing passwords
Migrating passwords

Let's learn how Clerk handles it all!

Choosing passwords

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.

2. Password has been breached

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.

3. Password is too weak

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.

Customizing requirements

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).

Changing passwords

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

The user must authenticate first, including with multifactor authentication if it is enabled on their account. The helps prevent attackers from claiming an account they discover is signed-in on a public device.
The user must be given the option to sign out of other devices. This stops attackers who may already have access to an account.

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

Storage

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.

Migrations

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.

Summary

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.