Laravel

Sign in through OAuth in a Laravel app, locally and in CI, with any of the eight providers Mockatoo mocks.

Example on GitHub: mockatoo/examples/socialite-laravel.

How it works

  1. Your sign-in route calls Socialite's redirect(), which sends the browser to the mock on the provider's real paths: accounts.google.com/o/oauth2/v2/auth becomes app.mockatoo.globalunderdog.com/google/o/oauth2/v2/auth.
  2. You (or a test) fill in the login page and click Authorize.
  3. The mock redirects back to /auth/<provider>/callback. Socialite's user() checks the OAuth state, exchanges the code for provider-shaped tokens and fetches the profile, as it would in production.

Your routes, scopes and callbacks don't change. Only the client credentials and the provider URLs do, and only when the mock is on.

Prerequisites

  • PHP 8.3, Composer 2, Node.js 24 and pnpm 10, with laravel/framework 12, laravel/socialite and socialiteproviders/openidconnect (composer.json). Node.js runs only the Playwright tests.
  • A Mockatoo test account. Sign up at app.mockatoo.globalunderdog.com, then copy the email and password from the dashboard.

Turn the mock on

config/services.php reads one switch, next to each provider's usual Socialite settings:

'mockatoo' => [    'enabled' => env('MOCKATOO_FORCE') === true,    'origin' => rtrim(env('MOCKATOO_URL') ?: 'https://app.mockatoo.globalunderdog.com', '/'),],

When it is on, app/Socialite/Providers.php registers every driver with the mock's shared client and a callback built from the request:

if ($mock) {    $config['client_id'] = 'mockatoo';    $config['client_secret'] = 'mockatoo-secret';    $config['redirect'] = url("/auth/$id/callback");}
  • mockatoo / mockatoo-secret is the shared client. It accepts any http(s) callback, so localhost and preview URLs need no provider setup.
  • url() builds the callback from the request, so each localhost port and preview deployment uses its own.
  • The example's committed .env sets MOCKATOO_FORCE=true so its live demo works. In your app, turn the mock on only outside production. Never ship it.

Point the drivers at the mock

Socialite's drivers hard-code the provider URLs, so the example handles them in two ways.

Google, GitHub, Facebook, LinkedIn and X keep Socialite's built-in drivers, with their scopes, token exchange and profile mapping. The UsesMockatoo trait replaces the authorization URL and gives the driver a Guzzle client that sends each provider request to the mock's matching path:

