Download the PHP package zhylon/zhylon-auth without Composer

Zhylon OAuth2

Zhylon OAuth2 Provider for Laravel Socialite

Integrate ZhylonID single sign-on into your Laravel application with just a few lines of code. This package provides a first-class Laravel Socialite driver for the Zhylon OAuth2 service, handling the full authentication flow, token management, and user synchronization out of the box.

📋 Table of Contents

• Features
• Requirements
• Installation
• Configuration
• Preparing Your User Model
• Usage
  • OAuth Flow Overview
  • Controller Example
  • Accessing User Data
  • Token Refresh
• Environment Variables Reference
• Troubleshooting
• Security
• Changelog
• Contributing
• Credits
• License

✨ Features

• Drop-in Laravel Socialite driver for Zhylon OAuth2
• Automatic user creation and synchronization on login
• Stores zhylon_id, zhylon_token, and zhylon_refresh_token on your User model
• Configurable callback URL, redirect path, and post-login destination
• Ships with a ready-to-use migration for the required user fields
• Minimal setup — works with any existing Laravel auth scaffold

📦 Requirements

Note: You need an active ZhylonID account and a registered OAuth application. Sign up at https://id.zhylon.net.

🚀 Installation

Install the package via Composer:

Publish the configuration file and migration:

Run the database migration to add the required columns to your users table:

⚙️ Configuration

Environment Variables

Add the following variables to your .env file. You will find the client credentials in your ZhylonID dashboard after registering your application.

Optional settings — these have sensible defaults but can be customized:

Config File

After publishing, the config file is available at config/zhylon-auth.php. This file maps the environment variables above and can be adjusted for more advanced setups (e.g., per-environment overrides).

👤 Preparing Your User Model

The package syncs OAuth user data into your User model. You need to add the three Zhylon fields to the $fillable array so that mass-assignment works correctly:

The migration published in the previous step will automatically add these three columns to your users table:

🧑‍💻 Usage

OAuth Flow Overview

The package implements the standard OAuth2 Authorization Code flow:

Controller Example

The package registers the redirect and callback routes automatically. If you need to build a custom controller or override the default behavior, here is a full example:

Register the routes in routes/web.php:

Accessing User Data

Once the user is authenticated, you can access the Zhylon-specific fields directly from the authenticated user:

Token Refresh

If you need to refresh an expired access token on behalf of a user, you can use Socialite's refreshToken method:

Note: ZhylonID may rotate refresh tokens on use. Always persist the new refresh token returned from this call.

📄 Environment Variables Reference

🔧 Troubleshooting

InvalidStateException after callback This typically happens when the session is lost between the redirect and the callback. Make sure your session middleware is applied to the callback route and that your session driver is properly configured.

Client error: 401 Unauthorized Double-check that ZHYLON_AUTH_CLIENT_ID and ZHYLON_AUTH_CLIENT_SECRET in your .env match the credentials in your ZhylonID dashboard. Also clear the config cache: php artisan config:clear.

Callback URL mismatch The callback URL registered in your ZhylonID application must exactly match the value of ZHYLON_AUTH_CALLBACK_WEBSITE + ZHYLON_AUTH_SITE_PATH + /callback. For example: https://your-app.com/auth/zhylon/callback.

Columns not found after migration If the migration did not run, execute php artisan migrate. If the columns are missing from the migration file, re-publish with: php artisan vendor:publish --force.

📝 Changelog

Please see CHANGELOG for a full history of changes.

🤝 Contributing

Contributions are welcome! Please read the Contributing Guide before submitting a pull request.

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

🔒 Security

• Never commit your .env file or expose ZHYLON_AUTH_CLIENT_SECRET publicly.
• Store tokens (zhylon_token, zhylon_refresh_token) encrypted in the database using Laravel's encrypted casting if your threat model requires it.
• The callback route should be protected against CSRF. Laravel Socialite handles the state parameter automatically to prevent CSRF attacks during the OAuth flow.
• If you discover a security vulnerability, please do not use the public issue tracker. Instead, send an email to [email protected]. All security reports are addressed promptly.

🙏 Credits

• TobyMaxham
• All Contributors

📄 License

The MIT License (MIT). Please see the License File for details.