Beartropy SAML2
Prerequisites
- PHP 8.1 or higher
- Laravel 10.x, 11.x, or 12.x
- PHP openssl extension
- PHP dom extension
1. Install via Composer
Install the package using Composer:
1composer require beartropy/saml22. Publish Configuration (Required)
Publish the configuration file to customize package options. This creates config/beartropy-saml2.php.
1php artisan vendor:publish --tag=beartropy-saml2-config3. Run Migrations (Optional)
Run migrations to create the necessary tables for storing IDPs and settings. This is optional if you are using an all env configuration.
1php artisan migrateCreated Tables
| Table | Description |
|---|---|
| beartropy_saml2_idps | Stores Identity Provider configurations |
| beartropy_saml2_settings | Stores general package settings |
4. Configure Environment Variables
Add these variables to your .env file:
1# Your app's entity identifier (required)2SAML2_SP_ENTITY_ID=https://your-app.com3 4# Optional but recommended5SAML2_LOGIN_REDIRECT=/dashboard6SAML2_LOGOUT_REDIRECT=/5. Generate SP Certificates (Recommended)
For production environments, generate certificates to sign SAML requests. This creates environment variables for the certificate and private key.
1php artisan saml2:generate-cert6. Publish Login Listener (Recommended)
Publish a customizable listener to handle SAML login events. This creates app/Listeners/HandleSaml2Login.php.
1php artisan saml2:publish-listenerLogin Listener Example
The published listener looks like this. Customize it to match your authentication logic:
1namespace App\Listeners; 2 3use Beartropy\Saml2\Events\Saml2LoginEvent; 4use Illuminate\Support\Facades\Auth; 5use App\Models\User; 6 7class HandleSaml2Login 8{ 9 public function handle(Saml2LoginEvent $event): void10 {11 $email = $event->getEmail();12 $name = $event->getName();13 14 // Find or create user15 $user = User::firstOrCreate(16 ['email' => $email],17 ['name' => $name ?? $email]18 );19 20 // Authenticate user21 Auth::login($user, remember: true);22 }23}7. Access the Setup Wizard
/saml2/setup to run the setup wizard.The wizard is available before the first IDP is configured. It guides you through SP metadata sharing and IDP configuration.
Optional: Publish Views and Translations
Publish Views
To customize the setup wizard and admin panel appearance:
1php artisan vendor:publish --tag=beartropy-saml2-viewsPublish Translations
To customize interface text (English and Spanish included):
1php artisan vendor:publish --tag=beartropy-saml2-langAvailable Artisan Commands
| Command | Description |
|---|---|
| saml2:create-idp {key} | Create a new IDP |
| saml2:list-idps | List all configured IDPs |
| saml2:test-idp {key} | Test an IDP's configuration |
| saml2:delete-idp {key} | Delete an IDP |
| saml2:generate-cert | Generate SP certificates |
| saml2:refresh-metadata | Refresh IDP metadata from URLs |
| saml2:publish-listener | Publish login listener |
| saml2:reset-setup | Reset to initial setup state |
Verify Routes
Verify the SAML2 routes are registered:
1php artisan route:list --name=saml2