Download the PHP package maize-tech/laravel-saml2-sp without Composer

Laravel SAML2 Service Provider

This package lets you add SAML2 authentication support within your application.

It acts as a SAML2 Service Provider (SP): it exposes the SP metadata, redirects users to your Identity Provider (IdP) for authentication, consumes the IdP assertion to log the user in, and handles single logout. Under the hood it wraps onelogin/php-saml and stores one or more SAML configurations in the database.

Installation

You can install the package via composer:

You can publish the config and migration files and run the migrations with:

This is the content of the published config file:

Usage

Minimum configuration

After publishing the config file, set at least the following keys in config/saml2-sp.php (or via your environment):

• user_model: the fully qualified class name of your authenticatable user model.
• login_return_url: where users are redirected after a successful login.
• logout_return_url: where users are redirected after logout.
• domain_whitelist: the list of domains accepted as return urls. Any return_url / RelayState whose host is not whitelisted falls back to the configured return url. This prevents open-redirect attacks.

Both login_return_url and logout_return_url also accept a closure or the class name of an invokable class, so you can resolve the destination at runtime:

Creating a SAML configuration

SAML settings are stored in the database through the SamlConfig model. Each row holds the service provider (sp) and identity provider (idp) sections, merged at runtime with the default_values defined in the config file. The sp, idp, security, contactPerson and organization columns are transparently encrypted.

Routes

When routes.enabled is true (the default), the package registers the following routes under the configured prefix (saml2 by default) and middleware (web):

A typical flow looks like this:

1. Share saml2/metadata with your Identity Provider.
2. Send the user to saml2/login (optionally with a whitelisted ?return_url=). They are redirected to the IdP to authenticate.
3. The IdP posts the assertion back to saml2/acs. The package validates it, resolves the matching user and logs them in, then redirects to the RelayState (if whitelisted) or to login_return_url.
4. To log out, send the user to saml2/logout. After the IdP processes it, the saml2/sls endpoint logs the user out locally and redirects to logout_return_url.

You may disable the built-in routes (routes.enabled => false) and register your own pointing to the package controllers if you need full control.

Events

The package dispatches two events you can listen to:

• Maize\Saml2Sp\Events\SamlLoggedIn — after a user is authenticated through the ACS endpoint.
• Maize\Saml2Sp\Events\SamlLoggedOut — after a user is logged out through the SLS endpoint.

Both expose the affected user via a public $user property:

Customizing the authentication logic

The default AuthenticateUser action looks up the user by matching its email column against the SAML nameId, then logs it in through the configured guard. The default LogoutUser action logs out the currently authenticated user.

You can replace either action with your own by pointing the config to a custom class:

A custom authenticate action receives the Maize\Saml2Sp\SamlUserData instance (name id, attributes and friendly-name attributes) and must return an Illuminate\Contracts\Auth\Authenticatable:

Resolving the configuration per request (multi-tenant)

By default the DefaultSamlConfigFinder returns the first SamlConfig row. If you serve several Identity Providers (e.g. one per tenant or domain), implement your own finder and register it in the config:

Testing

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Enrico De Lazzari
• Riccardo Dalla Via
• All Contributors

License

The MIT License (MIT). Please see License File for more information.