Laravel Social Auth

One-command Google and Apple social login for Laravel mobile APIs.

Supports Android and iOS with separate client IDs per platform, stateless token verification, automatic user provisioning, and Laravel Sanctum token issuance. All column names are fully configurable — no assumptions are made about your users table structure.

Requirements

• PHP 8.1 or higher
• Laravel 10 or 11
• Laravel Sanctum 3 or 4
• Laravel Socialite 5

Installation

Step 1 — Install the package via Composer:

composer require rahatulrabbi/laravel-social-auth

Step 2 — Run the install command:

php artisan social-auth:install

This single command:

• Publishes config/social-auth.php
• Publishes app/Http/Controllers/Api/Auth/SocialAuthController.php
• Publishes a migration that reads your config at runtime to create the correct columns
• Appends the necessary keys to your .env file

Step 3 — Set your credentials in .env:

CLIENT_ID_ANDROID=your-android-client-id.apps.googleusercontent.com
CLIENT_ID_IOS=your-ios-client-id.apps.googleusercontent.com
CLIENT_SECRET=
REDIRECT_URI=

Step 4 — Configure field mappings in config/social-auth.php:

Open the published config and adjust every section to match your actual users table column names. Do this before running the migration — the migration reads this config at runtime to know which columns to create.

// Name strategy: write to one column, or split into first/last
'name_field' => [
    'strategy' => 'single',   // 'single' | 'split'
    'column'   => 'name',     // used when strategy = single
    'first'    => 'first_name', // used when strategy = split
    'last'     => 'last_name',  // used when strategy = split
],

// Avatar column name and storage disk
'avatar' => [
    'enabled' => true,
    'column'  => 'avatar_path', // e.g. 'avatar', 'image', 'profile_image', 'user_image'
    'disk'    => 'local_public', // 'local_public' | any Laravel disk key
    'folder'  => env('PROFILE_IMAGE_FOLDER', 'uploads/profileImages'),
],

// Username generation — disable entirely if your table has no username column
'username' => [
    'enabled' => true,
    'column'  => 'username', // e.g. 'username', 'user_name', 'handle'
],

// Active status column
'active_status' => [
    'enabled' => true,
    'column'  => 'is_active', // e.g. 'is_active', 'status', 'active'
    'value'   => true,
],

Step 5 — Run the migration:

php artisan migrate

The migration reads your published config/social-auth.php and creates only the columns you have enabled, using exactly the column names you configured.

Step 6 — Register the SocialiteProviders event listener (Laravel 10 only).

Laravel 11 and above: this step is not required. SocialiteProviders v5+ registers itself automatically.

Laravel 10 only — open app/Providers/AppServiceProvider.php and add the following inside the boot method:

use SocialiteProviders\Manager\SocialiteWasCalled;
use Illuminate\Support\Facades\Event;

public function boot(): void
{
    Event::listen(function (SocialiteWasCalled $event) {
        $event->extendSocialite('google', \SocialiteProviders\Google\Provider::class);
        $event->extendSocialite('apple',  \SocialiteProviders\Apple\Provider::class);
    });
}

Route

The package automatically registers the following route:

POST /api/social-login

Rate limited to 5 requests per minute by default. The route prefix, path, middleware, and enabled state are all configurable in config/social-auth.php under the route key.

Request Payload

Example — Google Android:

{
  "provider": "google",
  "provider_id": "ya29.a0AfH6SMDxxxxxxxx",
  "device": "android"
}

Example — Apple iOS:

{
  "provider": "apple",
  "provider_id": "eyJraWQiOiJBMkQz...",
  "device": "ios"
}

Response

Success (200):

{
  "success": true,
  "message": "Login successful.",
  "data": {
    "user": { ... },
    "token": "1|abc123...",
    "token_type": "Bearer"
  }
}

New user registered (200):

{
  "success": true,
  "message": "User registered successfully.",
  "data": {
    "user": { ... },
    "token": "1|abc123...",
    "token_type": "Bearer"
  }
}

