# 2FA Trusted IP Setup Guide

## Overview

This guide explains how to configure trusted IP addresses that automatically bypass 2FA verification for users connecting from office networks, VPNs, or other trusted locations.

## Quick Setup

### 1. Add Trusted IPs to Environment

Add these variables to your `.env` file:

```env
# Trusted IP Addresses (bypass 2FA)
# Format: Comma-separated list of IPs or CIDR ranges
TWO_FACTOR_TRUSTED_IPS=192.168.1.100,192.168.1.0/24,10.0.0.0/8

# Enable or disable IP bypass (default: true)
TWO_FACTOR_ENABLE_IP_BYPASS=true
```

### 2. Configuration Examples

#### Single IP Address
```env
TWO_FACTOR_TRUSTED_IPS=192.168.1.100
```

#### Multiple IP Addresses
```env
TWO_FACTOR_TRUSTED_IPS=192.168.1.100,192.168.1.101,10.0.0.50
```

#### CIDR Ranges (Recommended for Networks)
```env
# Office network (192.168.1.0 to 192.168.1.255)
TWO_FACTOR_TRUSTED_IPS=192.168.1.0/24

# VPN network (10.0.0.0 to 10.255.255.255)
TWO_FACTOR_TRUSTED_IPS=10.0.0.0/8

# Multiple networks
TWO_FACTOR_TRUSTED_IPS=192.168.1.0/24,10.0.0.0/8,172.16.0.0/12
```

#### IPv6 Support
```env
# Single IPv6 address
TWO_FACTOR_TRUSTED_IPS=2001:db8::1

# IPv6 CIDR range
TWO_FACTOR_TRUSTED_IPS=2001:db8::/32
```

### 3. Clear Configuration Cache

After updating your `.env` file, clear Laravel's configuration cache:

```bash
php artisan config:clear
```

## How It Works

1. **Authentication**: User logs in with username/password (or OAuth)
2. **IP Check**: System checks if the user's IP is in the trusted list
3. **Bypass**: If trusted, 2FA verification is skipped
4. **Logging**: All bypass events are logged for security auditing
5. **Session**: User is marked as 2FA-verified for the session duration

## Use Cases

### Office Network
Configure your office's IP range to automatically bypass 2FA for users physically in the office:

```env
# Office subnet
TWO_FACTOR_TRUSTED_IPS=192.168.0.0/24
```

### VPN Users
For users connecting via VPN, add the VPN's IP range:

```env
# VPN network
TWO_FACTOR_TRUSTED_IPS=10.0.0.0/8
```

### Multiple Locations
Combine multiple networks:

```env
# Office + VPN + Specific servers
TWO_FACTOR_TRUSTED_IPS=192.168.1.0/24,10.0.0.0/8,203.0.113.100
```

## Security Considerations

### ✅ Best Practices

1. **Use Specific Ranges**: Prefer CIDR ranges to specific IPs when possible
2. **Regular Audits**: Review trusted IP list quarterly
3. **Monitor Logs**: Check for unexpected bypass events
4. **Network Security**: Ensure trusted networks are properly secured
5. **Principle of Least Privilege**: Only add networks you fully trust

### ⚠️ Important Warnings

1. **Not for Public Networks**: Never add public or shared WiFi networks
2. **VPN Security**: Only add VPN ranges if your VPN requires authentication
3. **Dynamic IPs**: Static IP ranges are recommended over dynamic
4. **Log Monitoring**: Enable logging and review regularly
5. **Disable When Needed**: Set `TWO_FACTOR_ENABLE_IP_BYPASS=false` to globally disable

## Disabling the Feature

To completely disable IP bypass:

```env
TWO_FACTOR_ENABLE_IP_BYPASS=false
```

Even if trusted IPs are configured, they will be ignored when this is set to `false`.

## Finding Your Office IP Range

### Windows
```bash
ipconfig /all
```
Look for "IPv4 Address" and "Subnet Mask" to calculate your CIDR range.

### Mac/Linux
```bash
ifconfig
```
or
```bash
ip addr
```

### Get Current IP
Visit https://whatismyipaddress.com/ to see your current public IP address.

## Troubleshooting

### IP Not Being Recognized

1. **Clear cache**: `php artisan config:clear`
2. **Check format**: Ensure no extra spaces or characters
3. **Verify IP**: Use `request()->ip()` in logs to see detected IP
4. **Check logs**: Look for "2FA bypassed for trusted IP" messages

### Configuration Not Working

```bash
# Clear all caches
php artisan config:clear
php artisan cache:clear
php artisan route:clear
php artisan view:clear
```

### Testing

Check Laravel logs (`storage/logs/laravel.log`) for messages like:
```
[INFO] 2FA bypassed for trusted IP
```

## Support

For more information, see the full [Two-Factor Authentication documentation](TWO_FACTOR_AUTHENTICATION.md).