README

Daycry Auth

A comprehensive authentication and authorization library for CodeIgniter 4, designed to be flexible, secure, and easy to extend.

composer require daycry/auth

Features

Authentication Methods

Method	Description
Session	Email/password with secure remember-me cookies
Access Token	Long-lived API keys sent via `X-API-KEY` header
JWT	Stateless Bearer tokens with refresh token rotation
Magic Link	Passwordless login via one-time email link
OAuth 2.0	Social login: Google, GitHub, Facebook, Microsoft Azure

Security Features

Feature	Description
TOTP Two-Factor Auth	Time-based OTP (Google Authenticator, Authy, 1Password)
Email Two-Factor Auth	6-digit code sent to user's email after login
Email Activation	Require email confirmation before first login
Per-User Account Lockout	Lock account after N failed attempts (independent of IP)
IP-Based Blocking	Block IPs that exceed failed attempt limits
Rate Limiting	Per-IP, per-user, or per-endpoint request throttling
Force Password Reset	Flag accounts for mandatory password change
Password Reset Flow	Secure token-based reset with email delivery
Self-Service Email Change	Change email with confirmation link to new address
Access Token Revocation	Soft-revoke tokens without deleting them
Device Session Tracking	See and terminate active logins per device/browser
UUID Dual-Key Pattern	Internal `id` (INT) + external `uuid` (UUID v7) on users

Authorization

Feature	Description
Groups	Named roles (e.g., `admin`, `editor`, `user`)
Permissions	Granular actions (e.g., `posts.create`, `users.delete`)
Permission Inheritance	Users inherit all permissions from their groups
Wildcard Permissions	`posts.*` grants all post-related permissions
Permission Cache	Configurable TTL cache to avoid repeated DB queries
Route Filters	`group:admin`, `permission:posts.edit` directly on routes

Developer Experience

Feature	Description
BaseAuthController	Abstract base with validation, redirect, and error helpers
Bootstrap 5 Admin Panel	Manage users, groups, permissions, and logs via UI
OAuth Provider Unlinking	Let users disconnect social accounts
Pre-Auth Events	`pre-login` and `pre-register` CodeIgniter Events
CI4 Events System	Hook into `login`, `logout`, `registered`, `passwordReset`, etc.
Chain Authenticator	Try session → access_token → JWT automatically
Custom Authenticators	Extend `Base` with full Dependency Injection support

Quick Start

Requirements

PHP 8.1 or higher
CodeIgniter 4.4 or higher
Composer

Installation

# 1. Install the package
composer require daycry/auth

# 2. Run migrations (creates all auth tables)
php spark migrate --all

# 3. Publish config files and basic routes
php spark auth:setup

Basic Usage

// Login
$result = auth()->attempt([
    'email'    => 'user@example.com',
    'password' => 'secret',
]);

if ($result->isOK()) {
    return redirect()->to('/dashboard');
}

// Check authentication
if (auth()->loggedIn()) {
    $user = auth()->user();
    echo $user->email;
}

// Check authorization
if ($user->can('posts.create')) { ... }
if ($user->inGroup('admin')) { ... }

// Logout
auth()->logout();

Protect Routes

// app/Config/Routes.php

// Require login
$routes->group('dashboard', ['filter' => 'session'], static function ($routes) {
    $routes->get('/', 'Dashboard::index');
});

// Require login + admin group
$routes->group('admin', ['filter' => 'session,group:admin'], static function ($routes) {
    $routes->get('/', 'Admin::index');
});

// Require a specific permission
$routes->post('posts/delete/(:num)', 'PostController::delete/$1', [
    'filter' => 'session,permission:posts.delete',
]);

// API with JWT
$routes->group('api', ['filter' => 'jwt'], static function ($routes) {
    $routes->get('profile', 'API\ProfileController::show');
});

JWT with Refresh Tokens (API)

# Login → get access + refresh token
POST /auth/jwt/login
email=user@example.com&password=secret

# Use access token
GET /api/profile
Authorization: Bearer eyJ0eXAi...

# Refresh when expired
POST /auth/jwt/refresh
user_id=42&refresh_token=a3f8c2d1...

# Logout (revoke refresh token)
POST /auth/jwt/logout
user_id=42&refresh_token=a3f8c2d1...

Documentation

Full documentation is available at:

https://authentication-for-codeigniter-4.readthedocs.io/

Section	Description
Quick Start	Install and set up in minutes
Configuration	Every config option explained
Authentication	All auth methods + JWT refresh + password reset
Filters	Route protection filters
Controllers	All included controllers
Authorization	Groups, permissions, RBAC
Logging & Events	CI4 Events, DB logs, lockout
Testing	Testing auth in your app
OAuth 2.0	Google, GitHub, Facebook, Azure
TOTP 2FA	Authenticator app integration
Device Sessions	Active session management

Contributing

Contributions of all kinds are welcome — code, documentation, bug reports, or feedback. See CONTRIBUTING.md for details.

License

This project is licensed under the MIT License — see the LICENSE file for details.

Acknowledgements

Made with contrib.rocks.

Security design informed by:

daycry / auth

Maintainers

Package info

Statistics

Security