Invalid token (422):

{
  "success": false,
  "message": "Invalid social token or missing email.",
  "data": null
}

Server error (500):

{
  "success": false,
  "message": "Social login failed.",
  "data": {
    "error": "Detailed error message here."
  }
}

Field Mapping Reference

All field mappings are controlled from config/social-auth.php. The migration and the controller both read this config at runtime, so the two are always in sync.

Name Strategy

Avatar Storage Disk

Quick Reference

Customisation

The published SocialAuthController in your application extends the package base controller. Override any method to customise behaviour without losing future package updates.

namespace App\Http\Controllers\Api\Auth;

use RahatulRabbi\SocialAuth\Http\Controllers\SocialAuthController as BaseSocialAuthController;

class SocialAuthController extends BaseSocialAuthController
{
    // Example: assign a referral code to new users
    protected function findOrProvisionUser(mixed $socialiteUser, string $provider): mixed
    {
        $user = parent::findOrProvisionUser($socialiteUser, $provider);

        if ($user->wasRecentlyCreated) {
            $user->referral_code = \Illuminate\Support\Str::upper(\Illuminate\Support\Str::random(8));
            $user->save();
        }

        return $user;
    }
}

Available override points:

Disabling the Auto-Registered Route

Set route.enabled to false in config/social-auth.php, then define the route manually:

// routes/api.php
use App\Http\Controllers\Api\Auth\SocialAuthController;

Route::post('/social-login', [SocialAuthController::class, 'socialLogin'])
    ->middleware('throttle:5,1');

Publishing Assets Individually

# Config only
php artisan vendor:publish --tag=social-auth-config

# Controller only
php artisan vendor:publish --tag=social-auth-controller

# Migration only
php artisan vendor:publish --tag=social-auth-migrations

Uninstalling

Always run the uninstall command before composer remove. Composer only removes the package from vendor/ — it has no knowledge of the config, controller, migration, or .env keys that were published into your application. The uninstall command handles all of that.

Step 1 — Clean up published files and database columns:

php artisan social-auth:uninstall

You will be shown a summary of what will be removed and asked to confirm. The command will:

• Delete config/social-auth.php
• Delete app/Http/Controllers/Api/Auth/SocialAuthController.php
• Delete the published migration file from database/migrations/
• Roll back the migration, dropping all social auth columns from users
• Remove the social auth key block from .env
• Remove app/Http/Controllers/Api/Auth/ if it is left empty

If your SocialAuthController.php contains custom code, you will be prompted separately before that file is deleted.

Step 2 — Remove the package via Composer:

composer remove rahatulrabbi/laravel-social-auth

Available flags:

Non-interactive uninstall (CI environments):

php artisan social-auth:uninstall --force
composer remove rahatulrabbi/laravel-social-auth

Common Errors

Invalid ID token audience

The token was verified against the wrong client ID. Confirm that Android tokens are sent with device=android and iOS tokens with device=ios. Check that CLIENT_ID_ANDROID and CLIENT_ID_IOS in your .env match the credentials registered in Google Cloud Console.

No configuration found for provider [google] on device [android]

Your CLIENT_ID_ANDROID or CLIENT_ID_IOS in .env is empty. Fill in both values and run php artisan config:clear.

Undefined method stateless()

The SocialiteProviders event listener is not registered. Follow Step 6 above (Laravel 10 only).

Class "SocialiteProviders\Apple\Provider" not found

Run composer require socialiteproviders/apple. This is declared as a dependency and should be installed automatically, but may be missing if Composer constraints prevented it.

Migration created wrong column names

You ran php artisan migrate before configuring config/social-auth.php. Roll back with php artisan migrate:rollback, update your config, then migrate again.

Changelog

See CHANGELOG.md for release history.

License

MIT. See LICENSE.

Author

Built by MD. Rahatul Rabbi.