Download the PHP package danyseifeddine/keychain without Composer

🔐 KeyChain - Laravel Social Authentication Package

The most powerful and flexible Laravel social authentication package with multi-guard support, automatic setup, and complete customization control.

KeyChain provides an elegant solution for implementing social login across multiple user types (Users, Restaurants, Admins, etc.) with automatic guard registration, dynamic user creation, polymorphic token storage, and infinitely customizable authentication flows.

🚀 Features

• 🔐 Multi-Guard Support - Support unlimited authentication guards (User, Restaurant, Admin, etc.)
• 🎯 Automatic Setup - Guards, providers, and routes registered automatically from config
• 🪄 Magic Methods - Dynamic method generation for guard-specific user creation/update
• 📦 Laravel Socialite Integration - Built on Laravel's official social authentication
• 🔄 Token Management - Polymorphic social token storage with advanced expiration control
• 🎨 Fully Customizable - Override any part of the authentication flow
• 🛡️ Security First - Secure token handling, validation, and cleanup
• 📊 Management Commands - Artisan commands for token management and statistics
• 🎭 Publishable Assets - Controllers, views, config, and migrations
• 🔧 Zero Configuration - Works out of the box with sensible defaults

📋 Table of Contents

1. Installation
2. Basic Configuration
3. Simple Usage
4. Multi-Guard Setup
5. Publishing Assets
6. Controller Customization
7. Magic Methods
8. Token Management
9. Helper Functions
10. Commands
11. Advanced Configuration
12. Examples
13. Troubleshooting

🚀 Installation

1. Install via Composer

2. Publish Configuration and Assets

3. Run Migrations

4. Add Social Provider Credentials

Add your OAuth credentials to .env:

⚙️ Basic Configuration

Update config/keychain.php to enable providers:

🎯 Simple Usage

Basic Social Login (Single Guard)

KeyChain automatically generates these routes:

In your Blade template:

User Model Setup

Add the HasSocialAccounts trait to your User model:

That's it! KeyChain will automatically:

• ✅ Handle OAuth redirects and callbacks
• ✅ Create new users from social data
• ✅ Link social accounts to existing users
• ✅ Store and manage social tokens
• ✅ Redirect users to dashboard after login

🛡️ Multi-Guard Setup

1. Enable Multi-Guard in Config

2. Create Guard Models

3. Multi-Guard Routes

KeyChain automatically generates guard-specific routes:

4. Multi-Guard Login Template

📦 Publishing Assets

KeyChain provides several publishable assets for customization:

Available Publishing Tags

What Gets Published

🎛️ Controller Customization

Publishing the Controller

This creates app/Http/Controllers/Auth/SocialAuthController.php which extends the base controller.

Magic Methods (Dynamic Guard Support)

KeyChain automatically looks for guard-specific methods:

Lifecycle Hooks

Override these methods for custom logic at different stages:

Complete Callback Override

For ultimate control, override the entire authentication flow:

🪄 Magic Methods

KeyChain's magic method system automatically handles guard-specific user creation and updates without requiring you to define every method.

How Magic Methods Work

1. Method Pattern: create{Guard}User() and update{Guard}User()
2. Automatic Detection: KeyChain detects the guard from the method name
3. Dynamic Fallback: If method doesn't exist, uses dynamic creation from config
4. Case Handling: Converts method names to proper guard names automatically

Examples

