IP Whitelist

Overview

The IP Whitelist module allows you to restrict access to your admin panel to specific IP addresses or ranges. This is a powerful security feature that ensures only connections from trusted locations can access administrative functions, even if someone has valid login credentials.

IP whitelisting is particularly useful for organizations with static IP addresses, remote offices, or situations where you want to limit admin access to specific physical locations.

Accessing IP Whitelist

Navigation path: Dashboard > Security > IP Whitelist

Required permission: security.ip_whitelist.manage

Key Features

• IP Address Management: Add, edit, and remove whitelisted IP addresses
• Flexible Configuration: Support for individual IPs and CIDR ranges
• Temporary Access: Set expiration dates for temporary whitelist entries
• Active/Inactive Toggle: Quickly enable or disable entries without deleting them
• Descriptive Labels: Add labels and descriptions to identify each entry
• Status Tracking: See which entries are active, inactive, or expired
• Creator Attribution: Track who added each whitelist entry

Main Interface

Status Banner

At the top of the page, a banner indicates whether IP whitelisting is currently enabled:

• Green banner: IP whitelisting is active
• Yellow banner: IP whitelisting is disabled (configure in Security Settings)

IP Whitelist Table

The main table displays all whitelist entries with the following columns:

• IP Address: The whitelisted IP address or range (displayed in monospace font)
• Label: Descriptive name for the entry
• Status: Current status (Active, Inactive, or Expired)
• Expires: Expiration date/time, or "Never" for permanent entries
• Created By: User who added this entry
• Actions: Activate/Deactivate, Edit, and Delete buttons

Status Badges

• Green (Active): Entry is currently active and not expired
• Red (Expired): Entry has passed its expiration date
• Gray (Inactive): Entry is manually deactivated

Common Tasks

Task 1: Adding Your Current IP Address

1. Navigate to Dashboard > Security > IP Whitelist
2. Click Add IP Address button
3. The form will pre-fill with your current IP address
4. Enter a Label (e.g., "My Home Office")
5. Optionally, add a Description with more details
6. Leave Expires At empty for permanent access
7. Ensure Active is checked
8. Click Add to Whitelist

Result: Your current IP address is whitelisted and you can access the admin panel from this location.

Important: Always add your current IP before enabling IP whitelisting to avoid locking yourself out.

Task 2: Adding a Specific IP Address

1. Navigate to Dashboard > Security > IP Whitelist
2. Click Add IP Address
3. Replace the pre-filled IP with the desired IP address
   • Example: 203.0.113.50
4. Enter a descriptive Label
   • Example: "Office Network"
5. Add a Description if needed
   • Example: "Main office static IP address"
6. Set Expires At if this is temporary access
7. Ensure Active is checked
8. Click Add to Whitelist

Result: The specified IP address can now access the admin panel.

Task 3: Adding an IP Range (CIDR Notation)

1. Navigate to Dashboard > Security > IP Whitelist
2. Click Add IP Address
3. Enter an IP range in CIDR notation
   • Example: 192.168.1.0/24 (allows 192.168.1.0 through 192.168.1.255)
   • Example: 203.0.113.0/28 (allows 16 addresses)
4. Enter a Label
   • Example: "Office Network Range"
5. Add a Description
   • Example: "Entire office subnet"
6. Click Add to Whitelist

Result: All IP addresses in the specified range can access the admin panel.

CIDR Examples:

• /32 = Single IP (e.g., 192.168.1.1/32)
• /24 = 256 addresses (e.g., 192.168.1.0/24)
• /16 = 65,536 addresses (e.g., 192.168.0.0/16)

Task 4: Adding Temporary Access

1. Navigate to Dashboard > Security > IP Whitelist
2. Click Add IP Address
3. Enter the IP address
4. Enter a Label
   • Example: "Contractor - John Doe"
5. Set Expires At to the desired end date/time
   • Example: One week from now
6. Click Add to Whitelist

Result: The IP address has access until the expiration date, then automatically becomes inactive.

Use Cases:

• Temporary contractor access
• Guest administrator access
• Time-limited remote access
• Testing periods

Task 5: Editing an IP Whitelist Entry

1. Navigate to Dashboard > Security > IP Whitelist
2. Find the entry you want to modify
3. Click Edit in the Actions column
4. Update any fields:
   • IP address
   • Label
   • Description
   • Expiration date
   • Active status
5. Click Update

Result: The whitelist entry is updated with your changes.

Note: Be careful when editing the IP address itself, as you might lock yourself out.

Task 6: Temporarily Disabling an Entry

1. Navigate to Dashboard > Security > IP Whitelist
2. Find the entry you want to disable
3. Click Deactivate in the Actions column
4. The status changes to "Inactive"

Result: The IP address can no longer access the admin panel, but the entry is preserved.

To re-enable:

1. Click Activate in the Actions column
2. The status changes back to "Active"

Task 7: Deleting an IP Whitelist Entry

1. Navigate to Dashboard > Security > IP Whitelist
2. Find the entry you want to remove
3. Click Delete in the Actions column
4. Confirm the deletion in the popup

Result: The IP address is permanently removed from the whitelist.

Warning: If you delete your own IP while whitelisting is enabled, you'll be locked out.

Task 8: Enabling IP Whitelisting

1. Navigate to Dashboard > Security > Settings
2. Scroll to the IP Whitelisting section
3. Add your current IP to the whitelist first (see Task 1)
4. Add any other necessary IP addresses
5. In Security Settings, check Enable IP Whitelist
6. Ensure Admin Only is checked (recommended)
7. Click Save Security Settings

