README

Schenke Io Laravel Auth Router

Helper kit for AUTH routings in Laravel applications

Laravel Auth Router streamlines adding multiple social logins to your Laravel app, saving significant developer effort. Forget complex setups; this package leverages Laravel Socialite to offer a vastly simplified experience.

One-Liner Route Setup: Instead of extensive controller code and numerous route definitions for each provider, a single line in your routes file can manage login, callback, and logout.
Pre-Built Provider Chooser: Get an immediate, customizable page on your domain for users to select their login method – no manual UI building required.
Rapid Configuration: Minimal setup is needed due to a unified route helper and familiar service configuration.
Flexible Fluent API: Customize behavior like success/error redirects, registration permission, and session persistence with a simple, readable chain.
Developer Conveniences: Includes multi-language support (DE/EN), dark mode for the chooser, and session-based error messages for easy integration into your Blade views.

It automatically handles routing, offers flexible customization for redirects and user registration, and prevents route conflicts, letting you focus on core features instead of auth boilerplate.

Schenke Io Laravel Auth Router
Providers

Installation

Install the package with composer:

composer require schenke-io/laravel-auth-router

Basic concept

In the routes/web.php file you use the Route::authRouter() macro to define which providers you want to use and your registration policy. This package handles the configuration through config/services.php.

Route::authRouter(['google', 'microsoft'])
    ->middleware(['web', 'throttle:60,1'])
    ->success('dashboard')
    ->error('login')
    ->home('home')
    ->canAddUsers(true)
    ->rememberMe(false)
    ->prefix('auth')
    ->name('auth.')
    ->debug('stack')
    ->register();

Method	Definition	Examples
`success()`	route after successful login	'dashboard'
`error()`	route after login failure, should be able to display errors as feedback	'error'
`home()`	route to a non protected view (default: 'home')	'home'
`canAddUsers()`	should unknown users be added or rejected (default: true)	`true` or `false`
`rememberMe()`	stores the login even when session expires (default: false)	`true` or `false`
`prefix()`	prefix for the URIs	'auth'
`name()`	prefix for the route names	'auth.'
`middleware()`	additional middleware for the routes	'web' or `['web', 'throttle']`
`emailConfirm()`	implementation of `EmailConfirmInterface` to handle email verification	`$myEmailConfirm`
`debug()`	log channel for debug information (registration and communication)	'stack'
`register()`	Mandatory call to actually register the routes

Route names can be same. If the homepage can display errors error() and home() could be the same. When the service configuration is not complete not all routes will be created.

Login and Logout flow

In the app just link to the login route (or auth.login if using .name('auth.')). It either displays the selector page, configuration errors or redirect to a single login provider.

For logout just do an empty POST to the logout route. Only authenticated users can use the logout.

Name conflicts

If you have multiple authentication setups or want to avoid name conflicts, use prefix() and name():

// routes/web.php
Route::authRouter('google')
    ->prefix('admin')
    ->name('admin.')
    ->success('admin.dashboard')
    ->register();

Registers the following routes when the configuration is free of errors:

/admin/login (named admin.login)
/admin/login/google (named admin.login.google)
/admin/callback/google (named admin.callback.google)
/admin/logout (named admin.logout)

Just use php artisan route:list to see which names and routes have been added.

Debugging

If you want to track the authentication process, use the debug() method with a log channel name. This will log:

Successful route registrations
Start of login and callback processes
Successful authentications (with provider and email)
Errors (with error type and details)

Configuration

There is no special configuration file; all setup is done via config/services.php.

Standard Socialite Drivers

To make a standard Socialite driver stateless, add a stateless key in its config/services.php section:

// config/services.php
'google' => [
    'client_id' => env('GOOGLE_CLIENT_ID'),
    'client_secret' => env('GOOGLE_CLIENT_SECRET'),
    'stateless' => true
],

WorkOS Drivers

WorkOS drivers require an api_key, client_id, and organization_id:

// config/services.php
'workos_google' => [
    'api_key' => env('WORKOS_API_KEY'),
    'client_id' => env('WORKOS_CLIENT_ID'),
    'organization_id' => env('WORKOS_ORGANIZATION_ID'),
],

