README

Complete SAML2 SSO authentication for Filament panels — optimized for Okta, compatible with any SAML2 identity provider.

Panel plugin that adds SAML2 single sign-on to your Filament admin panel. Configure IdP credentials, certificates, user mapping, and a login button — all from the Filament UI. Database-driven configuration (no SAML secrets in .env).

Built following the official Filament plugin guidelines: PackageServiceProvider, Filament\Contracts\Plugin, and Schema-based panel pages.

Features

Requirements

Installation

1. Install via Composer

# Filament 5.x
composer require johnriveragonzalez/saml2-okta:^2.0

# Filament 4.x
composer require johnriveragonzalez/saml2-okta:^2.0 --prefer-source
# Require branch 4.x in your composer.json if needed

2. Publish migrations and migrate

php artisan vendor:publish --tag="saml2-okta-migrations"
php artisan migrate

3. Register the plugin

In app/Providers/Filament/AdminPanelProvider.php:

use JohnRiveraGonzalez\Saml2Okta\Saml2OktaPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugins([
            Saml2OktaPlugin::make(),
        ]);
}

4. Run the installer

php artisan saml2-okta:install

This command extends your User model, updates UserResource, and completes the initial setup.

5. Optional publishes

php artisan vendor:publish --tag="saml2-okta-translations"
php artisan vendor:publish --tag="saml2-okta-config"

Configuration

Open SAML2 → Configuración SAML2 in your Filament panel.

Main settings

Identity provider (Okta / IdP)

Service provider (your app)

User settings

• Auto-create users on first login
• Auto-update existing users
• Default role for new SAML users
• Mark users as external

Login button

• Toggle SAML2 login on/off
• Custom button label and icon (Okta, Microsoft, Google, Auth0, or Heroicons)

Debug & field mapper

• Enable debug logging to inspect SAML attributes
• Map IdP fields to User columns with live sample data

Production checklist

1. Use HTTPS — SAML2 requires TLS in production.
2. Set APP_URL to your real domain.
3. Register callback URL in your IdP: https://your-domain.com/saml2/callback
4. Upload SP metadata or certificate to your IdP.
5. Disable debug mode after testing.
6. Run php artisan optimize after deployment.

Artisan commands

php artisan saml2-okta:install
php artisan saml2-okta:extend-user-model
php artisan saml2-okta:extend-user-resource
php artisan saml2-okta:unregister-middleware   # legacy upgrades only

Package structure

src/
├── Commands/
├── Controllers/
├── Models/
├── Pages/
├── Services/
├── Saml2OktaPlugin.php
└── Saml2OktaServiceProvider.php
database/migrations/
resources/views/
routes/web.php
lang/en|es/

Compatible identity providers

With bundled icons: Okta, Microsoft / Azure AD, Google Workspace, Auth0

Also compatible: OneLogin, Ping Identity, Shibboleth, ADFS, and any SAML2-compliant IdP.

Contributing

Issues and pull requests are welcome at github.com/Johnrivera7/filamentSaml2Okta.

License

MIT © John Rivera Gonzalez

Español

Plugin completo de autenticación SAML2 para paneles Filament. Instalación, configuración de Okta/IdP, certificados, mapeo de campos y botón de login desde la interfaz de administración. Compatible con Filament 4.x y 5.x. Ver secciones anteriores para instalación detallada.