Download the PHP package libinkk/oneauth without Composer

OneAuth

OneAuth is a modular, API-first authentication package for Laravel 9, 10, 11, 12, and 13.

It provides one public API for session authentication, Laravel Sanctum, JWT access and refresh tokens, email OTP and OTP login, anonymous login, email verification, password management with history and expiration, two-factor authentication (TOTP, email OTP, SMS OTP with a custom provider), social login via Socialite, session tracking, device tracking with trusted-device policies, account locks, IP and country access rules, suspicious-login events, and audit logs.

OneAuth does not install a frontend, modify your User model, or force one authentication driver. Your Laravel application controls its UI, guards, User model, mail transport, and external providers.

[!IMPORTANT] OneAuth 1.x is under active development. Read Current implementation status before using it in production. SMS and WhatsApp delivery remain extension stubs until you bind real providers.

Contents

• Why OneAuth
• Features
• Requirements
• Installation
• Application setup
• Authentication drivers
• Facade API tutorial
• HTTP API tutorial
• OTP authentication
• Email verification
• Password management
• Two-factor authentication
• Social authentication
• Sessions and devices
• Anonymous login
• Security controls
• Middleware
• Events
• Configuration reference
• Database tables
• Extension points
• Artisan commands
• Testing
• Security checklist
• Troubleshooting
• Current implementation status
• Contributing
• Support
• License

Why OneAuth

Laravel applications often combine multiple packages for session login, Sanctum, JWT, OTP, social login, verification, password reset, and 2FA. OneAuth organizes these concerns behind:

• A unified OneAuth facade
• Replaceable authentication drivers
• Replaceable OTP and OAuth providers
• Repository contracts for sessions and devices
• Configurable JSON API routes
• Package-owned migrations with the oneauth_ prefix
• Laravel events for authentication outcomes
• Safe, repeatable installation commands

Features

Available in the package

• Email, username, or phone identifier lookup
• Registration with configurable password rules
• Session authentication driver
• Sanctum token driver
• JWT access tokens
• Opaque JWT refresh tokens with rotation
• Email OTP generation, delivery, hashing, expiration, cooldown, and attempt limits
• Numeric and alphanumeric OTP types
• Guest OTP send and OTP login
• Optional anonymous (guest) login
• Email verification tokens and temporary signed URLs
• Laravel password broker integration
• Password change, password history, and password expiration
• TOTP, email OTP, and SMS OTP two-factor methods (SMS delivery needs a custom provider)
• Single-use recovery codes and trusted-device 2FA skip
• Socialite providers: Google, Apple, GitHub, Facebook, Microsoft, LinkedIn, Twitter, Discord
• Active session records with revoke and logout-other-devices
• Device records with user-agent parsing, trust flags, country, and timezone
• Login attempt records, rate limiting, and persistent account locks
• IP and country allow/block lists
• Suspicious login detection for new devices
• Audit log writes for authentication events
• JSON API routes and exception envelope
• Facade-based API
• Middleware aliases
• Authentication events
• Install, publish, doctor, and cleanup commands
• GitHub Actions test matrix for Laravel 9 through 13

Integration required

• Sanctum requires laravel/sanctum and HasApiTokens
• Social login requires Laravel Socialite and provider credentials
• SMS and WhatsApp OTP or notifications require custom provider implementations
• Session API routes require session middleware
• JWT and Sanctum request authentication require guard or middleware wiring in the host application
• Password reset requires Laravel's password broker, reset token storage, mail, and User provider configuration
• Country restrictions rely on CF-IPCountry, X-Country-Code, request input, or ONEAUTH_DEFAULT_COUNTRY

Not included

• Blade, Vue, React, Livewire, Tailwind, or Bootstrap UI
• Automatic changes to the application User model
• Passport, LDAP, SAML, enterprise SSO, or OAuth server
• Magic links or passkeys
• Role and permission management

Requirements

• Composer 2
• PHP ^8.0.2
• Laravel 9, 10, 11, 12, or 13
• A configured database connection
• A Laravel authenticatable User model

The actual PHP requirement also depends on your Laravel major version. Composer resolves the compatible PHP and Illuminate dependency set.

Installation

Install the package:

Publish configuration and migrations:

Run migrations:

You can install and migrate in one command:

The install process is safe to run again:

• Existing config/oneauth.php is skipped
• Existing published OneAuth migration files are skipped
• Each package migration checks whether its table already exists
• Existing OneAuth tables are not recreated

Use --force only when you intentionally want to overwrite published files:

Check your installation:

The doctor command reports every OneAuth table as [exists] or [missing] and exits with a failure code when a table is missing.

Application setup

User model

OneAuth does not edit your User model. Your configured model must:

