Email/password authentication in Supabase - Deep Dive

Overview - Email/password authentication

What is it?

Email/password authentication is a way for users to prove who they are by entering their email address and a secret password. The system checks if the email exists and if the password matches the stored secret. If both are correct, the user gains access to the service. This method is common because it is simple and familiar to most people.

Why it matters

Without email/password authentication, websites and apps would not know who is using them, making it impossible to protect personal data or provide personalized experiences. It solves the problem of identifying users securely and controlling access. Without it, anyone could access private information or perform actions they shouldn't.

Where it fits

Before learning email/password authentication, you should understand basic user accounts and data storage. After this, you can learn about advanced authentication methods like multi-factor authentication or social logins, and how to secure user sessions.

Mental Model

Core Idea

Email/password authentication is like a locked door that only opens when you provide the right key (password) linked to your unique mailbox (email).

Think of it like...

Imagine your email as your home address and your password as the key to your front door. Only if you have the correct key can you enter your home safely.

┌───────────────┐
│ User enters   │
│ email & pwd   │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ System checks │
│ email exists? │
└──────┬────────┘
       │Yes
       ▼
┌───────────────┐
│ Password      │
│ matches?      │
└──────┬────────┘
       │Yes
       ▼
┌───────────────┐
│ Access       │
│ granted      │
└───────────────┘

Build-Up - 7 Steps

1

Foundation

Understanding user identity basics

Concept: Users need a way to identify themselves uniquely to a system.

Every user has an email address that is unique to them. This email acts like a name tag in the system. To keep accounts safe, users also create a secret password that only they know.

Result

Users have a unique identifier (email) and a secret (password) to prove who they are.

Understanding that email acts as a unique ID helps grasp why it is used to find the right user account.

2

Foundation

How passwords protect accounts

Concept: Passwords are secrets that prove the user owns the email account.

When a user creates an account, they choose a password. The system stores a scrambled version of this password, not the actual one, to keep it safe. When logging in, the system scrambles the entered password and compares it to the stored version.

Result

Passwords protect accounts by requiring knowledge of a secret that only the user should have.

Knowing that passwords are stored securely prevents the false idea that systems keep your real password.

3

Intermediate

How Supabase handles authentication

🤔Before reading on: do you think Supabase stores your password as plain text or encrypted? Commit to your answer.

Concept: Supabase manages user authentication by securely storing password hashes and verifying credentials on login.

Supabase uses a service called GoTrue to handle authentication. When you sign up, your password is hashed (turned into a fixed string) and stored. When you log in, Supabase hashes your entered password and compares it to the stored hash. If they match, you get a session token to access resources.

Result

Users can securely sign up and log in without exposing their real passwords.

Understanding that Supabase never stores plain passwords but hashes them explains how it protects user data.

4

Intermediate

Session tokens and user access

🤔Before reading on: do you think the password is checked every time you use the app after login? Commit to your answer.

Concept: After login, Supabase issues a session token that proves the user is authenticated without rechecking the password each time.

Once logged in, Supabase gives the user a token that acts like a temporary ID card. This token is sent with requests to prove the user is allowed to access data. The password is only checked once during login, making the experience smooth.

Result

Users stay logged in securely without entering their password repeatedly.

Knowing how session tokens work helps understand how apps balance security and convenience.

5

Intermediate

Handling password resets securely

🤔Before reading on: do you think password reset links contain your password? Commit to your answer.

Concept: Password resets use temporary, unique links to let users change passwords without exposing secrets.

If a user forgets their password, Supabase sends a special link to their email. This link is unique and expires after some time. Clicking it lets the user set a new password. This process ensures only the email owner can reset the password.

Result

Users can regain access safely without risking password leaks.

Understanding password reset flows prevents common security mistakes like sending passwords by email.

6

Advanced

Security best practices in email/password auth

🤔Before reading on: do you think using simple passwords is safe if the system is secure? Commit to your answer.

Concept: Strong passwords, hashing, and secure transport protect user accounts from attacks.

Supabase enforces strong password rules and uses bcrypt hashing to protect passwords. All communication happens over encrypted channels (HTTPS). These layers prevent attackers from stealing or guessing passwords easily.

Result

User accounts remain safe even if attackers try to intercept or guess passwords.

Knowing the multiple layers of protection helps appreciate why weak passwords still pose risks.

7

Expert

Behind the scenes: GoTrue and token management

🤔Before reading on: do you think tokens can be reused forever? Commit to your answer.

Concept: GoTrue manages tokens with expiration and refresh mechanisms to balance security and usability.

Supabase's GoTrue issues access tokens that expire after a short time and refresh tokens that last longer. When the access token expires, the refresh token gets a new one without asking the user to log in again. This reduces risk if tokens are stolen and improves user experience.

Result

Users stay logged in securely with automatic token renewal, minimizing password prompts.

Understanding token lifecycles reveals how modern auth systems protect sessions without burdening users.

Under the Hood

