Authentication Guide

Last Updated: 2026-01-14 Status: Implemented Plan Reference: 003-authentication-system.md, 114-marketing-site.md

Overview

The authentication system provides secure user login, registration, password management, email verification, and two-factor authentication (2FA). Built on Laravel Breeze with multi-domain support, all authentication happens at the marketing site (scopeforged.com) with role-based redirects to the appropriate subdomain:

• Admin users → admin.scopeforged.com
• Client users → portal.scopeforged.com

Sessions are shared across all subdomains via SESSION_DOMAIN=.scopeforged.com.

Table of Contents

1. Accessing Authentication
2. Features
3. How to Use
4. Two-Factor Authentication
5. Technical Architecture
6. Related Features

Accessing Authentication

Public Routes (Guest Only) - Marketing Domain

All authentication routes are hosted on the marketing domain (scopeforged.com):

Authenticated Routes

Features

Core Authentication

• Login: Email/password authentication with "Remember Me" option
• Logout: Secure session termination
• Registration: New user signup (defaults to client role)
• Password Reset: Email-based password recovery
• Email Verification: Verify email addresses before full access

Security Features

• Two-Factor Authentication: TOTP-based 2FA with recovery codes
• Rate Limiting: Throttling on sensitive endpoints
• Session Management: Secure session handling
• Password Confirmation: Re-confirm password for sensitive actions

Role-Based Redirects

After login at scopeforged.com/login, users are redirected based on their role:

• Admin users → admin.scopeforged.com (Admin Dashboard)
• Client users → portal.scopeforged.com (Client Portal Dashboard)

Unauthenticated Access Handling

When an unauthenticated user attempts to access protected routes:

• Portal routes (portal.scopeforged.com/*) → Redirect to scopeforged.com/login
• Admin routes (admin.scopeforged.com/*) → Redirect to scopeforged.com/login

This is configured in bootstrap/app.php:

$middleware->redirectGuestsTo(fn () => marketing_url('/login'));

How to Use

Logging In

1. Navigate to /login
2. Enter your email address
3. Enter your password
4. Optionally check "Remember me" to stay logged in
5. Click "Log in"
6. If 2FA is enabled, enter your authentication code
7. You'll be redirected to your dashboard

Registering a New Account

1. Navigate to /register
2. Enter your name
3. Enter your email address
4. Create a password (min 8 characters)
5. Confirm your password
6. Click "Register"
7. Check your email for verification link
8. Click the verification link to activate your account

Resetting Your Password

1. Navigate to /forgot-password
2. Enter your email address
3. Click "Email Password Reset Link"
4. Check your email for the reset link
5. Click the link and enter your new password
6. Confirm the new password
7. Click "Reset Password"

Updating Your Password

1. Log in to your account
2. Navigate to your profile settings
3. Enter your current password
4. Enter your new password
5. Confirm the new password
6. Click "Update Password"

Two-Factor Authentication

Enabling 2FA

1. Navigate to /two-factor
2. Click "Enable Two-Factor Authentication"
3. Scan the QR code with your authenticator app (Google Authenticator, Authy, etc.)
4. Enter the 6-digit code from your app
5. Save your recovery codes in a secure location

Using 2FA at Login

1. Enter your email and password
2. You'll be redirected to the 2FA challenge page
3. Enter the 6-digit code from your authenticator app
4. Or use a recovery code if you don't have access to your app

Disabling 2FA

1. Navigate to /two-factor
2. Click "Disable Two-Factor Authentication"
3. Confirm your password if prompted

Regenerating Recovery Codes

1. Navigate to /two-factor
2. Click "Regenerate Recovery Codes"
3. Save the new codes in a secure location
4. Old codes will no longer work

Technical Architecture

Controllers

Marketing Domain (Primary Auth)

Legacy Breeze Controllers (for 2FA and email verification)

Routes Summary

# Guest Routes
GET|POST /login              - Login
GET|POST /register           - Registration
GET|POST /forgot-password    - Password reset request
GET|POST /reset-password     - Password reset

# Authenticated Routes
POST     /logout             - Logout
GET      /verify-email       - Verification notice
GET      /verify-email/{id}  - Verify email
POST     /email/verification-notification - Resend verification
GET|POST /confirm-password   - Password confirmation
PUT      /password           - Update password

# Two-Factor Routes
GET      /two-factor         - 2FA settings
POST     /two-factor/setup   - Enable 2FA
POST     /two-factor/confirm - Confirm 2FA setup
DELETE   /two-factor         - Disable 2FA
POST     /two-factor/regenerate-codes - New recovery codes
GET|POST /two-factor-challenge - 2FA login challenge

Database Tables

Key User Model Methods

// Check if user is admin
$user->isAdmin(): bool

// Check if user is client
$user->isClient(): bool

// Check if email is verified
$user->hasVerifiedEmail(): bool

Middleware

Related Features

Dependencies

Complementary Features

Configuration

Environment Variables

# Session Configuration
SESSION_DRIVER=database
SESSION_LIFETIME=120

# Mail Configuration (for verification/reset emails)
MAIL_MAILER=smtp
MAIL_HOST=smtp.example.com
MAIL_PORT=587
MAIL_USERNAME=your-username
MAIL_PASSWORD=your-password
MAIL_FROM_ADDRESS=noreply@example.com
MAIL_FROM_NAME="${APP_NAME}"

Security Settings

• Password minimum: 8 characters
• Login throttle: 5 attempts per minute
• 2FA throttle: 5 attempts per minute
• Session lifetime: 120 minutes (configurable)
• Remember me: 2 weeks

Troubleshooting

See Also

• Authorization Guide - Role-based access control
• Security Guide - Security best practices
• Mail & Notifications - Email configuration