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
- 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/authbecomesapp.mockatoo.globalunderdog.com/google/o/oauth2/v2/auth. - You (or a test) fill in the login page and click Authorize.
- The mock redirects back to
/auth/<provider>/callback. Socialite'suser()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/framework12,laravel/socialiteandsocialiteproviders/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-secretis the shared client. It accepts anyhttp(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
.envsetsMOCKATOO_FORCE=trueso 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
entraprovider 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.phpkeeps 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:
| Provider | What Socialite needs |
|---|---|
| Apple | response_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 |
| Discord | The openid identify email scopes. Its ID token has no email, so the driver reads it from userinfo |
| Microsoft | The 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 devpnpm 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 testThe 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
| Symptom | Fix |
|---|---|
| The real provider's login page opens | The mock isn't on: set MOCKATOO_FORCE=true in .env or the environment |
| No sign-in buttons appear | Same 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=oauth | Keep 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 error | The OpenID Connect driver needs a cache store. Without a database, set CACHE_STORE=array or file |
| A built-in driver fails after a Socialite upgrade | The driver calls an endpoint UsesMockatoo doesn't list: add its mock path in Providers.php |
| Login fails after a password change | Copy the new password from the dashboard into .env.local and your secrets |
Next steps
- All examples: Laravel, Flask, Spring Boot, Auth.js, Better Auth, SvelteKit, Nuxt and Hono
- Playwright · Email tags · Account flow · Run in CI
- Use Mockatoo only outside production, and never commit its credentials.