'whatsapp' => [
    'api_key' => env('WHATSAPP_API_KEY'),
    'approved_emails' => env('WHATSAPP_APPROVED_EMAILS'),
]

Errors

The package handles two types of errors differently:

setup errors the developer can handle
runtime errors which influence the user experience

Setup errors

The setup errors are shown in the /login selector page. If you have any errors with your setup, you can fix them in config/services.php. Its mainly missing keys, or missing provider names in config/services.php.

Runtime errors

The runtime errors are stored in a session and can be handled by the app.

session key	value	language	header
authRouterErrorInfo	user message of the error	localised
authRouterErrorMessage	exception text of the provider/code	english mainly
	name of the error case		X-Custom-Error-Type

The error page could look like:

<h3>
    {{session('authRouterErrorInfo')}}
</h3>
<p>
    {{session('authRouterErrorMessage')}}
</p>

Error Cases

The following error names are used in the X-Custom-Error-Type header and define the error's source:

Error Name	Description
`UnknownService`	The requested login provider is unknown.
`ServiceNotSet`	The provider service is not defined in config.
`ConfigNotSet`	A specific config value (e.g., client_id) is missing.
`UnableToAddNewUsers`	New user registration is disabled in the macro call.
`EmailMissing`	The provider did not return an email address.
`InvalidEmail`	The returned email address is invalid.
`LocalAuth`	Local authentication process failed.
`RemoteAuth`	The third-party provider returned an error.
`State`	OAuth state mismatch (potential CSRF).
`Network`	A network error occurred during the callback.
`InvalidRequest`	The login or callback request was invalid.
`MixedProviders`	Mixing WorkOS and non-WorkOS providers is not allowed.
`InvalidCredentials`	The provided credentials (email/password) are incorrect.

Example Google login

In the .env file you have the credentials:

GOOGLE_CLIENT_ID=24242343242
GOOGLE_CLIENT_SECRET=3843430984

In config/services.php you define the service:

// config/services.php
'google' => [
    'client_id' => env('GOOGLE_CLIENT_ID'),
    'client_secret' => env('GOOGLE_CLIENT_SECRET')
]

In the routes/web.php you define the route:

// routes/web.php
Route::authRouter('google')
    ->success('dashboard')
    ->error('error')
    ->home('home')
    ->register();

Advanced Example

If you want a selection of logins you basically just do:

Fill the secret data into .env.
Register the services in config/services.php.
Add the routes:

// routes/web.php
Route::authRouter(['google','paypal','microsoft'])
    ->success('dashboard')
    ->error('error')
    ->home('home')
    ->canAddUsers(true)
    ->register();

Route Prefixing and Naming

To avoid route name conflicts or to group authentication routes under a specific path, you can use the prefix() and name() methods:

// routes/web.php
Route::authRouter('google')
    ->prefix('auth')
    ->name('auth.')
    ->success('dashboard')
    ->register();

This generates routes like /auth/login, /auth/callback/google, and route names like auth.login, auth.login.google.

Key Classes

Class	Summary
`Service`	All supported authentication services.
`UserData`	Data object for user information, mapping different provider user formats.

Providers

The following providers are supported:

amazon
auth0
facebook
google
linkedin
microsoft
paypal
stripe
apple
whatsapp
custom
workos_apple
workos_email
workos_google
workos_linkedin

WorkOS Configuration

To use WorkOS providers, you must set the following environment variables:

WORKOS_API_KEY (stored in services.workos.api_key)
WORKOS_CLIENT_ID (stored in services.workos.client_id)
WORKOS_ORGANIZATION_ID (stored in services.workos.organization_id)

WhatsApp Configuration

To use WhatsApp login, you must set the following environment variables:

WHATSAPP_API_KEY (stored in services.whatsapp.api_key)
WHATSAPP_APPROVED_EMAILS (stored in services.whatsapp.approved_emails) - a comma-separated list of approved emails.

WhatsApp login requires an approved email to be provided first. The flow includes a button to start the login and a waiting page for the user to confirm via their WhatsApp device.

Email and Password Flow

The workos_email provider supports both magic link flows (GET) and direct email/password authentication (POST). The login view includes fields for both, allowing users to choose their preferred method.

