Skip to content

Security Layers: Deep Dive

AuthForge follows a "Defense in Depth" strategy. Each layer is designed to solve a specific security problem while remaining highly customizable.

🕵️ 1. Anomaly Detection (Risk Scoring)

What is it?

The Anomaly Detection engine evaluates every login attempt against a set of historical and geographic rules. It assigns a Risk Score (0-100) to the login.

Why is it used?

Stolen passwords are the #1 cause of data breaches. Even if an attacker has a valid password, their login behavior (wrong country, weird time, new device) will trigger a high risk score, allowing the system to block them or force MFA.

Customization:

  • Toggle: Enable/Disable via security.anomaly_detection_enabled in authforge.yaml.
  • Rules: You can customize the scoring weights (e.g., making "Impossible Travel" worth 100 instead of 80) by overriding the run_anomaly_detection service.
  • Thresholds: You can choose what to do with the score in your application logic (e.g., score > 70 = Force MFA, score > 90 = Block).

💻 2. Device Fingerprinting

What is it?

It is a technology that identifies a user's browser and hardware without relying solely on cookies. It uses headers, IP metadata, and browser attributes to create a unique ID.

Why is it used?

It allows the system to distinguish between a "Known Device" (safe) and a "New Device" (untrusted). It is the backbone of the Anomaly Detection system.

Customization:

  • Trust Lifecycle: You can implement your own "Trust this device" button using the provided /auth/devices/{id}/trust endpoint.
  • Storage: Metadata is stored in the device_fingerprints table, allowing you to audit all devices used by a user.

🔐 3. Step-Up Authentication

What is it?

Step-up auth requires a user with a valid session to re-verify their identity (via password or MFA) before performing a high-privilege action.

Why is it used?

It prevents "Unlocked Laptop" attacks. If a user leaves their session open, an attacker cannot delete data or change billing settings without the user's password.

Customization:

  • Timer: You can customize how long a "Step-Up" remains valid. Use the @auth.step_up_required(valid_window_minutes=15) decorator.
  • Scopes: You can define different windows for different actions.

🔨 4. Brute-Force Protection

What is it?

A defensive mechanism that tracks failed attempts and imposes cooling-off periods or invalidates tokens.

Why is it used?

It stops automated "bots" from guessing passwords or trying to brute-force a password reset link.

Customization:

  • Limits: Change the maximum attempts (default: 5) via security.max_login_attempts.
  • Lockout Time: Adjust the penalty duration via security.lockout_minutes.
  • Token Security: Password reset tokens are automatically destroyed after 5 failed guesses—this behavior is fixed for maximum security.