OAuth Providers

This is the smallest module type.

Read Fundamentals first if you haven’t.

Generate it

php artisan make:module Acme --type=provider
php artisan module:enable AcmeProvider
php artisan module:migrate AcmeProvider
php artisan module:doctor AcmeProvider

You also need a logo, or the login button will not render:

public/modules-logos/acme-provider.png

What you get

Modules/Providers/AcmeProvider/
├── module.json                 link_url, link_column, colors
├── app/
│   ├── Providers/
│   ├── Http/Controllers/
│   │   ├── AcmeController      redirect, callback, unlink
│   │   └── SettingsController
│   └── Models/AcmeCredential
├── database/migrations/        credentials table, and users.acme_id
└── routes/

Three manifest keys do all the work

module.json

"link_url": "/auth/acme/redirect",
"link_column": "acme_id",
"logo": "/modules-logos/acme-provider.png",
"colors": { "bg": "#FF6B35", "text": "#FFFFFF", "hover": "#E55A2B" }

string

required

Where the button sends people. Must match your actual route exactly.

string

required

The users column holding the external account ID. Also how “is this linked?” gets answered.

string

required

Path under public/.

object

Button branding: bg, text, hover. Falls back to a built-in table by provider name.

A provider missing any of the first three gets skipped in silence, so the button just never shows up. module:doctor reports it as an error.

OAuthProviderRegistry reads them, and the login page, market checkout and profile page all get their provider list from it.

Install a Socialite driver

Most providers are on socialiteproviders.com. Google, GitHub, Facebook, X, LinkedIn, GitLab and Bitbucket ship with laravel/socialite already. Then uncomment two lines in your service provider:

class AcmeProviderServiceProvider extends OAuthProviderServiceProvider
{
    protected ?string $socialiteDriver = 'acme';
    protected ?string $socialiteProvider = \SocialiteProviders\Acme\Provider::class;
}

For a driver built into laravel/socialite, leave both out.

Credentials come from the database

Admins configure OAuth apps in the UI, not in .env, so you pass config per request:

Socialite::driver('acme')->setConfig(new Config(
    $credential->client_id,
    $credential->client_secret,
    route('acme.callback'),
));

The generated controller has a driver() helper that does this and returns null when the module isn’t configured yet.

The callback has three cases

The generated controller handles all three. Worth knowing what each one is.

Already signed in
Known external ID
Brand new

Link the account, but refuse if that external ID belongs to someone else:

$taken = User::where('acme_id', $oauthUser->getId())
    ->where('id', '!=', $user->id)
    ->exists();

Skip that check and one external account can be attached to several DezerX users, which is an account-takeover path.

Hand it to core:

$user = $this->registration->registerViaOAuth(
    $oauthUser,
    'acme',        // notification channel
    'Acme',        // shown to the user
    'acme_id',     // the users column
    $oauthUser->getAvatar(),
);

The one rule you shouldn’t relax

registerViaOAuth() resolves in this order:

Match the external ID

Found, so refresh the avatar and sign them in.

Match the email, but only if that account already has this provider's ID

Same result.

No match, so create the user

Fires Registered and sends the welcome notification.

If the email matches an account that was never linked to this provider, it throws:

An account with this email already exists but is not linked to Acme. Please log in with your password first, then link your Acme account from your profile settings.

That looks unhelpful and it’s deliberate. Auto-linking on email alone means anyone who can set that address at the provider takes over the DezerX account, and not every provider verifies email addresses.Discord and GitHub always refused. Google used to auto-link, and no longer does.

Your catch block should surface that message rather than a generic failure:

if (str_contains($e->getMessage(), 'already exists but is not linked to Acme')) {
    return redirect('/login')->with('error', $e->getMessage());
}

The generator writes this for you. The exact phrasing is what the check matches on, so don’t reword it.

Unlinking

Provide the route. The generated controller already refuses to unlink someone’s only way back in:

if (empty($user->password)) {
    return back()->with('error', 'Set a password before unlinking your only sign-in method.');
}

Fire an event if other modules should react. DiscordProvider removes Discord roles on unlink.

Test it

php artisan module:doctor AcmeProvider

Fresh sign-up creates the account and sends exactly one welcome email

Sign out, sign back in: same account, not a duplicate

A password account can link from the profile page and shows as linked

Linking the same external account to a second user is rejected

Unlink clears the column and the button says “Link” again

Disabling the module removes the button from login and profile

An email matching an unlinked account gives the actionable message, not “Authentication failed”

Worth reading

GoogleProvider

The minimal version.

GithubProvider

Same shape, different driver.

DiscordProvider

What this can grow into: role sync and 17 listeners sending DMs.

If your provider has a notification channel or a roles concept, DiscordProvider is the pattern to copy. It’s just core events, covered in Fundamentals.

GETTING STARTED

MAKE YOUR OWN

SPARTAN THEMES

Generate it

Three manifest keys do all the work

Install a Socialite driver

Credentials come from the database

The callback has three cases

The one rule you shouldn’t relax

Unlinking

Test it

Worth reading

GoogleProvider

GithubProvider

DiscordProvider

​Generate it

​Three manifest keys do all the work

​Install a Socialite driver

​Credentials come from the database

​The callback has three cases

​The one rule you shouldn’t relax

​Unlinking

​Test it

​Worth reading

GoogleProvider

GithubProvider

DiscordProvider

Generate it

Three manifest keys do all the work

Install a Socialite driver

Credentials come from the database

The callback has three cases

The one rule you shouldn’t relax

Unlinking

Test it

Worth reading