Implement SAML SSO Authentication in Laravel Filament with Socialite

Single Sign-On (SSO) is a common requirement in enterprise applications.

When working with Laravel Filament in internal business environments, clients often want to authenticate users directly through:

• Active Directory
• Microsoft Entra ID (Azure AD)
• Okta
• Keycloak
• Google Workspace

Instead of managing passwords inside your application.

In this article, we’ll build a clean SAML SSO integration using:

• Laravel Socialite
• The Socialite SAML2 provider

The goal is not only to make authentication work, but also to build a maintainable foundation for enterprise environments.

At the end of this article, you’ll have:

• SAML authentication working inside Filament
• A metadata endpoint for your Identity Provider
• A dedicated authentication flow
• A clean architecture ready for role synchronization

In the premium follow-up article, we’ll implement:

• Active Directory group mapping
• Spatie Permission synchronization
• Production-ready role handling
• Enterprise access control strategies

Installing the SAML2 Provider

First, install Laravel Socialite and the SAML2 provider:

composer require laravel/socialite
composer require socialiteproviders/saml2

You can then configure your SAML provider inside config/services.php.

Configuring the SAML Provider

Here is a simple SAML configuration:

'saml2' => [
    'metadata' => env('SAML2_METADATA_URL', 'http://localhost:4000/api/saml/metadata'),
    'sp_acs' => 'auth/saml2/callback',
    'sp_default_binding_method' => \LightSaml\SamlConstants::BINDING_SAML2_HTTP_POST,
    'sp_name_id_format' => 'urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified',
],

Depending on your security requirements, you may also need signed or encrypted assertions.

Understanding the Configuration

metadata

This is the Identity Provider metadata URL.

Depending on your environment, this could come from:

• Microsoft Entra ID
• Okta
• Keycloak
• A local SAML testing provider

The provider uses this metadata to retrieve:

• certificates
• SSO endpoints
• bindings
• entity identifiers

sp_acs

This is your Assertion Consumer Service (ACS) endpoint.

After authentication, the Identity Provider redirects the user back to this endpoint.

In our case:

/auth/saml2/callback

sp_default_binding_method

This defines how SAML responses are transmitted.

Using POST binding is generally the safest and most common option.

Creating the Controller

A dedicated controller keeps the authentication flow clean and isolated.

<?php

namespace App\Http\Controllers\Auth;

use App\Services\SAML2Service;
use Filament\Notifications\Notification;
use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Response;

class SAML2Controller extends Controller
{
    public function __construct(protected SAML2Service $saml2Service) {}

    public function metadata(): Response
    {
        return $this->saml2Service->metadata();
    }

    public function redirect(): RedirectResponse
    {
        return $this->saml2Service->redirect();
    }

    public function callback(): RedirectResponse
    {
        $user = $this->saml2Service->callback();

        if (! $user) {
            Notification::make()
                ->title(__('Unable to connect. Please contact an administrator.'))
                ->danger()
                ->send();
        }

        return redirect(filament()->getUrl());
    }
}

Why Use a Dedicated Service?

Many authentication tutorials place all the logic directly inside the controller.

This quickly becomes difficult to maintain when adding:

• role synchronization
• multiple providers
• access policies
• audit logging
• tenant support

Moving the SAML logic into a dedicated service keeps the architecture maintainable.

Defining the Routes

Next, create the authentication web routes:

Route::prefix('auth/saml2')
    ->name('auth.saml2.')
    ->controller(\App\Http\Controllers\Auth\SAML2Controller::class)
    ->group(function () {
        Route::get('metadata', 'metadata')->name('metadata');
        Route::get('redirect', 'redirect')->name('login');
        Route::post('callback', 'callback')->name('callback');
    });

This gives us:

• /auth/saml2/metadata : Service Provider metadata
• /auth/saml2/redirect : Redirect to Identity Provider
• /auth/saml2/callback : Handle SAML response

Building the SAML Service

Now let’s implement the service.

<?php

namespace App\Services;