$stack->push(Middleware::mapRequest(function (RequestInterface $request) use ($origin, $endpoints) {    $uri = $request->getUri();    $endpoint = (string) $uri->withQuery('');    // Fail closed if a Socialite upgrade changes an endpoint.    $path = $endpoints[$endpoint] ?? throw new LogicException('Missing Mockatoo endpoint.');    return $request->withUri(new Uri($origin.$path.'?'.$uri->getQuery()));}));

Each driver lists the endpoints it calls. GitHub's, from Providers.php:

new class (...$args) extends GithubProvider { use UsesMockatoo; },'/github/login/oauth/authorize',[    'https://github.com/login/oauth/access_token' => '/github/login/oauth/access_token',    'https://api.github.com/user' => '/github/api/v3/user',    'https://api.github.com/user/emails' => '/github/api/v3/user/emails',],

With the mock, the example also pins Facebook's Graph API version (v24.0) so its endpoints match the mock's paths.

Apple, Discord and Microsoft have no Socialite driver. They all publish OpenID Connect discovery, so the example uses the generic OpenID Connect driver from Socialite Providers. It reads the endpoints and signing keys from the issuer and verifies the ID token's signature, issuer, audience, expiry and nonce. Only the issuer changes for the mock:

[$class, $issuer, $scopes] = match ($id) {    'apple' => [OpenIDConnectProvider::class, $mock ? "$mock/apple" : 'https://appleid.apple.com', ['openid', 'email']],    'discord' => [OpenIDConnectProvider::class, $mock ? "$mock/discord" : 'https://discord.com', ['openid', 'identify', 'email']],    'microsoft' => [        EntraProvider::class,        ($mock ? "$mock/login.microsoftonline.com" : 'https://login.microsoftonline.com')."/$tenant/v2.0",        ['openid', 'profile', 'email'],    ],};$driver = $socialite->buildProvider($class, $config);$driver->setConfig(new Config($config['client_id'], $config['client_secret'], $config['redirect'], [    'base_url' => $issuer,    'scopes' => $scopes,    'tenant' => $tenant,]));
  • For Microsoft, use the driver's entra provider class, which handles multi-tenant issuers. With the mock, the example uses a concrete tenant ID so the issuer matches the ID token.
  • The driver caches discovery documents and keys in Laravel's cache. The example has no database, so config/cache.php keeps them in memory. Your app's usual cache store works.

Copy the paths and issuers for all eight providers from Providers.php. Already have Socialite drivers? Keep them, and in development or CI point them at the mock the same way.

Sign in and read the user

routes/web.php uses the same two Socialite calls for every provider, real or mock (checks trimmed):

Route::post('/sign-in/{provider}', function (Request $request, string $provider) {    return Socialite::driver($provider)->redirect();});$callback = function (Request $request, string $provider = 'apple') {    $user = Socialite::driver($provider)->user();    $request->session()->regenerate();    $request->session()->put('profile', [        'provider' => Providers::LABELS[$provider],        'id' => (string) $user->getId(),        'email' => $user->getEmail(),    ]);    return redirect('/', 303);};Route::get('/auth/{provider}/callback', $callback);Route::post('/auth/apple/callback', $callback);

The example stores only the provider, account ID and email in an encrypted cookie session, and discards the provider tokens.

Handle provider differences

These settings match the real providers, so they belong in your app whether or not you use the mock. The example handles them in Providers.php, bootstrap/app.php and config/session.php:

ProviderWhat Socialite needs
Appleresponse_mode=form_post and the openid email scopes (Apple rejects profile), a CSRF-exempt POST /auth/apple/callback, and a SameSite=None; Secure session cookie
DiscordThe openid identify email scopes. Its ID token has no email, so the driver reads it from userinfo
MicrosoftThe tenant from MICROSOFT_TENANT_ID (default common). The entra provider reads the email from preferred_username, which needs the profile scope

Apple's callback is a cross-site POST, so exempt it from CSRF in bootstrap/app.php. The driver still validates the OAuth state and nonce:

->withMiddleware(function (Middleware $middleware) {    $middleware->validateCsrfTokens(except: ['auth/apple/callback']);})

See each provider's page, e.g. Apple or Microsoft, for its flow and known differences.

Run it

pnpm installpnpm buildprintf 'APP_KEY=base64:%s\n' "$(openssl rand -base64 32)" > .env.localpnpm dev

pnpm build runs composer install, and pnpm dev serves the app with PHP's built-in server (package.json). Open http://localhost:3000, pick a provider, and sign in with your dashboard email and password. To sign in as another user, add a tag to the email, e.g. you+alice@example.com (see Email tags).

Test with Playwright

The example tests the Laravel app with Playwright, which only needs a running server. playwright.config.ts installs the app and starts it, or tests a deployment when PLAYWRIGHT_BASE_URL is set:

const deployedURL = process.env.PLAYWRIGHT_BASE_URL;const localURL = `http://localhost:${process.env.PORT || "3000"}`;export default defineConfig({	testDir: "./tests",	use: { baseURL: deployedURL || localURL },	webServer: deployedURL		? undefined		: { command: "pnpm build && pnpm start", url: localURL, timeout: 120000 },});

tests/sign-in.spec.ts signs in, checks the session survives a reload, signs out, and declines consent with every provider:

await page.goto("/");await page	.getByRole("button", { name: `Sign in with ${provider}`, exact: true })	.click();await page.getByLabel("Email", { exact: true }).fill(email);await page.getByLabel("Password", { exact: true }).fill(password);await page.getByRole("button", { name: "Log in with password" }).click();await page.getByRole("button", { name: decision, exact: true }).click();

Add MOCKATOO_TEST_EMAIL and MOCKATOO_TEST_PASSWORD to .env.local or the environment, then run:

pnpm exec playwright install chromiumpnpm test

The Playwright guide covers fresh users per test, edge-case tags and token refresh. Those tests work the same against a Laravel app.

Run in CI

The example's workflow sets up PHP and Node.js, generates an app key, then runs the tests with the credentials as secrets:

- uses: shivammathur/setup-php@v2  with:    php-version: "8.3"    extensions: mbstring, dom, curl, zip    tools: composer:v2- run: pnpm --dir socialite-laravel build- name: Generate runtime secret  run: echo "APP_KEY=base64:$(openssl rand -base64 32)" >> "$GITHUB_ENV"- run: pnpm --dir socialite-laravel exec playwright install --with-deps chromium- run: pnpm --dir socialite-laravel test  env:    MOCKATOO_TEST_EMAIL: ${{ secrets.MOCKATOO_TEST_EMAIL }}    MOCKATOO_TEST_PASSWORD: ${{ secrets.MOCKATOO_TEST_PASSWORD }}

More in Run in CI.

Troubleshooting

SymptomFix
The real provider's login page opensThe mock isn't on: set MOCKATOO_FORCE=true in .env or the environment
No sign-in buttons appearSame cause: without the mock, the example hides providers that have no real credentials
Set APP_KEY to a generated Laravel application key.Add APP_KEY=base64: and the output of openssl rand -base64 32 to .env.local
Apple sign-in ends on /?error=oauthKeep the CSRF exemption and the SameSite=None; Secure cookie for Apple, and use HTTPS or Chromium's localhost
Apple, Discord or Microsoft fails with a database errorThe OpenID Connect driver needs a cache store. Without a database, set CACHE_STORE=array or file
A built-in driver fails after a Socialite upgradeThe driver calls an endpoint UsesMockatoo doesn't list: add its mock path in Providers.php
Login fails after a password changeCopy the new password from the dashboard into .env.local and your secrets

Next steps