Daycry Auth - Authentication Library for CodeIgniter 4 Logo

Getting Started

  • Quick Start Guide
    • Requirements
    • Installation
      • 1. Install via Composer
      • 2. Run Migrations
      • 3. Publish Configuration
    • Basic Configuration
    • Register Filters
    • Set Up Routes
    • Your First Protected Controller
    • Authentication Helpers
    • What’s Working Now
    • Next Steps
    • Troubleshooting
  • ⚙️ Configuration Reference
    • The Configuration Files
    • Database
      • Database Group
      • Table Names
    • Authenticators
      • Available Authenticators
      • JWT Adapter
      • Authentication Chain
    • Session Authenticator
    • User Settings
    • Password Settings
    • Password Reset
    • Per-User Account Lockout
    • Magic Links
    • Access Tokens
    • JWT Refresh Tokens
    • Logging & Monitoring
      • Activity Logs
      • IP-Based Failed Attempt Blocking
      • Rate Limiting
    • Authorization Cache
    • Views
    • Redirects
    • Routes
    • Post-Authentication Actions
    • Field Validation Rules
    • OAuth Providers
      • Provider Configuration Keys
    • Sessions
    • Trusted Devices (2FA bypass)
    • Compliance & Observability
    • Common Presets
      • Web Application
      • API (Stateless)
      • High-Security (production)
      • Compliance (SOC 2 / ISO 27001)
    • Dynamic Configuration

Authentication

  • 🔐 Authentication — Complete Guide
    • 📋 Index
    • Session Authenticator
      • Basic Usage
      • Helper Functions
      • Session Configuration
      • Remember Me
    • Per-User Account Lockout
      • Configuration
      • How It Works
      • Unlocking Manually (Admin)
      • Concurrency safety
    • Compromised-Password Recheck on Login
      • What happens on a hit
      • What happens on HIBP failure
    • Access Token Authenticator
      • Enable Access Tokens
      • Generate a Token
      • Use the Token in Requests
      • Protect Routes with the Token Filter
      • Token Management
      • Soft Revocation
      • Scope Enforcement
      • Admin CLI
    • JWT Authenticator
      • Configuration
      • Use the JWT Filter
      • Authorization Header
    • JWT Refresh Tokens
      • Register the JWT Routes
      • Configure Refresh Token Lifetime
      • Login
      • Refresh an Expired Access Token
      • Logout (Revoke Refresh Token)
      • Client-Side Flow (JavaScript example)
    • Magic Link Authentication
      • Enable Magic Links
      • Complete Flow
      • Routes
    • Guest Authenticator
    • Password Reset
      • How It Works
      • Routes (already in Config/Auth.php)
      • Configuration
      • Listen for Reset Completion
    • Force Password Reset
      • Flag a User for Password Reset
      • How It Works
      • Apply the Filter
    • Pre-Authentication Events
    • Switching Between Authenticators
      • Multiple Authenticators in One App
      • Chain Authenticator
      • Runtime Detection
    • Custom Authenticators
    • Why HTTP Digest Auth is not supported
      • 1. Incompatible with bcrypt / argon2
      • 2. Effectively deprecated
      • 3. No security gain over Basic + TLS
      • 4. Modern alternatives are already in the package
      • If your use case really requires Digest
  • OAuth 2.0 & Social Login
    • Table of Contents
    • How It Works
    • Architecture
    • Installation
    • Configuration
      • Provider Configuration Keys
    • Routing
      • Automatic Routing
      • Manual Routing
    • Adding Login Buttons
    • Provider Examples
      • Google
      • GitHub
      • Facebook
      • Microsoft / Azure
      • Generic OIDC Provider
    • Stored Token Data
      • Extra JSON Structure
    • Profile Fields
      • Configuring Profile Fields
      • Profile Resolvers
        • AzureProfileResolver
        • GenericProfileResolver
      • Custom Profile Resolver
      • Reading Stored Profile Data
    • Scopes Granted
    • Refresh Tokens
      • Refresh an Access Token
      • Error Handling
    • OAuth Events
      • Listening to OAuth Events
    • OAuthTokenRepository
      • Available Methods
      • Direct Usage
    • IdentityType Helper
    • Unlinking a Provider
      • Route Setup
      • Unlink Button in a View
      • Safety Check
    • Account Linking Strategy
      • Handling New Users from OAuth
    • Testing OAuth
      • Mocking the Provider
      • Testing Events
      • Testing the Repository
      • Testing the ProfileResolverFactory
  • 🔐 TOTP Two-Factor Authentication
    • 📋 Table of Contents
    • How It Works
    • Configuration
      • 1. Enable the TOTP Post-Login Action
      • 2. Set the Issuer Name
      • 3. Configure the Encryption Key
    • User Enrollment
      • Phase 1 — Generate the QR code
      • Phase 2 — Confirm the first code
      • Setup View
    • Login Flow
      • What Happens Automatically
      • Override the Default TOTP Views
    • HasTotp Trait Reference
      • Security Dashboard Example
    • Backup Codes
      • When they are generated
      • How they work during login
      • Storage
      • Programmatic regeneration
      • Lifecycle with TOTP
    • Trust This Device
      • Enable
      • User flow
      • Revoking trust
      • Security properties
      • When NOT to use
    • UserSecurityController Integration
    • Admin TOTP Reset
    • Disabling TOTP
    • Testing TOTP
    • Security Notes
  • 📱 Device Sessions
    • 📋 Table of Contents
    • How It Works
    • Configuration
    • Database Migration
    • Viewing Active Sessions
      • Get All Sessions for a User
      • Get Only Active (Not Logged-Out) Sessions
      • Identify the Current Session
    • Terminating Sessions
      • Terminate a Specific Session
      • Terminate All Other Sessions (Keep Current)
      • Terminate All Sessions (Including Current)
    • Concurrent Session Limit
      • Enable
      • Behaviour
      • Use cases
      • Edge cases
    • Trusted Devices (2FA bypass)
      • Helper methods on the model
    • Login Activity Feed
    • UserSecurityController Integration
    • Building a Sessions Management Page
      • Controller
      • View
    • New Device Login Notification
    • Admin CLI
    • Testing Device Sessions
    • Security Tips