• Extend Laravel's authenticatable model
• Have a password attribute
• Have at least one configured identifier field
• Allow the registration attributes you want OneAuth to create
• Hide passwords and other secrets from JSON output

Example:

The HasOneAuth trait is optional. It provides:

Use a different model through .env:

Identifier fields

The default identifier fields are:

Remove fields your users table does not contain. If your database has no username or phone column, leaving these defaults can produce SQL errors during login lookup.

Mail

Email OTP, verification, and password reset need a configured Laravel mail transport:

Routes

OneAuth routes are enabled by default under /oneauth.

Disable package routes when using only the facade or your own controllers:

Authentication drivers

Choose one driver:

Supported values are session, sanctum, and jwt.

Session driver

The session driver uses Laravel's configured Auth guard:

The default package route middleware is api, which usually does not start a session. For session-based HTTP authentication, publish the config and change:

For SPA setups, configure Laravel's session cookies, CSRF protection, stateful domains, and CORS for your application.

Sanctum driver

Install Sanctum:

Add HasApiTokens to your User model:

Select the driver:

Login returns a Sanctum plain-text token:

Your application must configure Sanctum middleware or guards so Bearer tokens populate Laravel's current Auth user on protected requests.

JWT driver

firebase/php-jwt is installed with OneAuth. Configure a dedicated secret:

Generate a secret:

JWT login returns:

Refresh the token pair:

Refresh tokens are stored as SHA-256 hashes and rotated after use.

[!NOTE] OneAuth issues and rotates JWTs, authenticates Bearer access tokens in oneauth.auth, and revokes refresh tokens plus recently issued access tokens on logout and credential revoke.

Facade API tutorial

Import the facade:

Register

Registration does not automatically log in the user.

The default password policy requires:

• At least 8 characters
• One uppercase letter
• One lowercase letter
• One number

Login

Login with email:

Login with username:

Login with phone:

You can also use the generic identifier key:

The result shape is driver-dependent:

OTP login

Send a login OTP (guest or authenticated):

Verify the code and establish the active driver session or tokens:

Verify without logging in (sets session flag when a session exists):

Anonymous login

Requires ONEAUTH_ANONYMOUS_LOGIN=true:

Current user

Logout

Refresh

For JWT, the current request must contain refresh_token.

Email verification

Password management

Two-factor authentication

Social login

Supported provider names: google, apple, github, facebook, microsoft, linkedin, twitter, discord.

Sessions and devices

Account lock helpers

Select a driver at runtime

Driver contract methods:

• attempt(array $credentials)
• establish(mixed $user)
• login(array $credentials)
• logout()
• refresh()
• user()
• check()
• guest()
• token()

Prefer OneAuth::login() for application flows. It runs the shared login pipeline (rate limits, locks, access policy, verified email, 2FA, devices, sessions) before the driver establishes credentials.

HTTP API tutorial

All package endpoints return JSON. The default base path is:

Send these headers:

Public endpoints

Protected endpoints

These routes use oneauth.auth:

Register request

Login request

OTP login request

Anonymous login request

Requires ONEAUTH_ANONYMOUS_LOGIN=true.

Current user request

The Authorization header works only after your selected guard or custom middleware authenticates the token into Laravel Auth.

OTP authentication

The default provider sends OTP codes through Laravel Mail.

Send an OTP with the facade. Authenticated users can omit the identifier. Guests can send a login OTP by email, username, or phone:

Verify an OTP:

Complete an OTP login (verifies the code and establishes the configured driver session or tokens):

HTTP requests:

OTP security behavior:

• Codes use random_int for numeric OTPs or secure alphanumeric generation
• Codes are stored with Laravel Hash
• Expiration is enforced
• Attempt limits are enforced
• Send cooldown is enforced
• A verified code cannot be reused

Custom SMS or WhatsApp provider

The built-in SMS and WhatsApp provider classes are stubs. Bind your own implementation of OTPProviderInterface:

Register it in an application service provider:

The configured ONEAUTH_OTP_PROVIDER selects the bound package provider. The channel request field does not dynamically replace the container binding.

Email verification

Send a verification message:

The response contains:

Verify a token:

The package:

• Stores only a hash of the verification token
• Uses a 30-minute expiration
• Sends a raw email containing the token and temporary signed URL
• Updates email_verified_at when that attribute exists
• Dispatches EmailVerified

Require email verification during login:

[!NOTE] Guest verification with a token is supported through OneAuth::verifyEmail and the signed URL route. Authenticated users can also request a fresh verification email.

Password management

Forgot password

This delegates to Laravel's configured password broker.

Reset password

Change password

Password resets and changes record the resulting hash in oneauth_password_history, reject reuse against the configured history_limit, prune older history rows, and revoke OneAuth sessions plus Sanctum/JWT credentials.

