bevi-webdev-jm/hub-auth-client

SSO client package for connecting Laravel apps to the centralized Hub via OAuth2

v1.0.0 2026-06-04 08:51 UTC

Requires

• php: ^8.0
• guzzlehttp/guzzle: ^7.0
• laravel/framework: ^8.0|^9.0|^10.0|^11.0|^12.0
• laravel/socialite: ^5.0

Requires (Dev)

• mockery/mockery: ^1.4
• orchestra/testbench: ^7.0|^8.0|^9.0|^10.0
• phpunit/phpunit: ^9.0|^10.0|^11.0

MIT

README

A Laravel package that provides Single Sign-On (SSO) integration for Laravel applications via OAuth2, connecting them to a centralized Hub authentication server.

Overview

This package handles the complete OAuth2 flow between your Laravel application and the Hub, including user synchronization, account linking by email, and automatic user provisioning on first login.

Requirements

• PHP 8.0+
• Laravel 8.0–12.0
• Laravel Socialite 5.0+

Installation

composer require bevi-webdev-jm/hub-auth-client

The package auto-registers its service provider via Laravel's package discovery.

Setup

1. Publish the configuration

php artisan vendor:publish --tag=hub-auth-config

2. Add environment variables

HUB_URL=https://hub.yourdomain.com
HUB_CLIENT_ID=your-client-id
HUB_CLIENT_SECRET=your-client-secret
HUB_REDIRECT_URI=https://yourapp.com/login/hub/callback
HUB_DEFAULT_ROLE=default_user

3. Add hub_user_id to your users table

Schema::table('users', function (Blueprint $table) {
    $table->string('hub_user_id')->nullable()->unique();
});

4. Add hub_user_id to your User model's $fillable array

protected $fillable = [
    'name',
    'email',
    'hub_user_id',
    // ...
];

5. Add a login link to your template

<a href="{{ route('hub.login') }}">Login with Hub</a>

Configuration

All options are in config/hub-auth.php:

Key	ENV Variable	Default	Description
hub_url	HUB_URL	http://localhost:8000	Base URL of the Hub server
client_id	HUB_CLIENT_ID	—	OAuth2 client ID issued by Hub
client_secret	HUB_CLIENT_SECRET	—	OAuth2 client secret issued by Hub
redirect	HUB_REDIRECT_URI	—	Full callback URL of your application
default_role	HUB_DEFAULT_ROLE	default_user	Role assigned to new users (requires Spatie Permission)
redirect_after_login	—	/home	Where to redirect after successful login

Authentication Flow

1. User visits /login/hub → redirected to Hub's OAuth2 authorization page
2. User authenticates at Hub
3. Hub redirects back to /login/hub/callback with an authorization code
4. Package exchanges the code for a token and fetches the user from Hub's /api/me
5. Local user is resolved (created, linked, or retrieved — see below)
6. User is logged into the Laravel session and redirected to redirect_after_login

User Resolution

The DefaultHubUserResolver handles three scenarios on every login:

• Existing Hub user — looks up by hub_user_id, returns the local user as-is
• Email match — links the existing local account to the Hub by setting hub_user_id
• New user — creates a local account from Hub data with a null password

Username generation

If your User model has username in its $fillable array, a username is derived from the email prefix and made unique by appending a counter on collision (e.g., alice, alice1, alice2).

Role assignment

If Spatie Laravel-Permission is installed and the User model uses the HasRoles trait, new users are assigned the HUB_DEFAULT_ROLE on creation. The role must exist in the database. Role assignment is skipped (with a debug log) if the package or role is not found.

Registered Routes

Method	URI	Name	Action
GET	/login/hub	hub.login	Redirect to Hub OAuth
GET	/login/hub/callback	hub.callback	Handle Hub callback

Custom User Resolution

To override how Hub users are resolved to local users, bind your own implementation of ResolvesHubUser in a service provider:

use BeviBeverage\HubAuthClient\Contracts\ResolvesHubUser;

$this->app->bind(ResolvesHubUser::class, MyCustomUserResolver::class);

Your class must implement:

public function resolve(SocialiteUser $hubUser): Authenticatable;

Running Tests

composer test

License

MIT