Configuring Threat Protection

Auris provides three configurable protection layers that work together in the login security pipeline: IP rules (network-level blocking), suspicious login detection (behavioral analysis), and CAPTCHA (bot mitigation). Each layer operates independently and can be configured to match your security requirements.

This guide walks through the practical setup of each layer and explains how they fit into the full login pipeline.

Protection Layers Overview

All three layers are non-blocking to each other — configuring one does not affect the others.

IP Allow/Block Lists

IP rules use CIDR notation to control which IP addresses can access your tenant’s authentication endpoints.

Rule Types and Precedence

Precedence: BLOCK rules always take priority over ALLOW rules within the same scope. If an IP matches both a BLOCK and an ALLOW rule, it is blocked.

Scope

Rules can be scoped at two levels:

• Tenant scope (scope: TENANT) — applies to all applications under the tenant
• Application scope (scope: APPLICATION) — applies only to a specific application

Application-scoped rules are evaluated after tenant-scoped rules. A tenant-level BLOCK cannot be overridden by an application-level ALLOW.

Setting Up IP Rules

{
  "cidr": "203.0.113.0/24",
  "type": "BLOCK",
  "scope": "TENANT",
  "label": "Known attack source",
  "note": "Blocked after credential stuffing attack on 2025-06-01"
}

{
  "cidr": "198.51.100.42/32",
  "type": "BLOCK",
  "scope": "TENANT",
  "label": "Temporary block - active attack",
  "isTemporary": true,
  "expiresAt": "2025-07-01T00:00:00Z"
}

{
  "cidr": "10.0.0.0/8",
  "type": "ALLOW",
  "scope": "TENANT",
  "label": "Corporate network"
}

Programmatic Management

IP rules can also be managed via the API for automated incident response:

// Block an IP range programmatically after detecting an attack
await fetch('https://auth.yourdomain.com/api/ip-rules', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${adminToken}`,
    'Content-Type': 'application/json',
    'x-tenant': 'your-tenant',
  },
  body: JSON.stringify({
    cidr: '192.0.2.0/24',
    type: 'BLOCK',
    scope: 'TENANT',
    label: 'Automated block - rate limit exceeded',
    isTemporary: true,
    expiresAt: new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString(),
  }),
})

CIDR Quick Reference

Suspicious Login Detection

After a user’s credentials are verified, Auris analyzes the login context for behavioral anomalies using five independent detectors.

Detection Methods

1. New Device

A fingerprint hash is computed from browser user agent, screen resolution, and other stable signals. First-time devices are flagged. The fingerprint is recorded after successful login for future comparison.

2. New IP Address

Auris tracks the IP addresses a user has previously logged in from. A login from an IP not seen for this account triggers the detector.

3. New Country

GeoIP lookup determines the country of the login IP. A country not previously seen in the user’s login history triggers the detector.

4. Impossible Travel

The geographic distance between the current and most recent login is divided by the elapsed time to compute implied travel speed. If the speed exceeds the configured threshold (default: 800 km/h), the login is flagged as impossible travel.

5. VPN / Proxy / Datacenter

GeoIP metadata identifies IPs belonging to known VPN providers, proxies, or cloud datacenters. These are flagged by default but can be allowed for organizations whose users commonly use VPNs.

Configuring Actions

Each detector can be configured independently with one of four actions:

Configure via Console -> Settings -> Suspicious Login Detection:

GeoIP Provider

Reviewing Events

Suspicious login events are visible in Console -> Settings -> Suspicious Login Detection -> Events. Each event shows:

• User email and ID
• Detection reason (new device, impossible travel, etc.)
• Severity (low, medium, high)
• Action taken (logged, notified, blocked, MFA required)
• IP address, country, and device information
• Timestamp

Administrators can mark events as reviewed to track investigation status.

CAPTCHA

CAPTCHA protects login, signup, and password reset pages from automated bots. Auris supports three providers and three trigger modes.

Supported Providers

Trigger Modes

Setup Steps

The Complete Login Security Pipeline

When a user attempts to log in, the request passes through all protection layers in sequence. Each layer can short-circuit the pipeline:

Incoming login request
        |
        v
1. IP Allow/Block Check
   BLOCK rule matched? --> HTTP 403, stop
        |
        v
2. CAPTCHA Verification (if configured)
   Invalid or missing token? --> HTTP 400, stop
        |
        v
3. Rate Limiting
   Per-IP or per-user limit exceeded? --> HTTP 429, stop
        |
        v
4. Brute-Force Lockout Check
   Account or IP locked? --> HTTP 423, stop
        |
        v
5. Keycloak Authentication
   Invalid credentials? --> record failure, HTTP 401, stop
        |
        v
6. Suspicious Login Analysis
   Run 5 detectors, execute configured actions
   Action = block? --> HTTP 403, stop
   Action = require_mfa? --> force MFA step
        |
        v
7. Adaptive MFA Risk Scoring
   5-factor weighted score
   Score above threshold? --> require MFA step-up
        |
        v
8. Token Issuance
   Set ACR/AMR claims
   Return access token + refresh token

Steps 1-4 are fast, synchronous checks that filter out obviously malicious traffic before reaching the more expensive authentication and analysis steps.

Best Practices for Production

1. Start with logging: Enable all suspicious login detectors in log mode first. Review events for a week to understand your baseline before switching to block or require_mfa.

2. Use temporary IP blocks: During an active attack, create temporary BLOCK rules with a 24-48 hour expiry rather than permanent blocks. This prevents accidental long-term lockouts.

3. Layer CAPTCHA with rate limiting: Use AFTER_FAILURES trigger mode so legitimate users never see CAPTCHA, while attackers hit it after 3-5 failed attempts.

4. Deploy MaxMind locally: For deployments handling more than 1000 logins per hour, switch from ip-api.com to MaxMind GeoLite2 to avoid external API rate limits and reduce latency.

5. Monitor the pipeline: Review audit logs regularly for patterns. A sudden spike in impossible_travel or new_country detections may indicate a credential stuffing attack.

6. Combine with MFA: Threat protection works best alongside Multi-Factor Authentication. Enable MFA for all users and use suspicious login detection to trigger step-up auth for anomalous logins.

API Endpoints

Required Permissions

Related Guides

• Attack Protection — Rate limiting, brute-force lockout, password security, and the full pipeline reference
• Multi-Factor Authentication — TOTP, SMS OTP, WebAuthn, and adaptive MFA
• Implementing DPoP — Token binding to prevent token theft
• Session Management — Managing user sessions and session policies