Apple Configuration

To use Apple Sign-In, you must set the following environment variables:

APPLE_CLIENT_ID (your Service ID)
APPLE_TEAM_ID (your Apple Team ID)
APPLE_KEY_ID (your Apple Key ID)
APPLE_PRIVATE_KEY (the content of your .p8 key file)

The package automatically handles dynamic client secret generation required by Apple.

Server-to-Server Notifications

Apple can send notifications when a user disables email relay or revokes consent. This package provides a webhook handler for these events.

Webhook URL: https://your-app.com/auth/apple/webhook (assuming default prefix)

Configuration:

In the Apple Developer portal, set the "Server-to-Server Notification Endpoint" to the URL above.
Ensure the route is excluded from CSRF protection in your application.

In Laravel 11+, you can do this in bootstrap/app.php:

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

The handler will:

Mark email_verified_at as null if the user disables email relay.

Apple Socialite Callback

Apple Sign-In is unique because it only provides the user's name and email on the first successful authentication ("One-Shot"). Subsequent logins only provide the unique Apple ID (sub claim).

This package handles this by:

Returning User: Checking for an existing user by their email.
New User (One-Shot): Creating a new user and capturing the name and email provided by Apple on their first login.

Custom Provider

The custom provider is a flexible authentication option that can be fully configured via your config/services.php and .env file. It leverages Laravel Socialite to provide a "free programmable" login flow.

Real vs. Fake Usage

In your .env file, you can define the service keys for the custom provider.

Real Provider: To connect to a real OAuth service, provide the actual client credentials:

CUSTOM_CLIENT_ID=your-real-client-id
CUSTOM_CLIENT_SECRET=your-real-client-secret
CUSTOM_REDIRECT_URI=https://your-app.com/auth/custom/callback

Fake Provider (Mocking): For local development or CI, you can use a mock driver or a "fake" configuration. Since the custom provider uses standard Socialite logic, you can easily mock it in your tests:

Socialite::fake();

This allows you to test the entire login flow without ever making a real network request.

Restriction: Mixing Providers

A collection of login providers passed to Route::authRouter must NOT contain a mix of WorkOS and non-WorkOS providers. If any WorkOS provider is present, all other providers in that same set must also be WorkOS providers.

ID	Detail	Link
amazon	Social login with Amazon	https://developer.amazon.com/
google	social login with Google	https://console.cloud.google.com/
linkedin	Social login with LinkedIn	https://developer.linkedin.com/
microsoft	Social login with Microsoft	https://portal.azure.com/
paypal	Social login with PayPal	https://developer.paypal.com/
auth0	social login with Auth0	https://auth0.com/developers
facebook	Social login with Facebook	https://developers.facebook.com/
stripe	Social login with Stripe	https://dashboard.stripe.com/
whatsapp	WhatsApp login provider implementation.	??
apple	Social login with Apple.	https://developer.apple.com/sign-in-with-apple/
custom	A free programmable login provider.	??
workos	Social login with WorkOS	https://workos.com/docs/user-management
logto		??
passkey	Passkey login provider implementation.	??

Amazon Provider

First go to https://developer.amazon.com/ Go to Developer Portal, create a Developer Account, create a Security Profile under "Login with Amazon", find Client ID and Secret in "Web Settings."

Edit the .env file in your Laravel project and add the credentials:

AMAZON_CLIENT_ID=...
AMAZON_CLIENT_SECRET=...

Edit the config/services.php file:

    'amazon' => [
        'client_id' => env('AMAZON_CLIENT_ID'),
        'client_secret' => env('AMAZON_CLIENT_SECRET'),
    ],

You do not need to configure the callback URL, it will be automatically added

Google Provider

First go to https://console.cloud.google.com/ Go to Google Cloud Console, create a Project, configure OAuth Consent Screen, create OAuth client ID, find Client ID and Secret under Credentials.

Edit the .env file in your Laravel project and add the credentials:

GOOGLE_CLIENT_ID=...
GOOGLE_CLIENT_SECRET=...

