Getting Started Tutorial

Step-by-step guide to set up and use the Laravel 2FA authentication system

Prerequisites

System Requirements

  • PHP 8.1 or higher
  • Laravel 12.x
  • MySQL 8.0 or higher
  • Composer
  • Node.js & NPM (for frontend assets)

Required Knowledge

  • Basic Laravel framework knowledge
  • Understanding of authentication concepts
  • Familiarity with API development
  • Basic understanding of 2FA/TOTP

Installation Steps

1

Clone and Setup

Clone Repository

git clone https://github.com/your-repo/laravel-2fa.git
cd laravel-2fa

Install Dependencies

composer install
npm install
2

Environment Configuration

Copy Environment File

cp .env.example .env
php artisan key:generate

Configure Database

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=laravel_2fa
DB_USERNAME=root
DB_PASSWORD=

Generate 2FA Encryption Keys

Important Security Note

Generate secure random keys for 2FA encryption. You can use these commands:

# Generate encryption key (32 bytes)
openssl rand -base64 32

# Generate initialization vector (16 bytes)
openssl rand -base64 16
3

Database Setup

Run Migrations

php artisan migrate

Seed Test Data

php artisan db:seed

Test User Credentials

Default Test User

Email: test@example.com

Password: password

4

Start Development Server

Start Laravel Server

php artisan serve

Build Frontend Assets

npm run dev
Open Application

Using the Application

User Authentication Flow

1

Login

Navigate to the login page and enter your credentials. Use the test user: test@example.com / password

2

Dashboard Access

After successful login, you'll be redirected to the dashboard where you can manage your account

3

2FA Setup

Click "Setup 2FA" to enable two-factor authentication. This will generate a QR code for your authenticator app

4

QR Code Scanning

Use Google Authenticator, Authy, or any TOTP app to scan the QR code

5

Verification

Enter the 6-digit code from your authenticator app to confirm 2FA setup

6

Protected Access

Now when you log in, you'll need to enter a 2FA code to access protected areas

Testing the API

Login via API

curl -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@example.com",
    "password": "password"
  }'

Get User Info

curl -X GET http://localhost:8000/api/auth/user \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

2FA Setup via API

curl -X POST http://localhost:8000/api/2fa/setup \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Troubleshooting

Common Issues

QR Code Not Working

Ensure the endroid/qr-code package is installed and the GD extension is enabled in PHP.

TOTP Code Invalid

Check that your device's time is synchronized. TOTP codes are time-sensitive.

Encryption Errors

Verify that your 2FA encryption keys are properly set in the .env file.

Debug Commands

Check Configuration

php artisan config:cache
php artisan route:clear

Database Status

php artisan migrate:status

Log Files

tail -f storage/logs/laravel.log

Next Steps

Customize

Modify the code to fit your specific requirements and branding

Deploy

Deploy to production with proper security configurations

Documentation

Read the full documentation for advanced features

Full Documentation API Reference