PHPackages                             tobymaxham/zhylon-auth - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Authentication & Authorization](/categories/authentication)
4. /
5. tobymaxham/zhylon-auth

Abandoned → [zhylon/zhylon-auth](/?search=zhylon%2Fzhylon-auth)Library[Authentication & Authorization](/categories/authentication)

tobymaxham/zhylon-auth
======================

Zhylon OAuth2 Provider for Laravel Socialite

v2.1(2mo ago)0331[1 issues](https://github.com/Zhylon/zhylon-auth/issues)MITPHPPHP ^8.3|^8.4|8.5

Since Dec 27Pushed 2mo ago2 watchersCompare

[ Source](https://github.com/Zhylon/zhylon-auth)[ Packagist](https://packagist.org/packages/tobymaxham/zhylon-auth)[ RSS](/packages/tobymaxham-zhylon-auth/feed)WikiDiscussions main Synced today

READMEChangelog (1)Dependencies (4)Versions (8)Used By (0)

Zhylon OAuth2
=============

[](#zhylon-oauth2)

> **Zhylon OAuth2 Provider for Laravel Socialite**

Integrate [ZhylonID](https://id.zhylon.net) 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.

[![Latest Version on Packagist](https://camo.githubusercontent.com/389129ea7706816daab25dc15e8bd474f8e0b06a3864b5b0be0f11fd959bf1a8/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7a68796c6f6e2f7a68796c6f6e2d617574682e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/zhylon/zhylon-auth)[![Total Downloads](https://camo.githubusercontent.com/9d2e7de2273bf6f689452bacf00943363b833d34cc515dbe204be944b9920d82/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f7a68796c6f6e2f7a68796c6f6e2d617574682e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/zhylon/zhylon-auth)[![License](https://camo.githubusercontent.com/d30069c673da94bb6e201afaf2cad8e6ff25d66f2e92fb6921f7c35d899ae15d/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f5a68796c6f6e2f7a68796c6f6e2d617574683f7374796c653d666c61742d737175617265)](LICENSE.md)

---

📋 Table of Contents
-------------------

[](#-table-of-contents)

- [Features](#-features)
- [Requirements](#-requirements)
- [Installation](#-installation)
- [Configuration](#-configuration)
- [Preparing Your User Model](#-preparing-your-user-model)
- [Usage](#-usage)
    - [OAuth Flow Overview](#oauth-flow-overview)
    - [Controller Example](#controller-example)
    - [Accessing User Data](#accessing-user-data)
    - [Token Refresh](#token-refresh)
- [Environment Variables Reference](#-environment-variables-reference)
- [Troubleshooting](#-troubleshooting)
- [Security](#-security)
- [Changelog](#-changelog)
- [Contributing](#-contributing)
- [Credits](#-credits)
- [License](#-license)

---

✨ Features
----------

[](#-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
--------------

[](#-requirements)

DependencyVersionPHP`^8.3`Laravel`^10.0 | ^11.0 | ^12.0`Laravel Socialite`^5.0`> **Note:** You need an active ZhylonID account and a registered OAuth application. Sign up at .

---

🚀 Installation
--------------

[](#-installation)

Install the package via Composer:

```
composer require zhylon/zhylon-auth
```

Publish the configuration file and migration:

```
php artisan vendor:publish --provider="Zhylon\ZhylonAuth\ZhylonAuthServiceProvider"
```

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

```
php artisan migrate
```

---

⚙️ Configuration
----------------

[](#️-configuration)

### Environment Variables

[](#environment-variables)

Add the following variables to your `.env` file. You will find the client credentials in your [ZhylonID dashboard](https://id.zhylon.net) after registering your application.

```
ZHYLON_AUTH_CLIENT_ID=your-client-id
ZHYLON_AUTH_CLIENT_SECRET=your-client-secret
ZHYLON_AUTH_CALLBACK_WEBSITE="https://your-application.com"
```

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

```
# The URL path that triggers the OAuth redirect (default: /auth/zhylon)
ZHYLON_AUTH_SITE_PATH="/auth/zhylon"

# The ZhylonID base URI (default: https://id.zhylon.net)
ZHYLON_AUTH_BASE_URI="https://id.zhylon.net"

# Where to redirect the user after a successful login (default: /dashboard)
ZHYLON_AUTH_HOME="/dashboard"
```

### Config File

[](#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
---------------------------

[](#-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:

```
// app/Models/User.php

protected $fillable = [
    'name',
    'email',
    // ... your existing fields ...
    'zhylon_id',
    'zhylon_token',
    'zhylon_refresh_token',
];
```

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

ColumnTypeDescription`zhylon_id``string|null`Unique user ID from ZhylonID`zhylon_token``text|null`Current OAuth access token`zhylon_refresh_token``text|null`OAuth refresh token for re-authentication---

🧑‍💻 Usage
---------

[](#‍-usage)

### OAuth Flow Overview

[](#oauth-flow-overview)

The package implements the standard **OAuth2 Authorization Code** flow:

```
User clicks "Login with Zhylon"
        │
        ▼
Your app redirects → https://id.zhylon.net/oauth/authorize
        │
        ▼ (User authenticates & grants permission)
        │
Zhylon redirects back → https://your-app.com/auth/zhylon/callback
        │
        ▼
Package exchanges code for token, creates/updates User, logs them in
        │
        ▼
User is redirected to ZHYLON_AUTH_HOME

```

### Controller Example

[](#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:

```