Edit the config/services.php file:

    'google' => [
        'client_id' => env('GOOGLE_CLIENT_ID'),
        'client_secret' => env('GOOGLE_CLIENT_SECRET'),
    ],

You do not need to configure the callback URL, it will be automatically added

Linkedin Provider

First go to https://developer.linkedin.com/ Go to Developer Portal, sign in, navigate to "My Apps," create an Application, find Client ID and Secret under "Authentication Keys" in "Authentication" settings.

Edit the .env file in your Laravel project and add the credentials:

LINKEDIN_CLIENT_ID=...
LINKEDIN_CLIENT_SECRET=...

Edit the config/services.php file:

    'linkedin' => [
        'client_id' => env('LINKEDIN_CLIENT_ID'),
        'client_secret' => env('LINKEDIN_CLIENT_SECRET'),
    ],

You do not need to configure the callback URL, it will be automatically added

Microsoft Provider

First go to https://portal.azure.com/ Go to Azure Portal, navigate to Azure Active Directory (or Entra ID), select "App registrations," register a new application, find Application (client) ID on "Overview," generate Client Secret under "Certificates & secrets."

Edit the .env file in your Laravel project and add the credentials:

MICROSOFT_CLIENT_ID=...
MICROSOFT_CLIENT_SECRET=...

Edit the config/services.php file:

    'microsoft' => [
        'client_id' => env('MICROSOFT_CLIENT_ID'),
        'client_secret' => env('MICROSOFT_CLIENT_SECRET'),
    ],

You do not need to configure the callback URL, it will be automatically added

Paypal Provider

First go to https://developer.paypal.com/ Go to Developer Portal, log in with business account, navigate to "Apps & Credentials," choose Sandbox or Live, create an App, find Client ID and Secret on the app details page.

Edit the .env file in your Laravel project and add the credentials:

PAYPAL_CLIENT_ID=...
PAYPAL_CLIENT_SECRET=...

Edit the config/services.php file:

    'paypal' => [
        'client_id' => env('PAYPAL_CLIENT_ID'),
        'client_secret' => env('PAYPAL_CLIENT_SECRET'),
    ],

You do not need to configure the callback URL, it will be automatically added

Auth0 Provider

First go to https://auth0.com/developers Go to Auth0 Dashboard, navigate to "Applications," create a new Application, find Client ID and Secret on the "Settings" tab under "Basic Information."

Edit the .env file in your Laravel project and add the credentials:

AUTH0_CLIENT_ID=...
AUTH0_CLIENT_SECRET=...
AUTH0_DOMAIN=...
AUTH0_COOKIE_SECRET=...

Edit the config/services.php file:

    'auth0' => [
        'client_id' => env('AUTH0_CLIENT_ID'),
        'client_secret' => env('AUTH0_CLIENT_SECRET'),
        'domain' => env('AUTH0_DOMAIN'),
        'cookie_secret' => env('AUTH0_COOKIE_SECRET'),
    ],

You do not need to configure the callback URL, it will be automatically added

Facebook Provider

First go to https://developers.facebook.com/ Go to Meta for Developers, log in, navigate to "My Apps," create an App, find App ID on the dashboard or under "Settings" -> "Basic," find App Secret under "Settings" -> "Basic" (click "Show").

Edit the .env file in your Laravel project and add the credentials:

FACEBOOK_CLIENT_ID=...
FACEBOOK_CLIENT_SECRET=...

Edit the config/services.php file:

    'facebook' => [
        'client_id' => env('FACEBOOK_CLIENT_ID'),
        'client_secret' => env('FACEBOOK_CLIENT_SECRET'),
    ],

You do not need to configure the callback URL, it will be automatically added

Stripe Provider

First go to https://dashboard.stripe.com/ Go to Stripe Dashboard, navigate to "Connect" -> "Settings" -> "OAuth settings" to find Client ID, navigate to "Developers" -> "API keys" to find Secret API Key (acts as client secret).

Edit the .env file in your Laravel project and add the credentials:

STRIPE_CLIENT_ID=...
STRIPE_CLIENT_SECRET=...

Edit the config/services.php file:

    'stripe' => [
        'client_id' => env('STRIPE_CLIENT_ID'),
        'client_secret' => env('STRIPE_CLIENT_SECRET'),
    ],