Controllers & Filters

  • 🛡️ Security Filters
    • 📋 Filter Index
    • 🔧 Initial Setup
      • 1. Register Filters in app/Config/Filters.php
    • 🔐 Authentication Filters
      • 1. Session Filter (session)
        • Basic Usage
        • Advanced Configuration
      • 2. Access Token Filter (tokens)
        • Usage in APIs
        • Required Headers
      • 3. JWT Filter (jwt)
        • Configuration
        • JWT Headers
      • 4. Basic Auth Filter (basic-auth)
        • Configuration
        • Routes
        • Behaviour
        • Use cases
      • 5. Chain Filter (chain)
        • Configuration
        • Practical Example
    • 👥 Authorization Filters
      • 1. Group Filter (group)
        • Basic Usage
        • Hierarchical Groups
      • 2. Permission Filter (permission)
        • Basic Usage
        • Granular Permission System
      • 3. Token Scope Filter (token-scope)
        • How scopes are matched
        • Generating scoped tokens
        • Failure response
    • 🔗 Chain Filters
      • Advanced Chain Configuration
      • Hybrid API Example
    • 📊 Control Filters
      • 1. Auth Rates Filter (auth-rates)
        • Global Configuration
        • Specific Configuration
      • 2. Force Password Reset Filter (force-reset)
      • 3. Password Age Filter (password-age)
      • 4. Password Confirm Filter (password-confirm)
        • Routes
        • Behaviour
        • Settings reference
      • 5. Auth Request Filter (auth-request)
    • 🛠️ Advanced Configuration
      • Conditional Filters
      • Custom Filters
      • Filter Combination
    • 🎯 Practical Examples
      • 1. Complete Admin Panel
      • 2. RESTful API with Multiple Auth Methods
      • 3. Application with Different Access Levels
    • 🚨 Error Handling
      • Custom Responses for Filters
    • 📈 Monitoring and Debugging
      • Filter Debugging
      • Filter Testing
  • 🎮 Controllers — Complete Guide
    • 📋 Index
    • BaseAuthController
      • Available Helper Methods
    • LoginController
      • Extending LoginController
    • RegisterController
      • Extending RegisterController
    • ActionController
    • MagicLinkController
    • PasswordResetController
      • How to Enable
      • Configuration
      • Security Design
      • Adding a Link to Your Login Page
      • Customising the Reset Email
      • Listen for Reset Completion
    • ForcePasswordResetController
      • How to Enable the Filter
      • Flag a User Programmatically
      • What the Form Requires
    • JwtController
      • Register the Routes
      • Configuration
      • login()
      • refresh()
      • logout()
      • Security Notes
    • UserSecurityController
      • Register the Routes
      • changePassword()
      • changeEmail()
      • confirmEmailChange()
      • unlinkOauth()
      • loginActivity()
    • Creating Custom Controllers
      • Minimal Custom Controller
      • API Controller with JWT + Access Token
    • Best Practices
      • 1. Always Use BaseAuthController for Auth Logic
      • 2. Validate in getValidationRules(), Not in Action Methods
      • 3. Check Permissions Early
      • 4. Use Events for Side Effects
      • 5. Return Correct HTTP Status Codes in APIs

