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:

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

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