use App\Models\User;
use Filament\Facades\Filament;
use Illuminate\Http\Response;
use Illuminate\Support\Facades\Auth;
use Laravel\Socialite\Facades\Socialite;
use SocialiteProviders\Saml2\Provider;
use Symfony\Component\HttpFoundation\RedirectResponse;

class SAML2Service
{
    public function redirect(): RedirectResponse
    {
        return Socialite::driver('saml2')->redirect();
    }

    public function callback(): ?User
    {
        /** @var Provider $saml2Provider */
        $saml2Provider = Socialite::driver('saml2');

        /** @var \SocialiteProviders\Saml2\User $socialiteUser */
        $socialiteUser = $saml2Provider->stateless()->user();

        $user = User::query()->updateOrCreate(
            ['email' => strtolower($socialiteUser->getEmail())],
            ['name' => $socialiteUser->getName()]
        );

        if ($user->canAccessPanel(Filament::getCurrentOrDefaultPanel())) {
            Auth::login($user);

            return $user;
        }

        return null;
    }

    public function metadata(): Response
    {
        /** @var Provider $saml2Provider */
        $saml2Provider = Socialite::driver('saml2');

        return $saml2Provider->getServiceProviderMetadata();
    }
}

Understanding the Authentication Flow

Redirecting the User

return Socialite::driver('saml2')->redirect();

This sends the user to the Identity Provider login page.

Depending on the environment, users may already be authenticated through their corporate session.

Retrieving the Authenticated User

$socialiteUser = $saml2Provider->stateless()->user();

The provider validates the SAML response and extracts the user information.

At this stage, you usually receive:

• email
• first name
• last name
• groups
• claims

The exact payload depends on your Identity Provider configuration.

Creating or Updating the User

User::query()->updateOrCreate(...)

This approach allows users to authenticate without pre-creating accounts manually.

It also keeps user information synchronized automatically.

Restricting Filament Access

$user->canAccessPanel(...)

This is an important step.

Authenticating a user does not necessarily mean they should access your Filament panel.

By checking panel access explicitly, you keep your authorization layer consistent with the rest of your application.

Generating Service Provider Metadata

One of the most useful features of the provider is automatic metadata generation.

return $saml2Provider->getServiceProviderMetadata();

This endpoint can be shared directly with your Identity Provider administrator.

It avoids:

• manually crafting XML files
• configuration mistakes
• certificate inconsistencies

In many enterprise environments, this alone saves a significant amount of setup time.

Improving the Login Experience in Filament

You can now add a custom login button inside your Filament login page.

For example with a render hook:

FilamentView::registerRenderHook(
    PanelsRenderHook::AUTH_LOGIN_FORM_BEFORE,
    fn (): View => view('filament.components.saml-login-button')
);

<x-filament::button
    href="{{ route('auth.saml2.login') }}"
    tag="a"
    color="primary"
    class="w-full"
    icon="heroicon-o-arrow-right-circle"
    aria-label="Connect with your SSO account"
>
    {{ __('Connect with your SSO account') }}
</x-filament::button>

This provides a much cleaner enterprise login experience.

Testing

For local development and testing, I personally use MockSAML:

This is also why the default metadata configuration points to port 4000:

'metadata' => env(
    'SAML2_METADATA_URL',
    'http://localhost:4000/api/saml/metadata'
),

Using a lightweight mock Identity Provider makes it much easier to test:

• SAML authentication flows
• user provisioning

Without requiring access to a real enterprise Active Directory during development.

What About Active Directory Groups?

At this point, authentication works.

However, most enterprise applications also need:

• role synchronization with Active Directory group mapping
• dynamic authorization

This is where things become significantly more interesting.

In the premium article, we’ll implement:

• automatic role synchronization
• group parsing from SAML claims
• Active Directory CN extraction
• role mapping strategies
• production-ready access control

SAML authentication is often perceived as complex, but Laravel Socialite combined with the SAML2 provider makes the integration surprisingly clean.

By isolating the authentication flow into a dedicated service and integrating directly with Filament, you can build enterprise-ready authentication while keeping your application maintainable.

The next step is implementing proper authorization and Active Directory role synchronization.