Result: Only whitelisted IP addresses can access the admin panel.

Critical: Always whitelist your current IP before enabling this feature.

Settings and Options

IP Address Field

• Type: Text input
• Format: IPv4, IPv6, or CIDR notation
• Required: Yes
• Examples:
  • IPv4: 203.0.113.50
  • IPv6: 2001:0db8:85a3:0000:0000:8a2e:0370:7334
  • CIDR: 192.168.1.0/24
• Validation: Must be a valid IP address or range

Label Field

• Type: Text input
• Required: Yes
• Purpose: Human-readable identifier
• Examples: "Office Network", "Home IP", "VPN Gateway"
• Best Practice: Use descriptive, meaningful labels

Description Field

• Type: Textarea
• Required: No
• Purpose: Additional context about the entry
• Examples: "Main office static IP - Contact IT if changed"

Expires At Field

• Type: Datetime picker
• Required: No
• Default: Never (permanent)
• Purpose: Automatically deactivate entry after this date/time
• Use Cases: Temporary access, contractor work, testing

Active Checkbox

• Type: Checkbox
• Default: Checked (active)
• Purpose: Enable or disable the entry
• Note: Inactive entries don't grant access but are preserved in the system

Permissions

The following permissions control access to IP whitelist management:

• security.ip_whitelist.view: Can view whitelist entries
• security.ip_whitelist.manage: Can add, edit, and delete entries
• security.ip_whitelist.toggle: Can activate/deactivate entries

Note: Only trusted administrators should have these permissions.

Tips and Best Practices

Before Enabling IP Whitelisting

• Add your current IP address first
• Add all necessary office/remote IPs
• Add localhost (127.0.0.1 and ::1) for local development
• Test access from each location before fully enabling
• Document all whitelisted IPs and their purposes
• Have a backup plan to disable if locked out

IP Address Management

• Use descriptive labels for easy identification
• Document why each IP is whitelisted
• Include contact information in descriptions
• Set expiration dates for temporary access
• Review and clean up old entries regularly
• Keep a separate record of all whitelisted IPs

CIDR Ranges

• Use the smallest range necessary
• /32 for single IPs (most secure)
• /24 for small networks (256 addresses)
• Avoid overly broad ranges like /16 or /8
• Document what each range covers
• Verify ranges don't overlap unnecessarily

Security Considerations

• Only enable if you have static IP addresses
• Dynamic IPs will cause access issues
• Consider using VPN instead for dynamic IPs
• Keep the "Admin Only" option enabled
• Don't whitelist public WiFi or shared IPs
• Monitor audit logs for access attempts

Maintenance

• Review whitelist monthly
• Remove expired or unused entries
• Update IPs when infrastructure changes
• Verify entries are still needed
• Check for duplicate or overlapping ranges
• Document changes in descriptions

Emergency Access

• Keep recovery codes for 2FA
• Have server/database access as backup
• Document how to disable IP whitelisting
• Keep contact info for someone with server access
• Consider a "break glass" emergency IP
• Test recovery procedures before needed

Troubleshooting

Problem: Locked Out After Enabling IP Whitelisting

Solution:

1. Access your server via SSH or control panel
2. Connect to your database
3. Find the settings table
4. Locate the IP whitelist enabled setting
5. Set it to false/disabled
6. Alternatively, add your IP to the whitelist table directly
7. Or temporarily disable the IP whitelist middleware

Prevention: Always add your IP before enabling whitelisting.

Problem: Can't Access from New Location

Solution:

1. Check your current IP address (visit whatismyip.com)
2. Contact an administrator with whitelist access
3. Provide your IP address and reason for access
4. Administrator adds your IP to the whitelist
5. Try accessing again

Alternative: Use VPN to connect from a whitelisted IP.

Problem: Access Works Sometimes But Not Others

Solution:

1. Your IP address might be dynamic (changes periodically)
2. Check if your IP has changed (whatismyip.com)
3. Contact your ISP about getting a static IP
4. Or use a VPN with a static IP
5. Or whitelist a broader range (less secure)
6. Consider disabling IP whitelisting if IPs are too dynamic

Problem: Whitelist Entry Shows as Expired

Solution:

1. Check the expiration date of the entry
2. Click Edit on the entry
3. Either remove the expiration date or set a new one
4. Click Update
5. The entry will become active again

Problem: Can't Add IP Address - Validation Error

Solution:

1. Verify the IP address format is correct
2. For IPv4: Use format like 203.0.113.50
3. For CIDR: Use format like 192.168.1.0/24
4. Remove any spaces or extra characters
5. For IPv6: Use full format or compressed format
6. Check that the IP isn't already in the whitelist

Problem: Entire Office Lost Access

Solution:

1. Check if the office IP changed
2. Contact ISP to verify current IP
3. Have someone with server access add the new IP
4. Or temporarily disable IP whitelisting
5. Update the whitelist entry with the new IP
6. Consider using a static IP from your ISP

Problem: Can't Delete Own IP While Whitelisting is Active

Solution:
This is a safety feature to prevent lockout:

1. Add another IP address first
2. Access from the new IP
3. Then delete the old IP
4. Or temporarily disable IP whitelisting
5. Delete the IP
6. Re-enable whitelisting

Related Modules

• Security Settings: Enable/disable IP whitelisting globally
• Security Events: Monitor blocked access attempts
• Audit Logs: Track whitelist changes
• Users: Manage users who can access from whitelisted IPs