Skip to content

Passwords

David Ciulla edited this page Nov 7, 2026 · 1 revision

Resetting Passwords

Laravex includes a full password-reset flow through Laravex.Auth.Password. Secure tokens are stored in the password_reset_tokens table and expire after a configurable window.

Configuration

# config/auth.exs
%{
  "passwords" => %{
    "users" => %{
      "provider" => "users",
      "table"    => "password_reset_tokens",
      "expire"   => 60,    # minutes before token expires
      "throttle" => 60     # seconds before another reset link can be requested
    }
  }
}

The password_reset_tokens table is created by the default migration (0001_01_01_000000_create_users_table.ex):

# database/migrations/0001_01_01_000000_create_users_table.ex
{:create, "password_reset_tokens", [
  {:string, "email", primary: true},
  {:string, "token"},
  {:timestamp, "created_at", nullable: true}
]}

Sending the Reset Link

case Laravex.Auth.Password.send_reset_link(%{"email" => email}) do
  :sent      -> # link emailed — redirect with status message
  :throttled -> # another link was recently sent — tell the user to wait
  :user      -> # email not found — respond the same as :sent to avoid enumeration
end

Internally send_reset_link/1:

  1. Looks up the user via model.find_by_email/1
  2. Checks the throttle window (default 60 seconds between requests)
  3. Generates a 64-character random token, stores its SHA-256 hash in password_reset_tokens
  4. Sends a Laravex.Auth.ResetPasswordNotification via Laravex.Notifications.Notifier

The plain-text token is embedded in the reset URL:

https://example.com/reset-password/<token>?email=user%40example.com

Resetting the Password

credentials = %{
  "email"    => request.params["email"],
  "token"    => request.params["token"],
  "password" => request.params["password"]
}

case Laravex.Auth.Password.reset(credentials) do
  :reset -> # success — redirect to login with confirmation
  :token -> # invalid or expired token
  :user  -> # user not found
end

reset/1:

  1. Validates that all three fields are present
  2. Verifies the token against the stored hash using constant-time comparison
  3. Checks the token has not expired (expire minutes from created_at)
  4. Hashes the new password via Hashing (Laravex.Hashing.Hash.make/1)
  5. Saves the new password to the user record
  6. Deletes the used token from password_reset_tokens

Working with the Broker Directly

For multi-broker setups, pass the broker name:

# Named broker
Laravex.Auth.Password.send_reset_link(%{"email" => email}, broker: "admins")

# Manual token lifecycle
token = Laravex.Auth.Password.create_token("user@example.com")
valid? = Laravex.Auth.Password.token_valid?("user@example.com", token)
Laravex.Auth.Password.delete_token("user@example.com")

The broker map contains name, table, expire, throttle, and provider fields derived from config/auth.exs.

Starter Kit Routes

The Starter-Kits command (./artisan install:starter-kit) scaffolds these routes in routes/auth.ex:

Router.get("/forgot-password", &App.Http.Controllers.AuthController.show_forgot/1,
  name: "password.request")

Router.post("/forgot-password", &App.Http.Controllers.AuthController.send_reset/1,
  name: "password.email")

Router.get("/reset-password/{token}", &App.Http.Controllers.AuthController.show_reset/1,
  name: "password.reset")

Router.post("/reset-password", &App.Http.Controllers.AuthController.reset/1,
  name: "password.update")

And the corresponding Blade templates in resources/views/auth/.

Security Notes

  • Tokens are SHA-256 hashed before storage; plain-text tokens never touch the database.
  • Constant-time comparison (:crypto.hash_equals/2) prevents timing attacks.
  • The send_reset_link/1 function returns the same response (:user is treated as :sent in the starter-kit controller) to prevent email enumeration.
  • Tokens expire after expire minutes and are deleted immediately on successful use.

See Also

  • Authentication — Guard.attempt/2 and session login
  • Hashing — Hash.make/1 used to hash the new password
  • Starter-Kits — install:starter-kit for complete auth scaffolding

Clone this wiki locally