README

Social / OAuth login plugin for Auth-Kit, built as a thin wrapper over Laravel Socialite. It stores linked social identities (multi-provider per user, tokens encrypted at rest), adds redirect/callback/link/unlink endpoints, and runs login hooks — while delegating the entire OAuth handshake to Socialite.

Socialite compatibility

Socialite does the OAuth handshake and returns a normalized user; it does not persist anything or link identities to your users. This plugin fills exactly that gap without reimplementing OAuth, so it stays compatible with every Socialite driver — including the community adapters from socialiteproviders.com.

Redirect delegates to Socialite::driver($provider)->redirect().
Callback pulls Socialite::driver($provider)->user(), then links/stores.
Tests use Socialite::fake() — no real OAuth round-trip.

See ADR 005 for the design rationale.

Requirements

PHP ^8.3
gusmanwidodo/auth-kit ^0.1
laravel/socialite ^5.0
Laravel 12

Installation

composer require gusmanwidodo/auth-kit-social
php artisan migrate
php artisan vendor:publish --tag=auth-kit-social-config

Configure your OAuth apps in config/services.php as you normally would for Socialite, then enable the providers in config/auth-kit-social.php:

'providers' => ['github', 'google'],

Endpoints

Method	URI	Purpose
GET	`/auth-kit/social/{provider}/redirect`	Redirect to the OAuth provider (via Socialite)
GET	`/auth-kit/social/{provider}/callback`	Handle the callback: link/store identity, run hooks
POST	`/auth-kit/social/{provider}/link`	Link a provider to an existing subject
POST	`/auth-kit/social/{provider}/unlink`	Unlink a provider from a subject

Providers not listed in config return 404 so a URL typo can't reach an unconfigured driver.

How login works

The plugin owns linking, not user creation — matching Socialite's own guidance (your app decides how a user is provisioned). On a new login, the before:social.login hook must resolve the subject (find-or-create your user):

// In any plugin implementing HasHooks, or an app service provider that
// registers into the AuthManager registry:
public function beforeHooks(): array
{
    return [
        'social.login' => function ($ctx) {
            // $ctx has: provider, provider_id, email, name, nickname
            $user = User::firstOrCreate(
                ['email' => $ctx->get('email')],
                ['name' => $ctx->get('name')],
            );
            $ctx->set('subject_type', User::class)->set('subject_id', $user->id);
            // To reject: $ctx->set('allow', false)->stop();
        },
    ];
}

On a returning login (an identity already exists for (provider, provider_id)), the subject is resolved automatically and the stored profile + tokens are refreshed — no hook needed.

Programmatic API

use Gusmanwidodo\AuthKitSocial\SocialManager;

$social = app(SocialManager::class);

// After Socialite returns a user:
$identity = $social->authenticate('github', $socialiteUser);

// Link another provider to a known subject (e.g. "connect account"):
$social->link('google', $socialiteUser, User::class, $user->id);

// Unlink:
$social->unlink('github', User::class, $user->id);

// All identities for a subject:
$social->identitiesFor(User::class, $user->id);

Multi-provider & encrypted tokens

A subject may hold multiple identities (one per provider); (provider, provider_id) is unique so the same OAuth account can't be linked twice.
OAuth token and refresh_token are stored encrypted at rest (Laravel encrypted cast). A test asserts the DB ciphertext differs from the plaintext.

Hooks

Event	When	Payload
`before:social.login`	New identity, before creation	`provider, provider_id, email, name, nickname` → set `subject_type`/`subject_id` or veto with `allow=false`
`after:social.login`	After link/login	`provider, identity_id, subject_type, subject_id, new`

Developing against a local core

composer config repositories.auth-kit path ../auth-kit
composer require gusmanwidodo/auth-kit:@dev
composer install
composer test   # 10 tests via Socialite::fake()

Note: running composer require :@dev rewrites this composer.json to @dev. Revert the gusmanwidodo/auth-kit constraint to ^0.1 (and remove any repositories block) before committing/tagging a release.

gusmanwidodo / auth-kit-social

Maintainers

Package info

Statistics

Security