Skip to content

Cookbook for session concurrency control #4440

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 4 commits into from
Closed

Cookbook for session concurrency control #4440

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
8e66f3f
Cookbook for session concurrency control
ajgarlag Nov 10, 2014
5f3a2de
Fix title underline
ajgarlag Nov 10, 2014
15d7f60
Changes suggested by @javiereguiluz.
ajgarlag Nov 11, 2014
108c476
Adds references to the new cookbook article in cookbok map and cookbo…
ajgarlag Nov 11, 2014
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions book/security.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2330,6 +2330,7 @@ Learn more from the Cookbook
* :doc:`Access Control Lists (ACLs) </cookbook/security/acl>`
* :doc:`/cookbook/security/remember_me`
* :doc:`How to Restrict Firewalls to a Specific Request </cookbook/security/firewall_restriction>`
* :doc:`How to Control Session Concurrency </cookbook/security/session_concurrency_control>`

.. _`FOSUserBundle`: https://github.com/FriendsOfSymfony/FOSUserBundle
.. _`implement the \Serializable interface`: http://php.net/manual/en/class.serializable.php
Expand Down
1 change: 1 addition & 0 deletions cookbook/map.rst.inc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -157,6 +157,7 @@
* :doc:`/cookbook/security/target_path`
* :doc:`/cookbook/security/csrf_in_login_form`
* :doc:`/cookbook/security/named_encoders`
* :doc:`/cookbook/security/session_concurrency_control`

* **Serializer**

Expand Down
1 change: 1 addition & 0 deletions cookbook/security/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,3 +25,4 @@ Security
target_path
csrf_in_login_form
named_encoders
session_concurrency_control
195 changes: 195 additions & 0 deletions cookbook/security/session_concurrency_control.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,195 @@
.. index::
single: Security; How to control Session Concurrency

How to Control Session Concurrency
==================================

Sometimes, it's useful to restrict the number of concurrent sessions that a given
user can open using different browsers and devices. When the maximum number of
concurrent sessions is achieved, Symfony allows you to disable new sessions or to
expire the old ones. To do so, set the ``max_sessions`` limit using the ``session_concurrency``
option of your firewall:

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What about rewording the introductory paragraph as follows?

Sometimes, it's useful to restrict the number of concurrent sessions that a given
user can open using different browsers and devices. When the maximum number of
concurrent sessions is achieved, Symfony allows you to disable new sessions or to
expire the old ones. To do so, set the ``max_sessions`` limit using the ``session_concurrency``
option of your firewall:

.. configuration-block::

.. code-block:: yaml

# app/config/security.yml
security:
firewalls:
main:
# ...
session_concurrency:
max_sessions: 2

.. code-block:: xml

<!-- app/config/security.xml -->
<?xml version="1.0" encoding="UTF-8"?>
<srv:container xmlns="http://symfony.com/schema/dic/security"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:srv="http://symfony.com/schema/dic/services"
xsi:schemaLocation="http://symfony.com/schema/dic/services
http://symfony.com/schema/dic/services/services-1.0.xsd">
<config>
<firewall name="main">
<!-- ... -->
<session-concurrency
max-sessions="2"
/>
</firewall>
</config>
</srv:container>

.. code-block:: php

// app/config/security.php
$container->loadFromExtension('security', array(
'firewalls' => array(
'main'=> array(
// ...
'session_concurrency' => array(
'max_sessions' => 2,
),
),
),
));

With this configuration, any user will be allowed to open up to 2 sessions, but
will fail to open the third one.

Maybe, you would like to close the older active session instead of disabling the
ability to open a new one. This can be achived setting the ``error_if_maximum_exceeded``
option to false in the firewall configuration:

.. configuration-block::

.. code-block:: yaml

# app/config/security.yml
security:
firewalls:
main:
# ...
session_concurrency:
max_sessions: 2
error_if_maximum_exceeded: false

.. code-block:: xml

<!-- app/config/security.xml -->
<?xml version="1.0" encoding="UTF-8"?>
<srv:container xmlns="http://symfony.com/schema/dic/security"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:srv="http://symfony.com/schema/dic/services"
xsi:schemaLocation="http://symfony.com/schema/dic/services
http://symfony.com/schema/dic/services/services-1.0.xsd">
<config>
<firewall name="main">
<!-- ... -->
<session-concurrency
max-sessions="2"
error-if-maximum-exceeded="false"
/>
</firewall>
</config>
</srv:container>

.. code-block:: php

// app/config/security.php
$container->loadFromExtension('security', array(
'firewalls' => array(
'main'=> array(
// ...
'session_concurrency' => array(
'max_sessions' => 2,
'error_if_maximum_exceeded' => false,
),
),
),
));

With these settings, when the user opens a new session, the older ones will be
marked as expired leaving only 2 active sessions. If the user makes a new
request with the expired session, will be logged out and redirected to ``/`` by
default. You can control where the user will be redirected when an expired
session is detected setting the ``expiration_url`` option in the firewall
configuration:

.. configuration-block::

.. code-block:: yaml

# app/config/security.yml
security:
firewalls:
main:
# ...
session_concurrency:
max_sessions: 2
error_if_maximum_exceeded: false
expiration_url: /session-expired

.. code-block:: xml

<!-- app/config/security.xml -->
<?xml version="1.0" encoding="UTF-8"?>
<srv:container xmlns="http://symfony.com/schema/dic/security"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:srv="http://symfony.com/schema/dic/services"
xsi:schemaLocation="http://symfony.com/schema/dic/services
http://symfony.com/schema/dic/services/services-1.0.xsd">
<config>
<firewall name="main">
<!-- ... -->
<session-concurrency
max-sessions="2"
error-if-maximum-exceeded="false"
expiration-url="/session-expired"
/>
</firewall>
</config>
</srv:container>

.. code-block:: php

// app/config/security.php
$container->loadFromExtension('security', array(
'firewalls' => array(
'main'=> array(
// ...
'session_concurrency' => array(
'max_sessions' => 2,
'error_if_maximum_exceeded' => false,
'expiration_url' => '/session-expired',
),
),
),
));

If the ``max_sessions`` option is left to its default value (``0``) the maximum
number of sessions will not be checked, but it will allow you to manually expire
all sessions for a concrete user through the session registry:

.. code-block:: php

// src/Acme/DemoBundle/Controller/DefaultController.php
namespace Acme\DemoBundle\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\Controller;
use Symfony\Component\Security\Core\User\UserInterface;

class DefaultController extends Controller
{
public function expireUserSessionsAction(UserInterface $user)
{
/** @var $sessionRegistry \Symfony\Component\Security\Http\Session\SessionRegistry */
$sessionRegistry = $this->get('security.authentication.session_registry');

$sessions = $sessionRegistry->getAllSessions($user->getUsername());
foreach ($sessions as $session) {
$sessionRegistry->expireNow($session->getSessionId());
}
}
}