When a user signs up, Supabase hashes the password using bcrypt, a slow and secure hashing algorithm, and stores the hash. On login, the entered password is hashed the same way and compared to the stored hash. If they match, GoTrue issues a JSON Web Token (JWT) as an access token and a refresh token. The access token grants access to resources and expires quickly. The refresh token can request new access tokens without re-entering credentials. All tokens are signed to prevent tampering.

Why designed this way?

This design balances security and usability. Hashing passwords prevents exposure if the database leaks. Using JWTs allows stateless session management, reducing server load. Short-lived access tokens limit damage if stolen, while refresh tokens improve user experience by reducing login frequency. Alternatives like storing plain passwords or long-lived tokens were rejected due to security risks.

┌───────────────┐       ┌───────────────┐       ┌───────────────┐
│ User Signup   │──────▶│ Password Hash │──────▶│ Store Hash    │
└───────────────┘       └───────────────┘       └───────────────┘
       │
       ▼
┌───────────────┐       ┌───────────────┐       ┌───────────────┐
│ User Login    │──────▶│ Hash Password │──────▶│ Compare Hash  │
└───────────────┘       └───────────────┘       └───────────────┘
       │ Yes Match
       ▼
┌───────────────┐       ┌───────────────┐       ┌───────────────┐
│ Issue JWT     │──────▶│ Access Token  │──────▶│ Access API    │
│ & Refresh Tok │       │ (Expires Fast)│       │ Resources     │
└───────────────┘       └───────────────┘       └───────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does Supabase store your real password in the database? Commit to yes or no.

Common Belief: Supabase stores my actual password securely in the database.

Reality: Supabase never stores your real password; it stores a hashed version that cannot be reversed to the original password.

Why it matters: Believing passwords are stored as-is leads to false trust and risky behavior like reusing passwords across sites.

Quick: After login, do you think the system checks your password every time you click something? Commit to yes or no.

Common Belief: The system verifies my password every time I use the app after logging in.

Reality: The system only checks your password once at login and then uses tokens to keep you logged in.

Why it matters: Misunderstanding this can cause confusion about session security and token expiration.

Quick: Do password reset links contain your password? Commit to yes or no.

Common Belief: Password reset emails send my password or a new password directly.

Reality: Password reset emails contain a temporary, unique link that lets you set a new password securely.

Why it matters: Thinking passwords are emailed can cause users to distrust reset processes or expose passwords accidentally.

Quick: Is using a simple password safe if the system uses HTTPS? Commit to yes or no.

Common Belief: If the connection is secure, any password is safe to use.

Reality: Even with HTTPS, simple passwords are vulnerable to guessing or database leaks and should be strong.

Why it matters: Weak passwords remain the biggest security risk despite secure connections.

Expert Zone

1

Supabase's use of bcrypt intentionally slows hashing to resist brute-force attacks, balancing security and performance.

2

Refresh tokens are stored securely and can be revoked, allowing fine-grained control over user sessions.

3

Supabase integrates with external identity providers, but email/password remains the foundation for custom user management.

When NOT to use

Email/password authentication is not ideal when users prefer passwordless or social logins for convenience. Alternatives include OAuth providers (Google, Facebook) or magic links that avoid passwords entirely.

Production Patterns

In production, developers combine email/password auth with email verification, rate limiting login attempts, and multi-factor authentication to enhance security. Supabase's built-in hooks allow custom logic on sign-up and login events.

Connections

OAuth 2.0

Alternative authentication method

Understanding email/password auth clarifies why OAuth offers convenience by delegating identity verification to trusted providers.

Hash Functions in Cryptography

Foundational security technique

Knowing how hashing secures passwords helps grasp many security systems beyond authentication.

Physical Security Locks

Similar security principle

Just like a lock and key protect a physical door, authentication protects digital resources, showing security principles apply across domains.

Common Pitfalls

#1 Storing passwords in plain text

Wrong approach:

INSERT INTO users (email, password) VALUES ('[e-mail]', 'mypassword123');

Correct approach:

INSERT INTO users (email, password_hash) VALUES ('[e-mail]', bcrypt('mypassword123'));

Root cause:

Misunderstanding that passwords must be transformed before storage to protect user data.

#2 Not using HTTPS for login pages

Wrong approach:

User submits email and password over http://example.com/login

Correct approach:

User submits email and password over https://example.com/login

Root cause:

Ignoring the need for encrypted communication exposes credentials to attackers.

#3 Allowing weak passwords without checks

Wrong approach:

Accept any password like '1234' or 'password'

Correct approach:

Enforce password rules: minimum length, mix of letters, numbers, symbols

Root cause:

Underestimating the risk of easy-to-guess passwords leads to vulnerable accounts.

Key Takeaways

Email/password authentication uses a unique email and a secret password to identify users securely.

Passwords are never stored as plain text but as hashed values to protect user secrets.

Supabase manages authentication by hashing passwords and issuing tokens for session management.

Tokens allow users to stay logged in without re-entering passwords, balancing security and convenience.

Strong passwords, secure transport, and proper token handling are essential to protect user accounts.