Dynamic Creation (When Methods Don't Exist)

If you don't define custom methods, KeyChain automatically creates users using the guard's model and configuration:

Enabling/Disabling Magic Methods

Magic Method Debugging

Enable debug mode to see magic method calls:

Check storage/logs/laravel.log for magic method calls:

🔐 Token Management

KeyChain provides comprehensive token management with polymorphic relationships, expiration control, and automatic cleanup.

Token Storage Schema

Tokens are stored in the key_chain_tokens table with polymorphic relationships:

Token Expiration Configuration

Setting Infinite Tokens (Never Expire)

When infinite is true, all tokens get expires_at = null and never expire.

Custom Token Expiration Logic

Override the token expiration logic in your controller:

Working with Tokens in Your Models

Using the HasSocialAccounts trait:

Token Model Methods

The KeyChainToken model provides useful methods:

🛠️ Helper Functions

KeyChain provides a comprehensive helper class with utility methods for social authentication management.

KeyChainHelper Class

All helper methods are available via the KeyChainHelper class:

Provider Management

Guard Management

URL Generation

User Social Account Management

Token Cleanup

Authentication Statistics

Using Helpers in Blade Templates

Custom Helper Usage in Controllers

🎯 Commands

KeyChain provides powerful Artisan commands for managing social authentication tokens and providers.

Available Commands

Provider Management

Token Management

Token Cleanup

Token Revocation

Statistics

Automated Token Cleanup

Set up automated token cleanup using Laravel's scheduler:

Command Options Summary

⚙️ Advanced Configuration

Complete Configuration Reference

Environment Variables Reference

Adding Custom Providers

KeyChain supports any Laravel Socialite provider. To add a custom provider:

1. Install the provider package:

2. Add to services config:

3. Add environment variables:

4. Register the provider (if needed):

Custom Middleware

Add custom middleware to routes:

Performance Optimization

Security Best Practices

💡 Examples

Complete Multi-Restaurant Application

This example shows a complete setup for a multi-restaurant platform where restaurant owners can log in to manage their restaurants.

1. Configuration

2. Models

3. Custom Controller

4. Multi-Guard Login View

5. Restaurant Dashboard

6. Routes

This example demonstrates a complete multi-restaurant platform with:

• ✅ Separate guards for customers and restaurant owners
• ✅ Custom user creation logic for each guard type
• ✅ Email notifications and approval workflows
• ✅ Professional multi-guard login interface
• ✅ Comprehensive dashboard with social account management
• ✅ API endpoints for account management
• ✅ Security features and activity logging

🔧 Troubleshooting

Common Issues and Solutions

1. Routes Not Working

Problem: KeyChain routes return 404 errors

Solutions:

Check configuration:

2. Published Controller Not Being Used

Problem: Custom methods in published controller aren't called

Solution: The package automatically detects and uses the published controller. Verify:

3. Guard Detection Issues

Problem: Wrong guard is detected during authentication

Debug steps:

Common causes:

• Session not persisting between redirect and callback
• Route parameters not configured correctly
• Multiple middleware interfering

4. Social Provider Configuration

Problem: Provider redirects fail or show errors

Check credentials:

Verify OAuth app settings:

• Redirect URIs must match exactly
• Client ID and secret must be correct
• OAuth app must be enabled

5. Database/Migration Issues

Problem: Token storage fails or migration errors

Solutions:

6. Token Expiration Issues

Problem: Tokens expire immediately or never expire

Check configuration:

7. Magic Methods Not Working

Problem: Dynamic methods like createRestaurantUser() not called

Verify configuration:

Debug magic methods:

8. Memory/Performance Issues

Problem: High memory usage or slow performance

Optimization steps:

Performance config:

Debug Checklist

When troubleshooting, work through this checklist:

1. ✅ Environment Setup

   • [ ] Composer package installed
   • [ ] Configuration published
   • [ ] Migrations run
   • [ ] Environment variables set

2. ✅ Configuration

   • [ ] Providers enabled in config/keychain.php
   • [ ] Services configured with credentials
   • [ ] Guards configured (if using multi-guard)
   • [ ] Routes enabled

3. ✅ OAuth Provider Setup

   • [ ] OAuth app created in provider console
   • [ ] Redirect URIs match exactly
   • [ ] Client ID and secret correct
   • [ ] OAuth app enabled/published

4. ✅ Laravel Setup

   • [ ] Models have HasSocialAccounts trait
   • [ ] Guards registered in auth.php (for multi-guard)
   • [ ] Routes not conflicting
   • [ ] Middleware working correctly
5. ✅ Debugging
   • [ ] Enable debug mode temporarily
   • [ ] Check Laravel logs
   • [ ] Verify route registration
   • [ ] Test with simple single-guard setup first

Getting Help

If you're still experiencing issues:

1. Check the logs: Always check storage/logs/laravel.log with debug mode enabled
2. Minimal reproduction: Try with a fresh Laravel install and minimal config
3. Community support: Open an issue on GitHub with:
   • Laravel version
   • KeyChain version
   • Complete error message
   • Relevant configuration
   • Steps to reproduce

📄 Requirements

• PHP: 8.0 or higher
• Laravel: 10.0+ or 11.0+
• Laravel Socialite: 5.0+
• Database: MySQL, PostgreSQL, SQLite, or SQL Server

📜 License

KeyChain is open-sourced software licensed under the MIT license.

🤝 Contributing

Contributions are welcome! Please see our contributing guidelines for details.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📞 Support

• Documentation: This README covers everything you need
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: [email protected]

🚀 What's Next?

KeyChain is actively maintained and continuously improved. Upcoming features:

• 🔄 Token refresh automation
• 📱 Mobile OAuth support
• 🎨 More UI components
• 🔐 Advanced security features
• 📊 Enhanced analytics
• 🎯 More social providers