Facade helpers:

Set password_policy.require_symbol to true when symbol characters are required.

Optional password expiration (days since last recorded password change; 0 disables):

Expired passwords block login until the user resets or changes their password.

Two-factor authentication

Enable TOTP 2FA (stores a pending secret until confirmed):

Enable email OTP 2FA (sends a confirmation OTP; SMS needs a custom OTP provider):

The TOTP setup result returns the secret and plaintext recovery codes once:

Render a QR code from otpauth_uri in your application UI. Secrets are RFC 4648 base32 for authenticator-app compatibility.

Confirm setup with a package TOTP or email/SMS OTP code (this sets enabled and fires TwoFactorEnabled):

Verify and consume a recovery code:

Disable 2FA (requires current password or a valid TOTP/recovery code):

The encrypted secret and recovery codes are cleared when disabled.

When login requires 2FA, OneAuth throws TwoFactorRequiredException with a short-lived challenge_token. Complete the login:

HTTP login returns 403 with two_factor_required and challenge_token. Finish with POST /oneauth/2fa/challenge.

Skip 2FA on trusted devices when enabled:

Mark a device trusted after login with OneAuth::trustDevice($fingerprint) or POST /oneauth/devices/{fingerprint}/trust.

[!WARNING] Pending 2FA secrets created before v1.2 used a package-specific secret format. Re-enable 2FA after upgrading if an older pending setup cannot be confirmed in an authenticator app.

Social authentication

Install Socialite:

Configure credentials in config/services.php.

Google example:

Environment:

Exchange a provider access token:

HTTP:

Supported provider names (configure Socialite + config/services.php for each):

• google
• apple
• github
• facebook
• microsoft
• linkedin
• twitter
• discord

Providers are resolved from oneauth.social.providers through a shared Socialite adapter.

The social flow:

1. Resolves the remote user through Socialite userFromToken
2. Finds an existing oneauth_social_accounts link
3. Optionally links a verified email match when social.link_by_email is true (default false)
4. Creates a user when social.create_user_if_missing is true and no conflicting email exists
5. Links the provider account
6. Dispatches SocialLogin
7. Runs the shared login pipeline (verified-email gate, 2FA challenge, then establish for the active driver)

Apple may require a compatible Socialite provider adapter and Laravel event registration because Apple is not included in every Socialite installation.

Sessions and devices

Every successful login records:

• One row in oneauth_sessions
• One device row matched by a SHA-1 fingerprint of user agent and IP when no fingerprint is supplied
• One successful login attempt

List sessions:

List devices:

HTTP:

Session records use ONEAUTH_IDLE_TIMEOUT for their expiry timestamp.

Device fingerprints and IP data are signals only. Do not treat them as proof of identity.

Device rows store parsed browser, OS, and device name when oneauth.devices.parse_user_agent is true. Trust a device:

Revoke a session or other devices:

Anonymous login

Opt-in guest accounts (disabled by default):

Security controls

After too many failed attempts OneAuth creates a row in oneauth_account_locks. Manual helpers:

New-device logins dispatch SuspiciousLoginDetected when detection is enabled. Password expiration:

Set to 0 to disable.

Middleware

OneAuth registers:

Apply middleware to application routes:

OTP and two-factor middleware currently use session flags. They are not token-scoped for pure JWT APIs.

Events

Listen to OneAuth events in your application:

Dispatched events:

• UserRegistered
• UserLoggedIn
• UserLoggedOut
• OTPSent
• OTPVerified
• EmailVerified
• PasswordReset
• PasswordChanged
• TwoFactorEnabled
• TwoFactorDisabled
• SocialLogin
• SuspiciousLoginDetected
• AccountLocked

All event objects expose:

Do not place tokens, OTP codes, passwords, recovery codes, or provider secrets in event context.

Configuration reference

Publish configuration:

Available environment variables:

Values in seconds:

• ONEAUTH_LOCKOUT_SECONDS
• ONEAUTH_OTP_EXPIRES_IN
• ONEAUTH_OTP_COOLDOWN
• ONEAUTH_IDLE_TIMEOUT

Values in minutes:

• ONEAUTH_JWT_TTL
• ONEAUTH_JWT_REFRESH_TTL

The full PHP configuration is in config/oneauth.php.

Database tables

OneAuth uses morph columns instead of a foreign key to a specific users table.

Migrations are safe to run more than once because each migration checks Schema::hasTable() before creating its table.

Extension points

OneAuth provides these contracts:

Override a binding in your application service provider:

Custom authentication driver

Implement:

The current manager resolves only the built-in names session, sanctum, and jwt. To add a named driver, extend or replace OneAuthManager in the container.

