Download the PHP package nbgrp/onelogin-saml-bundle without Composer

OneloginSamlBundle

Overview

OneLogin SAML Symfony Bundle.

This bundle depends on Symfony 6 and newer.
For older Symfony versions you can use hslavich/oneloginsaml-bundle which this bundle based on.

Compatibility

Installation

If you use Symfony Flex it enables the bundle automatically. Otherwise, to enable the bundle add the following code in config/bundles.php:

Configuration

To configure the bundle you need to add configuration in config/packages/nbgrp_onelogin_saml.yaml. You can use any configuration format (yaml, xml, or php), but for convenience in this document will be used yaml.

Check https://github.com/onelogin/php-saml#settings for more info about OneLogin PHP SAML settings.

You can use <request_scheme_and_host> placeholder in the following configuration values which will be replaced by the appropriate values from the Request object:

• onelogin_settings.sp.entityId
• onelogin_settings.sp.assertionConsumerService.url
• onelogin_settings.sp.singleLogoutService.url
• onelogin_settings.baseurl

Pay attention to trusted proxies settings if you're running your application behind a load balancer or a reverse proxy.

There are few extra parameters for idp and sp sections. You can read more about them from OneLogin PHP SAML docs.

Instead of specify IdP and SP x509 certificates and private keys, you can store them in OneLogin PHP SAML certs directory or use global constant ONELOGIN_CUSTOMPATH to specify custom directory (complete path will be ONELOGIN_CUSTOMPATH.'certs/').

If you do not want to set some contactPerson or organization info, do not add those parameters instead of leaving them blank.

Configure user provider and firewall in config/packages/security.yaml:

Edit your config/routes.yaml:

Multiple IdP

You can configure more than one OneLogin PHP SAML settings for multiple IdP. To do this you need to specify SAML settings for each IdP (sections with default and another keys in configuration above) and pass the name of the necessary IdP by a query string parameter idp or a request attribute with the same name. You can use another name with help of idp_parameter_name bundle parameter.

To use appropriate SAML settings, all requests to bundle routes should contain correct IdP parameter.

If a request has no query parameter or attribute with IdP value, the first key in onelogin_settings section will be used as default IdP.

Using reverse proxy

When you use your application behind a reverse proxy and use X-Forwarded-* headers, you need to set parameter nbgrp_onelogin_saml.use_proxy_vars = true to allow underlying OneLogin library determine request protocol, host and port correctly.

Optional features

Inject SAML attributes into User object

To be able to inject SAML attributes into user object, you must implement SamlUserInterface.

In addition to injecting SAML attributes to user, you can get them by getAttributes method from current security token (that should be an instance of Nbgrp\OneloginSamlBundle\Security\Http\Authenticator\Token\SamlToken).

Integration with classic login form

You can integrate SAML authentication with traditional login form by editing your security.yaml:

Then you can add a link to route saml_login in your login page in order to start SAML sign-on.

If you use multiple IdP, you should specify it by path argument:

Just-in-time user provisioning

In order for a user to be provisioned, you must use a user provider that throws UserNotFoundException (e.g. EntityUserProvider as used in the example above). The SamlUserProvider does not throw this exception which will cause an empty user to be returned (if your user class not implements Nbgrp\OneloginSamlBundle\Security\User\SamlUserInterface).

It is possible to have a new user provisioned based on the received SAML attributes when the user provider cannot find a user.

Create the user factory service by editing services.yaml:

Mapping items with '$' at the beginning of values references to SAML attribute value.
Values with '[]' at the end will be presented as arrays (even if they originally are scalars).

Then add the created service id as the user_factory parameter into your firewall settings in security.yaml:

Also, you can create your own User Factory that implements Nbgrp\OneloginSamlBundle\Security\User\SamlUserFactoryInterface.

And add it into services.yaml:

Persist user on creation and SAML attributes injection

Symfony EventDispatcher component and Doctrine ORM are required.

If you want to persist user object after success authentication, you need to add persist_user in you firewall settings in security.yaml:

To use non-default entity manager, specify its name in the nbgrp_onelogin_saml.entity_manager_name bundle configuration parameter.

User persistence is performing by the event listeners Nbgrp\OneloginSamlBundle\EventListener\User\UserCreatedListener and Nbgrp\OneloginSamlBundle\EventListener\User\UserModifiedListener that can be decorated if you need to override the default behavior.

Also, you can make your own listeners for Nbgrp\OneloginSamlBundle\Event\UserCreatedEvent and Nbgrp\OneloginSamlBundle\Event\UserModifiedEvent events:

Important: you must specify the dispatcher option corresponding the firewall which will trigger the event (main in the example above). Read more about Security Events.