Skip to content

Authentication

David Ciulla edited this page Nov 7, 2026 · 2 revisions

Authentication

Laravex ships a session-based authentication guard that mirrors Laravel's Auth facade. The implementation lives in Laravex.Auth.Guard and leans on Laravex.Session.Store for persistence.

Introduction

Out of the box Laravex provides:

  • A session guard (Laravex.Auth.Guard) that authenticates users via login_web session key
  • Remember-me cookies for persistent login across browser restarts
  • auth and guest middleware aliases wired up in the middleware kernel
  • Bearer-token support delegated to API-Tokens

The user model is resolved from config/auth.exs:

# config/auth.exs
%{
  "defaults" => %{"guard" => "web", "passwords" => "users"},
  "providers" => %{
    "users" => %{"driver" => "eloquex", "model" => "App.Models.User"}
  }
}

Retrieving the Authenticated User

# In a controller action — request is always passed in
user = Laravex.Auth.Guard.user(request)   # returns the struct or nil

id   = Laravex.Auth.Guard.id(request)     # shortcut to user.id
auth = Laravex.Auth.Guard.check?(request) # boolean

Guard.user/1 first checks the process dictionary for an acting_as override (useful in tests), then looks up login_web in the session, and finally falls back to the remember-me cookie.

Attempting Authentication

Guard.attempt/2 takes a credentials map and the current request struct:

credentials = %{
  "email"    => request.params["email"],
  "password" => request.params["password"],
  "remember" => request.params["remember"]   # any truthy value enables remember-me
}

case Laravex.Auth.Guard.attempt(credentials, request) do
  {:ok, user, request} ->
    # session regenerated, user stored
    {:redirect, "/dashboard"}

  {:error, :invalid} ->
    {:render, "auth/login", %{error: "These credentials do not match our records."}}
end

Internally, attempt/2:

  1. Looks up the user by email via model.find_by_email/1
  2. Verifies the password using Hashing (Laravex.Hashing.Hash.check/2)
  3. Rehashes the stored password if needs_rehash?/1 is true (seamless upgrade)
  4. Regenerates the session ID
  5. Writes login_web → user.id into the session
  6. Optionally issues a remember-me cookie

Logging In Manually

If you already have a user struct (e.g., after OAuth or email verification), call Guard.login/2:

request = Laravex.Auth.Guard.login(user, request)

# Or with remember-me:
request = Laravex.Auth.Guard.login(user, request, remember: true)

Login by ID

# Log in by primary key (fetches the model automatically)
{:ok, user, request} = Laravex.Auth.Guard.login_using_id(42, request)
{:ok, user, request} = Laravex.Auth.Guard.login_using_id(42, request, remember: true)
# Returns {:error, :invalid} if no user with that ID exists

Once — Request-only Login

Log a user in for the current request only without touching the session or cookies (useful in tests and single-request contexts):

request = Laravex.Auth.Guard.once(user, request)

Validate Credentials Without Logging In

case Laravex.Auth.Guard.validate_credentials(%{"email" => email, "password" => password}) do
  {:ok, user} -> # credentials are valid
  :error       -> # invalid
end

Guest Check

# Returns true when NO user is authenticated (inverse of check?)
Laravex.Auth.Guard.guest?(request)

Logging Out

request = Laravex.Auth.Guard.logout(request)

logout/1 clears login_web from the session, regenerates the session ID, nullifies the user's remember_token in the database, and expires the remember-me cookie.

Remember Me

When remember: true is passed to attempt/2 or login/3:

  1. A 60-character random token is generated and stored in user.remember_token
  2. The cookie remember_web is set with a one-year lifetime (HTTP-only)
  3. On the next request, Guard.user/1 decodes id|token from the cookie and re-hydrates the user

The cookie value is Base64-encoded "<user_id>|<token>".

Auth & Guest Middleware

The auth and guest middleware aliases are pre-registered in Laravex.Http.Middleware:

# routes/web.ex
Router.group([middleware: ["auth"]], fn ->
  Router.get("/dashboard", &App.Http.Controllers.DashboardController.index/1)
end)

# Guest-only (redirects authenticated users away)
Router.group([middleware: ["guest"]], fn ->
  Router.get("/login", &App.Http.Controllers.AuthController.show_login/1)
end)
Alias Module Behaviour
auth Laravex.Http.Middleware.Authenticate Redirects unauthenticated users to /login; returns 401 JSON for API/AJAX
guest Laravex.Http.Middleware.RedirectIfAuthenticated Redirects authenticated users to /

For stateless API routes, pass auth:api to get JSON 401 responses instead of redirects:

Router.group([middleware: ["auth:api"]], fn ->
  Router.get("/api/profile", &App.Http.Controllers.ProfileController.show/1)
end)

Protecting Routes

You can guard individual routes or entire groups:

# Single route
Router.get("/account", &App.Http.Controllers.AccountController.show/1,
  middleware: ["auth"]
)

# Group
Router.group([prefix: "admin", middleware: ["auth", "can:access-admin"]], fn ->
  Router.get("/", &App.Http.Controllers.Admin.DashboardController.index/1)
end)

Acting As Another User (Testing)

# Temporarily impersonate a user within the current process
Process.put(:laravex_acting_as, user)

# Clear the override
Process.delete(:laravex_acting_as)

See Also

Clone this wiki locally