Authorization & Logging

  • 👥 Authorization — Groups & Permissions
    • 📋 Table of Contents
    • Quick Reference
    • Groups
      • What Is a Group?
      • Checking Group Membership
      • Assigning and Removing Groups
      • Getting All Users in a Group
    • Permissions
      • Permission Format
      • Checking Permissions
      • Assigning and Removing Permissions
      • Assigning Permissions to a Group
    • Permission Inheritance
      • Wildcard Permissions
    • Gates & Policies
      • Closure-based abilities
      • Class-based policies
        • Auto-discovery
        • Explicit registration
        • Action name convention
      • gate: route filter
      • When to use what
    • Authorization in Controllers
      • Pattern 1: Early Return
      • Pattern 2: Exception-Based
      • Pattern 3: Group + Permission Check Together
    • Authorization in Views
    • Route Filters
      • Register Filter Aliases
      • What Happens on Denial?
    • Permission Cache
      • Cache Invalidation
      • When to Enable the Cache
    • Default Group for New Users
    • Admin Panel
    • Best Practices
      • 1. Use Groups for Roles, Permissions for Actions
      • 2. Check Permissions, Not Groups, in Business Logic
      • 3. Enable Cache in Production
      • 4. Keep Permission Names Consistent
  • 📊 Logging, Events & Monitoring
    • 📋 Table of Contents
    • CodeIgniter Events
      • Register Event Listeners
    • Available Events
    • Listening to Events
      • Security Alert on Multiple Failed Logins
      • Welcome Email on Registration
      • Audit Trail for Password Resets
      • OAuth Login Tracking
    • Pre-Authentication Events
      • Log All Login Attempts
      • Block Specific Domains from Registering
    • Suspicious Login Event
      • Listener — email the user
      • Possible flag values
    • Database Logging
      • Enable Activity Logs
      • Query Logs
    • Login Attempt Logging
      • Configuration
      • What Gets Stored
      • Query Login Attempts
    • Failed Attempt Blocking
      • Configuration
    • Per-User Account Lockout
      • Configuration
      • How It Works
      • Unlocking a User Manually
    • Rate Limiting
      • Configuration
      • Apply Rate Limiting to Routes
    • Audit Log (auth_audit_logs)
      • Built-in events
      • Recording your own events
      • Querying
    • Monitoring & Querying Logs
      • Dashboard Statistics
      • Find Locked Accounts
      • CI4 Log Files

Compliance & Operations

  • 🛡️ Audit Log & Compliance
    • 📋 Index
    • Audit Log
      • What gets recorded
      • Built-in events
      • Recording your own events
      • Querying the audit log
      • CLI: auth:audit
      • Database
    • Suspicious Login Detection
      • Enable
      • Detection signals
      • React with an event listener
      • What lands in the audit log
    • Compromised-Password Recheck on Login
      • Enable
      • Behaviour
      • Cost
    • Password History (No Reuse)
      • Enable
      • How it works
      • Hooks
      • Database
    • Password Rotation Policy
      • Enable
      • Wire the filter
      • Behaviour
      • Database
    • GDPR Export & Anonymization
      • auth:gdpr export
      • auth:gdpr anonymize
      • When to use export vs anonymize
    • Quick Configuration Reference
  • 🖥️ CLI Commands
    • 📋 Index
    • Setup & Discovery
      • auth:setup
      • auth:discover
    • User management
      • auth:user
    • Token & session admin
      • auth:tokens
      • auth:sessions
    • Two-factor admin
      • auth:totp
    • Audit & compliance
      • auth:audit
      • auth:gdpr
        • Export
        • Anonymize
    • Cheat sheet

Testing & Reference

  • 🧪 Testing Guide
    • 📋 Table of Contents
    • 🏃‍♂️ Quick Start
      • Running Tests
      • Test Environment Setup
    • 🧪 Test Categories
      • Unit Tests
      • Integration Tests
      • Feature Tests
    • 🔧 Test Setup
      • Base Test Class
      • Mock Configuration
    • 🛡️ Testing Authentication
      • Login Tests
      • Logout Tests
      • Remember Me Tests
    • 👥 Testing Authorization
      • Permission Tests
    • 🎛️ Testing Controllers
      • Controller Test Example
    • 🔍 Testing Filters
      • Filter Test Example
    • 📊 Testing Models
      • User Model Tests
    • 🏗️ Testing Traits
      • Testing BaseControllerTrait
    • 🎯 Testing Best Practices
      • 1. Test Isolation
      • 2. Clear Test Names
      • 3. Test Data Factories
      • 4. Mock External Dependencies
    • 🚀 Contributing Tests
      • Writing New Tests
      • Test Coverage
      • Pull Request Testing
      • Test Examples Repository
    • 🔗 Related Documentation
  • 🔄 Migration Guide
    • 📋 Index
    • Upgrading to the next release (Unreleased)
      • Required steps
      • Optional — opt-in to new features
      • What runs automatically (no action needed)
    • Upgrading to v5.x
      • What changed
      • What you must do
    • Upgrading to v4.x — Config\Auth split
      • What changed
      • What you must do
    • General upgrade checklist
Daycry Auth - Authentication Library for CodeIgniter 4
  • Search

© Copyright 2025, Daycry.

Built with Sphinx using a theme provided by Read the Docs.