laravel-socialite

Trigger Keywords

This skill automatically activates when Claude detects these keywords:

Overview

The laravel-socialite skill provides expertise for social authentication using OAuth. It covers setup for Google, GitHub, Facebook, and 100+ other providers through community packages.

What This Skill Provides

• OAuth Setup - Configure social providers
• User Creation - Create/link users from OAuth data
• Account Linking - Link multiple social accounts
• Scopes - Request additional permissions
• Community Providers - Apple, Discord, Microsoft, etc.

Quick Start

# Install Socialite
composer require laravel/socialite

Configuration

<?php

// config/services.php
return [
    'github' => [
        'client_id' => env('GITHUB_CLIENT_ID'),
        'client_secret' => env('GITHUB_CLIENT_SECRET'),
        'redirect' => env('GITHUB_REDIRECT_URI'),
    ],

    'google' => [
        'client_id' => env('GOOGLE_CLIENT_ID'),
        'client_secret' => env('GOOGLE_CLIENT_SECRET'),
        'redirect' => env('GOOGLE_REDIRECT_URI'),
    ],
];

Routes

Route::get('/auth/{provider}/redirect', [SocialiteController::class, 'redirect']);
Route::get('/auth/{provider}/callback', [SocialiteController::class, 'callback']);

Controller

<?php

use Laravel\Socialite\Facades\Socialite;

class SocialiteController extends Controller
{
    public function redirect(string $provider)
    {
        return Socialite::driver($provider)->redirect();
    }

    public function callback(string $provider)
    {
        $socialUser = Socialite::driver($provider)->user();

        $user = User::updateOrCreate(
            ['provider' => $provider, 'provider_id' => $socialUser->getId()],
            [
                'name' => $socialUser->getName(),
                'email' => $socialUser->getEmail(),
                'avatar' => $socialUser->getAvatar(),
            ]
        );

        Auth::login($user);

        return redirect('/dashboard');
    }
}

Requesting Scopes

return Socialite::driver('github')
    ->scopes(['read:user', 'public_repo'])
    ->redirect();

return Socialite::driver('google')
    ->with(['hd' => 'example.com']) // Restrict to domain
    ->redirect();

Stateless (API)

// For API/token-based flows
$user = Socialite::driver('github')->stateless()->user();

Supported Providers

Community Providers

# Install community provider
composer require socialiteproviders/discord

// EventServiceProvider
protected $listen = [
    \SocialiteProviders\Manager\SocialiteWasCalled::class => [
        \SocialiteProviders\Discord\DiscordExtendSocialite::class.'@handle',
    ],
];

Testing

use Laravel\Socialite\Facades\Socialite;
use Mockery;

it('authenticates with github', function () {
    $socialiteUser = Mockery::mock(\Laravel\Socialite\Two\User::class);
    $socialiteUser->shouldReceive('getId')->andReturn('12345');
    $socialiteUser->shouldReceive('getName')->andReturn('John Doe');
    $socialiteUser->shouldReceive('getEmail')->andReturn('john@example.com');

    Socialite::shouldReceive('driver->user')->andReturn($socialiteUser);

    $this->get('/auth/github/callback')
        ->assertRedirect('/dashboard');
});

Common Pitfalls

• Wrong redirect URI - Must exactly match provider settings
• Missing provider validation - Validate provider name
• Email conflicts - Handle existing users with same email
• Missing email - Some providers don't return email
• HTTPS required - Production must use HTTPS

Best Practices

• Validate provider names to prevent errors
• Handle OAuth exceptions gracefully
• Allow linking multiple social accounts
• Store and encrypt access tokens
• Handle missing email addresses
• Use HTTPS for redirect URIs
• Log social authentication events

Related Skills

• laravel-auth - Authentication and authorization
• laravel-sanctum - API token authentication