Service Provider (SP) Configuration

The Service Provider is your Laravel application. This section defines how your application identifies itself to Identity Providers.

 1'sp' => [
 2    // Unique identifier for your SP (usually your app URL)
 3    'entityId' => env('SAML2_SP_ENTITY_ID'),
 4 
 5    // SP x509 certificate and private key
 6    'x509cert' => env('SAML2_SP_CERT'),
 7    'privateKey' => env('SAML2_SP_PRIVATE_KEY'),
 8 
 9    // Custom URLs (null = auto-generate based on routes)
10    'acs_url' => env('SAML2_SP_ACS_URL'),
11    'sls_url' => env('SAML2_SP_SLS_URL'),
12    'metadata_url' => env('SAML2_SP_METADATA_URL'),
13 
14    // NameID format
15    'nameIdFormat' => env('SAML2_SP_NAMEID_FORMAT', 'urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress'),
16],

Option	Environment Variable	Description
entityId	SAML2_SP_ENTITY_ID	Unique identifier for your application
x509cert	SAML2_SP_CERT	SP public certificate for signing requests
privateKey	SAML2_SP_PRIVATE_KEY	Private key for the certificate
acs_url	SAML2_SP_ACS_URL	Assertion Consumer Service URL (auto-generated if null)
nameIdFormat	SAML2_SP_NAMEID_FORMAT	NameID format expected in SAML responses

IDP Source

Defines where Identity Provider configurations are loaded from.

1'idp_source' => env('SAML2_IDP_SOURCE', 'database'),

Value	Description	Use Case
env	Only from environment variables (single IDP)	Simple deployments with a single IDP
database	Only from database (multiple IDPs)	Most production cases
both	Checks env first, then database	Local development with test IDP

See the Environment IDP Configuration guide for details on configuring IDPs via environment variables.

Route Configuration

1'route_prefix' => env('SAML2_ROUTE_PREFIX', 'saml2'),
2'route_middleware' => ['web'],

Route	Method	Description
/saml2/setup	GET	Initial configuration wizard
/saml2/login/{idp?}	GET	Initiate SSO login
/saml2/acs	POST	Generic ACS (auto-detects IDP)
/saml2/acs/{idp}	POST	ACS with explicit IDP key
/saml2/metadata	GET	SP Metadata XML
/saml2/logout/{idp?}	GET	Initiate logout

Admin Panel

1'admin_enabled' => env('SAML2_ADMIN_ENABLED', true),
2'admin_route_prefix' => env('SAML2_ADMIN_PREFIX', 'saml2/admin'),
3'admin_middleware' => ['web', 'auth'],
4'layout' => env('SAML2_ADMIN_LAYOUT', 'beartropy-saml2::admin.partials.layout'),

Protecting the Admin Panel

To restrict access to administrators only:

1// config/beartropy-saml2.php
2'admin_middleware' => ['web', 'auth', 'can:manage-saml'],

Define a Gate

Define the Gate in your AuthServiceProvider:

1// app/Providers/AuthServiceProvider.php
2use Illuminate\Support\Facades\Gate;
3 
4public function boot(): void
5{
6    Gate::define('manage-saml', function ($user) {
7        return $user->hasRole('admin'); // or your permission logic
8    });
9}

Redirect URLs

1'login_redirect' => env('SAML2_LOGIN_REDIRECT', '/'),
2'logout_redirect' => env('SAML2_LOGOUT_REDIRECT', '/'),
3'error_redirect' => env('SAML2_ERROR_REDIRECT', '/login'),

Attribute Mapping

Defines how SAML attributes map to user fields in your application. This is the global mapping; each IDP can have its own custom mapping.

1'attribute_mapping' => [
2    'email' => 'email',
3    'name' => 'displayname',
4    'firstname' => 'firstname',
5    'lastname' => 'lastname',
6    'username' => 'username',
7    'roles' => 'roles',
8    'groups' => 'groups',
9],

Azure AD Mapping Example

Example mapping for Azure Active Directory:

1'attribute_mapping' => [
2    'email' => 'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress',
3    'name' => 'http://schemas.microsoft.com/identity/claims/displayname',
4    'firstname' => 'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname',
5    'lastname' => 'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname',
6    'roles' => 'http://schemas.microsoft.com/ws/2008/06/identity/claims/groups',
7],

Security Settings

Advanced settings for secure SAML communication.

 1'security' => [
 2    'nameIdEncrypted' => false,
 3    'authnRequestsSigned' => false,
 4    'logoutRequestSigned' => false,
 5    'logoutResponseSigned' => false,
 6    'signMetadata' => false,
 7    'wantMessagesSigned' => false,
 8    'wantAssertionsSigned' => false,
 9    'wantAssertionsEncrypted' => false,
10    'wantNameIdEncrypted' => false,
11    'requestedAuthnContext' => true,
12    'signatureAlgorithm' => 'http://www.w3.org/2001/04/xmldsig-more#rsa-sha256',
13    'digestAlgorithm' => 'http://www.w3.org/2001/04/xmlenc#sha256',
14],

Recommended Production Configuration

For production environments, enable signature verification:

1'security' => [
2    'authnRequestsSigned' => true,
3    'logoutRequestSigned' => true,
4    'logoutResponseSigned' => true,
5    'signMetadata' => true,
6    'wantMessagesSigned' => true,
7    'wantAssertionsSigned' => true,
8    // ... rest as default values
9],

To use signatures, you must first generate SP certificates with php artisan saml2:generate-cert

Debug Mode

1'debug' => env('SAML2_DEBUG', false),
2'strict' => env('SAML2_STRICT', true),

Warning: Never enable debug in production. It may expose sensitive information in logs.

Full .env Example

 1# Service Provider
 2SAML2_SP_ENTITY_ID=https://your-app.com
 3 
 4# IDP Source
 5SAML2_IDP_SOURCE=database
 6 
 7# Routes
 8SAML2_ROUTE_PREFIX=saml2
 9SAML2_ADMIN_PREFIX=saml2/admin
10SAML2_ADMIN_ENABLED=true
11 
12# Redirects
13SAML2_LOGIN_REDIRECT=/dashboard
14SAML2_LOGOUT_REDIRECT=/
15SAML2_ERROR_REDIRECT=/login
16 
17# Security
18SAML2_DEBUG=false
19SAML2_STRICT=true
20 
21# Metadata Import
22SAML2_ALLOW_METADATA_IMPORT=true

Beartropy SAML2

Service Provider (SP) Configuration

IDP Source

Route Configuration

Admin Panel

Protecting the Admin Panel

Define a Gate

Redirect URLs

Attribute Mapping

Azure AD Mapping Example

Security Settings

Recommended Production Configuration

Debug Mode

Full .env Example

Available Packages

SAML2

UI Kit

Tables

Alert System

Starter Kit

Settings

Charts

Permissions