You do not need to configure the callback URL, it will be automatically added

Whatsapp Provider

First go to ?? This provider handles WhatsApp-specific authentication logic.

Edit the .env file in your Laravel project and add the credentials:

WHATSAPP_API_KEY=...
WHATSAPP_APPROVED_EMAILS=...

Edit the config/services.php file:

    'whatsapp' => [
        'api_key' => env('WHATSAPP_API_KEY'),
        'approved_emails' => env('WHATSAPP_APPROVED_EMAILS'),
    ],

You do not need to configure the callback URL, it will be automatically added

Apple Provider

First go to https://developer.apple.com/sign-in-with-apple/ This provider uses dynamic client secret generation via AppleTokenGenerator. It also handles Server-to-Server notifications.

Edit the .env file in your Laravel project and add the credentials:

APPLE_CLIENT_ID=...
APPLE_TEAM_ID=...
APPLE_KEY_ID=...
APPLE_PRIVATE_KEY=...

Edit the config/services.php file:

    'apple' => [
        'client_id' => env('APPLE_CLIENT_ID'),
        'team_id' => env('APPLE_TEAM_ID'),
        'key_id' => env('APPLE_KEY_ID'),
        'private_key' => env('APPLE_PRIVATE_KEY'),
    ],

You do not need to configure the callback URL, it will be automatically added

Custom Provider

First go to ?? This provider allows for flexible configuration using environment variables. It utilizes Laravel Socialite to handle the authentication flow.

Edit the .env file in your Laravel project and add the credentials:

CUSTOM_CLIENT_ID=...
CUSTOM_CLIENT_SECRET=...

Edit the config/services.php file:

    'custom' => [
        'client_id' => env('CUSTOM_CLIENT_ID'),
        'client_secret' => env('CUSTOM_CLIENT_SECRET'),
    ],

You do not need to configure the callback URL, it will be automatically added

Workos Provider

First go to https://workos.com/docs/user-management

Edit the .env file in your Laravel project and add the credentials:

WORKOS_CLIENT_ID=...
WORKOS_API_KEY=...
WORKOS_CLIENT_SECRET=...

Edit the config/services.php file:

    'workos' => [
        'client_id' => env('WORKOS_CLIENT_ID'),
        'api_key' => env('WORKOS_API_KEY'),
        'client_secret' => env('WORKOS_CLIENT_SECRET'),
    ],

You do not need to configure the callback URL, it will be automatically added

Logto Provider

First go to ??

Edit the .env file in your Laravel project and add the credentials:

LOGTO_ENDPOINT=...
LOGTO_APP_ID=...
LOGTO_APP_SECRET=...

Edit the config/services.php file:

    'logto' => [
        'endpoint' => env('LOGTO_ENDPOINT'),
        'app_id' => env('LOGTO_APP_ID'),
        'app_secret' => env('LOGTO_APP_SECRET'),
    ],

You do not need to configure the callback URL, it will be automatically added

Passkey Provider

First go to ??

Edit the .env file in your Laravel project and add the credentials:

Edit the config/services.php file:

    'passkey' => [
    ],

You do not need to configure the callback URL, it will be automatically added

Markdown file generated by schenke-io/packaging-tools

schenke-io / laravel-auth-router

Maintainers

Package info

Statistics

Security

README

Schenke Io Laravel Auth Router

Contents

Installation

Basic concept

Login and Logout flow

Name conflicts

Debugging

Configuration

Standard Socialite Drivers

WorkOS Drivers

Errors

Setup errors

Runtime errors

Error Cases

Example Google login

Advanced Example

Route Prefixing and Naming

Key Classes

Providers

WorkOS Configuration

WhatsApp Configuration

Email and Password Flow

Apple Configuration

Server-to-Server Notifications

Apple Socialite Callback

Custom Provider

Real vs. Fake Usage

Restriction: Mixing Providers

Amazon Provider

Google Provider

Linkedin Provider

Microsoft Provider

Paypal Provider

Auth0 Provider

Facebook Provider

Stripe Provider

Whatsapp Provider

Apple Provider

Custom Provider

Workos Provider

Logto Provider

Passkey Provider