OAuth Authentication

Social login with Google, GitHub, Microsoft, and Apple. Built on Laravel Socialite with additional provider packages for Microsoft and Apple.

Supported Providers

• Google — via Laravel Socialite (built-in)
• GitHub — via Laravel Socialite (built-in)
• Microsoft — via socialiteproviders/microsoft
• Apple — via socialiteproviders/apple

OAuth Flow

Step 1: Redirect to Provider

GET /api/auth/oauth/{provider}/redirect

Replace {provider} with google, github, microsoft, or apple. This returns a redirect URL that the frontend uses to send the user to the provider's consent screen.

{
    "redirect_url": "https://accounts.google.com/o/oauth2/v2/auth?client_id=..."
}

Step 2: Handle Callback

GET /api/auth/oauth/{provider}/callback

After the user authorizes, the provider redirects back to this endpoint with an authorization code. The controller exchanges the code for user data and issues a Sanctum token.

{
    "token": "1|abc123def456...",
    "user": {
        "id": 1,
        "name": "John Doe",
        "email": "john@example.com",
        "avatar": "https://example.com/photo.jpg"
    },
    "is_new_user": false
}

JIT Account Creation

If no user exists with the email returned by the provider and registration is enabled, a new account is created automatically:

• Name is taken from the provider profile
• Email is automatically marked as verified (the provider has already verified it)
• Avatar URL is saved to the user's profile
• No password is set — the user can add one later from their profile
• The Registered event is fired, triggering the welcome notification

Account Linking

If a user already exists with the same email, the OAuth provider is linked to the existing account. The oauth_providers table tracks which providers are connected:

oauth_providers
├── id
├── user_id
├── provider (google, github, microsoft, apple)
├── provider_user_id
├── avatar (URL from provider)
├── created_at
└── updated_at

A user can have multiple OAuth providers linked to their account.

Avatar Sync

On each OAuth login, the user's avatar URL is updated from the provider profile. If the user has not set a custom avatar, the OAuth avatar is used as the default profile picture across the application.

Provider Configuration

Each provider requires a client_id and client_secret configured in the admin panel or environment variables:

# Environment variables (fallback)
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
GOOGLE_REDIRECT_URI=

GITHUB_CLIENT_ID=
GITHUB_CLIENT_SECRET=
GITHUB_REDIRECT_URI=

MICROSOFT_CLIENT_ID=
MICROSOFT_CLIENT_SECRET=
MICROSOFT_REDIRECT_URI=

APPLE_CLIENT_ID=
APPLE_CLIENT_SECRET=
APPLE_REDIRECT_URI=

Admin Toggles

Each provider can be independently enabled or disabled from the admin panel:

• auth.oauth.google → enabled or disabled
• auth.oauth.github → enabled or disabled
• auth.oauth.microsoft → enabled or disabled
• auth.oauth.apple → enabled or disabled

Additionally, the client_id and client_secret for each provider can be set via admin settings, overriding environment variables. When a provider is disabled, its redirect endpoint returns 403 Forbidden and the frontend hides the corresponding button.

Required Packages

The Microsoft and Apple providers require additional Socialite provider packages:

composer require socialiteproviders/microsoft
composer require socialiteproviders/apple

These are registered in the EventServiceProvider and extend Socialite's built-in provider support.