Download the PHP package nagibmahfuj/laravel-security-policies without Composer

Laravel Security Policies

A Laravel package that enforces organization-grade security policies:

• Strong session policy
• Password policy (complexity, expiry, history reuse prevention)
• Email-based multi-factor authentication (MFA) with trusted devices

Supports Laravel 8/9/10/11/12 and PHP 8.0+.

Features

• Strong session policy
  • Idle timeout: force logout after X minutes of inactivity
  • Require MFA after X days since last verification
• Password policy
  • Configurable complexity: min length, digits, symbols, lowercase, uppercase
  • Password expiry: require change after X days
  • Password history: restrict reuse of last X passwords
• MFA via email OTP
  • OTP generation, TTL, max attempts, resend
  • Remember/trust device with cookie + DB record

Installation

Install via Composer:

Then dump autoload:

If auto-discovery is not active, register the service provider in config/app.php:

Clear caches if needed:

Publish config

Publish config:

This will create a config/security-policies.php file with default values. You can modify these values as per your requirements. Check below for the configuration options.

Configuration

config/security-policies.php options (grouped):

Session

MFA

MFA Modes

• trusted_only (default)
  • Bypass MFA only if the request contains a trusted device cookie that matches a verified TrustedDevice record within mfa.device_remember_days.
  • If no trusted match exists, user is redirected to MFA verification on every login.
• grace_or_trusted
  • First, the middleware checks for a trusted device as above; if found, bypass MFA.
  • If not trusted, it allows access if the user's user_columns.last_mfa_at is within mfa.grace_days_after_login.
  • Otherwise, redirects to MFA verification.

Device Session Control

When mfa.device_session_control is set to 'single', users can only be logged in on one device at a time. This feature leverages the existing trusted_devices table to track active sessions.

• single_device_action: logout_previous (default)

  • When a user logs in from a new device, all previously trusted devices are automatically invalidated by setting their verified_at timestamp to null.
  • The new device becomes the only active trusted device.

• single_device_action: prevent_new

  • When a user tries to log in from a new device while already logged in elsewhere, the new login attempt is blocked.
  • The user is logged out and redirected to the login page with an error message explaining that single device access is enabled.
• device_session_control: multiple (default)
  • No device restrictions - users can be logged in on multiple devices simultaneously.

Device fingerprinting uses IP address, User-Agent, Accept-Language, and Accept headers to uniquely identify devices. The system automatically tracks device activity and updates last seen timestamps.

Password

User Columns

Publish migrations:

Register middleware aliases in app/Http/Kernel.php

If aliases are not already present, add these to $middlewareAliases:

Add Middlewares

The package registers aliases for convenience. In your route groups, add:

The idle timeout is typically applied to the web group:

Alternatively, use the alias security.idle in specific groups.

Use the Validation Rules

In Laravel 9+, Apply these rules where users set or change passwords:

For Laravel 8 and below, Apply these rules where users set or change passwords:

MFA Routes and Views

The package provides routes:

• GET /mfa/verify: show OTP form
• POST /mfa/verify: verify OTP
• POST /mfa/resend: resend OTP

Views are loaded from the package and can be published/overridden:

Database Schema

• password_histories: user_id, password_hash, timestamps
• mfa_challenges: user_id, code, expires_at, consumed_at, attempts, timestamps
• trusted_devices: user_id, device_fingerprint, user_agent, ip_address, verified_at, last_seen_at, timestamps
• Alters users table (defaults): last_mfa_at, password_changed_at, last_active_at
  • You may rename these columns in your own migrations and set the names via user_columns.* in the config.

Enabling Database Storage for Last Activity

To use database storage for last activity tracking:

1. Ensure your users table has a timestamp column for last activity (default: last_active_at). The published migration will add this if needed.

2. Set the following in config/security-policies.php:

3. The middleware will now track last activity in the database instead of the session.

Events & Listeners

• Listens to Illuminate\Auth\Events\PasswordReset
  • Stores the updated hashed password into password_histories
  • Sets the configured user_columns.password_changed_at = now()

If you are using a custom password change flow, you can trigger the event manually after updating the password:

Security Considerations

• Ensure mail is properly configured for OTP delivery.
• Consider enabling rate-limiting for the MFA verify/resend endpoints.
• Trusted device cookie is set with a fingerprint; adjust device_remember_days to your risk tolerance.
• Always keep Laravel and dependencies updated.

Testing

• Feature tests can assert middleware redirects when conditions are not met (MFA required, password expired, idle timeout).
• Unit tests for validation rules (StrongPassword, NotInRecentPasswords).

License

MIT License. See LICENSE.