NotificationProviderInterface defaults to the email implementation. SMS remains a stub until you bind a real provider.

Artisan commands

Install

Publish

Diagnose

Cleanup

Cleanup deletes:

• Expired OTP challenges
• Expired refresh tokens
• Revoked refresh tokens
• Expired tracked sessions

Schedule cleanup in routes/console.php or your console kernel:

For older Laravel applications:

Testing

Install development dependencies:

Run tests:

On Windows:

The repository currently includes:

• A Testbench session registration and login feature test
• A TOTP generation and verification unit test
• An in-memory SQLite test database

When contributing, add focused tests for every changed security flow and run the relevant Laravel compatibility matrix.

Security checklist

Before production use:

• Set a dedicated, strong ONEAUTH_JWT_SECRET
• Use HTTPS
• Configure trusted proxies correctly
• Configure Laravel mail and queues
• Hide password and remember_token in the User model
• Restrict mass assignment on the User model
• Remove identifier fields that do not exist in your users table
• Configure session cookies, CSRF, CORS, and stateful domains
• Use oneauth.auth for JWT Bearer protection; wire Sanctum middleware when using the Sanctum driver
• Keep social.link_by_email disabled unless you accept verified-email auto-linking
• Bind production SMS or WhatsApp providers before selecting them
• Add application-level request validation and exception mapping
• Schedule oneauth:cleanup
• Back up data before package upgrades

Never log:

• Passwords
• Raw OTP codes
• Access tokens
• Refresh tokens
• Recovery codes
• OAuth provider secrets
• TOTP secrets

Troubleshooting

Table already exists

OneAuth migrations skip tables that already exist. Run:

If a table exists with an incompatible schema, back it up and reconcile the schema manually. A table-name match does not validate its columns.

Table is missing

Session login does not persist

The default route middleware is api. Publish the config and change route middleware to web, or add your application session middleware.

Unauthenticated with a valid JWT

oneauth.auth accepts a Bearer JWT access token when the JWT driver (or a valid OneAuth JWT) is present. Confirm ONEAUTH_JWT_SECRET matches the issuing app and that the token has not expired.

Sanctum is not installed

Add HasApiTokens to the User model and complete Sanctum's installation.

Socialite is not installed

Then configure config/services.php.

SMS or WhatsApp OTP throws an exception

Those providers are extension stubs. Bind your own OTPProviderInterface implementation, switch oneauth.otp.provider to email, or run php artisan oneauth:doctor to confirm the configuration.

Current implementation status

The following details are important for honest production evaluation:

• Email OTP and OTP login are implemented; SMS and WhatsApp OTP remain extension stubs (doctor fails if stubs are selected)
• Session, Sanctum, and JWT drivers issue credentials with Bearer auth, refresh, and revoke flows
• TOTP uses base32 secrets with otpauth_uri; email 2FA uses package OTP; SMS 2FA needs a custom OTP provider
• Trusted devices can skip 2FA when ONEAUTH_2FA_SKIP_TRUSTED_DEVICE is true
• Password expiration, account locks, IP/country allow and block lists, and suspicious-login events are enforced from config
• Device rows parse browser, OS, and device name from the user agent
• Anonymous login is opt-in via ONEAUTH_ANONYMOUS_LOGIN
• Audit logs are written automatically when ONEAUTH_AUDIT_LOG_ENABLED is true
• OneAuth exceptions return a JSON envelope (message, error, context) on package/API routes
• Social login supports Google, Apple, GitHub, Facebook, Microsoft, LinkedIn, Twitter, and Discord via Socialite
• Session revoke and logout-other-devices APIs are available on the facade and HTTP routes
• GitHub Actions runs a Laravel 9–13 PHPUnit matrix on push and pull requests

These notes are documented so developers can make an informed decision and contribute improvements.

Contributing

Contributions are welcome.

1. Fork the repository
2. Create a feature branch
3. Keep changes modular and driver-independent
4. Add or update tests
5. Run vendor/bin/phpunit
6. Update documentation
7. Open a pull request with a clear description and test plan

Contribution rules:

• Support Laravel 9, 10, 11, 12, and 13
• Do not add frontend dependencies
• Do not modify the application User model automatically
• Keep secrets out of logs, events, and exceptions
• Use contracts across package module boundaries
• Preserve backward compatibility or include upgrade notes

Repository:

https://github.com/libin-k-k/oneauth

Issues:

https://github.com/libin-k-k/oneauth/issues

Support

• Website: https://www.libinkk.in
• Email: [email protected]
• Author: Libin K K
• Author email: [email protected]

Please use GitHub Issues for reproducible bugs and feature requests. Do not post credentials, tokens, OTP codes, or private application data.

License

OneAuth is open-source software licensed under the MIT License.