From 73e54d9e391b4f5b13a01d2d991e5578fbdccfbd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Antonio=20J=2E=20Garc=C3=ADa=20Lagar?= Date: Sat, 15 Nov 2014 08:03:05 +0100 Subject: [PATCH 1/4] Session expiration firewall documentation --- book/security.rst | 1 + cookbook/map.rst.inc | 2 + cookbook/security/index.rst | 1 + cookbook/security/session_expiration.rst | 149 +++++++++++++++++++++++ 4 files changed, 153 insertions(+) create mode 100644 cookbook/security/session_expiration.rst diff --git a/book/security.rst b/book/security.rst index c26108826d2..ef2a0775094 100644 --- a/book/security.rst +++ b/book/security.rst @@ -2326,6 +2326,7 @@ Learn more from the Cookbook * :doc:`Access Control Lists (ACLs) ` * :doc:`/cookbook/security/remember_me` * :doc:`How to Restrict Firewalls to a Specific Request ` +* :doc:`/cookbook/security/session_expiration` .. _`FrameworkExtraBundle documentation`: http://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/security.html .. _`FOSUserBundle`: https://github.com/FriendsOfSymfony/FOSUserBundle diff --git a/cookbook/map.rst.inc b/cookbook/map.rst.inc index 24a0cd78371..4820f40a89d 100644 --- a/cookbook/map.rst.inc +++ b/cookbook/map.rst.inc @@ -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_expiration` * **Serializer** @@ -175,6 +176,7 @@ * :doc:`/cookbook/session/sessions_directory` * :doc:`/cookbook/session/php_bridge` * :doc:`/cookbook/session/limit_metadata_writes` + * (security) :doc:`/cookbook/security/session_expiration` * **symfony1** diff --git a/cookbook/security/index.rst b/cookbook/security/index.rst index 91f4d654188..d4fedfdd202 100644 --- a/cookbook/security/index.rst +++ b/cookbook/security/index.rst @@ -25,3 +25,4 @@ Security target_path csrf_in_login_form named_encoders + session_expiration diff --git a/cookbook/security/session_expiration.rst b/cookbook/security/session_expiration.rst new file mode 100644 index 00000000000..c71f64af7e1 --- /dev/null +++ b/cookbook/security/session_expiration.rst @@ -0,0 +1,149 @@ +.. index:: + single: Security; Expiration of idle sessions + +Expiration of idle sessions +=========================== + +To be able to expire idle session, you have to activate the ``session_expiration`` +firewall listener: + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/security.yml + security: + firewalls: + main: + # ... + session_expiration: ~ + + .. code-block:: xml + + + + + + + + + + + + + .. code-block:: php + + // app/config/security.php + $container->loadFromExtension('security', array( + 'firewalls' => array( + 'main'=> array( + // ... + 'session_expiration' => array() + ), + ), + )); + + +To adjust the max idle time before the session is marked as expired, you can +set the ``max_idle_time`` option value in seconds. By default the value of this +option is equal to the ``session.gc_maxlifetime`` configuration option of PHP. +The ``max_idle_time`` option value **should be lesser or equal** to the +``session.gc_maxlifetime`` value. + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/security.yml + security: + firewalls: + main: + # ... + session_expiration: + max_idle_time: 600 + + .. code-block:: xml + + + + + + + + + + + + + .. code-block:: php + + // app/config/security.php + $container->loadFromExtension('security', array( + 'firewalls' => array( + 'main'=> array( + // ... + 'session_expiration' => array( + 'max_idle_time' => 600 + ) + ), + ), + )); + +By default, when an expired session is detected, an authorization exception is +thrown. If the option ``expiration_url`` is set, the user will be redirected +to this URL and no exception will be thrown: + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/security.yml + security: + firewalls: + main: + # ... + session_expiration: + expiration_url: /session-expired + + .. code-block:: xml + + + + + + + + + + + + + .. code-block:: php + + // app/config/security.php + $container->loadFromExtension('security', array( + 'firewalls' => array( + 'main'=> array( + // ... + 'session_expiration' => array( + 'expiration_url' => /session-expired + ) + ), + ), + )); + +To detect idle sessions, this firewall checks the last used timestamp stored in +the session metadata bag. Beware that this value could be not as accurate as +expected if you :doc:`limit metadata writes `. From a201929ebed48147dd1bab34dd8303f3f19f19d5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Antonio=20J=2E=20Garc=C3=ADa=20Lagar?= Date: Wed, 3 Dec 2014 09:04:56 +0100 Subject: [PATCH 2/4] Several fixes suggested by @xabbuh --- cookbook/security/session_expiration.rst | 24 +++++++++++++++--------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/cookbook/security/session_expiration.rst b/cookbook/security/session_expiration.rst index c71f64af7e1..9d54175c875 100644 --- a/cookbook/security/session_expiration.rst +++ b/cookbook/security/session_expiration.rst @@ -1,10 +1,10 @@ .. index:: - single: Security; Expiration of idle sessions + single: Security; Expiration of Idle sessions -Expiration of idle sessions +Expiration of Idle sessions =========================== -To be able to expire idle session, you have to activate the ``session_expiration`` +To be able to expire idle sessions, you have to activate the ``session_expiration`` firewall listener: .. configuration-block:: @@ -27,12 +27,14 @@ firewall listener: 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"> + + .. code-block:: php @@ -42,7 +44,7 @@ firewall listener: 'firewalls' => array( 'main'=> array( // ... - 'session_expiration' => array() + 'session_expiration' => array(), ), ), )); @@ -51,7 +53,7 @@ firewall listener: To adjust the max idle time before the session is marked as expired, you can set the ``max_idle_time`` option value in seconds. By default the value of this option is equal to the ``session.gc_maxlifetime`` configuration option of PHP. -The ``max_idle_time`` option value **should be lesser or equal** to the +The ``max_idle_time`` option value **should be less or equal** to the ``session.gc_maxlifetime`` value. .. configuration-block:: @@ -75,12 +77,14 @@ The ``max_idle_time`` option value **should be lesser or equal** to the 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"> + + .. code-block:: php @@ -91,14 +95,14 @@ The ``max_idle_time`` option value **should be lesser or equal** to the 'main'=> array( // ... 'session_expiration' => array( - 'max_idle_time' => 600 + 'max_idle_time' => 600, ) ), ), )); By default, when an expired session is detected, an authorization exception is -thrown. If the option ``expiration_url`` is set, the user will be redirected +thrown. If the option ``expiration_url`` is set, the user will be redirected to this URL and no exception will be thrown: .. configuration-block:: @@ -122,12 +126,14 @@ to this URL and no exception will be thrown: 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"> + + .. code-block:: php @@ -138,12 +144,12 @@ to this URL and no exception will be thrown: 'main'=> array( // ... 'session_expiration' => array( - 'expiration_url' => /session-expired + 'expiration_url' => '/session-expired', ) ), ), )); -To detect idle sessions, this firewall checks the last used timestamp stored in +To detect idle sessions, the firewall checks the last used timestamp stored in the session metadata bag. Beware that this value could be not as accurate as expected if you :doc:`limit metadata writes `. From aa4cf8e06d79b32fe850599a828824f57fc52081 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Antonio=20J=2E=20Garc=C3=ADa=20Lagar?= Date: Fri, 19 Dec 2014 09:52:40 +0100 Subject: [PATCH 3/4] Several improvements suggested by @WouterJ --- cookbook/security/session_expiration.rst | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/cookbook/security/session_expiration.rst b/cookbook/security/session_expiration.rst index 9d54175c875..084faf66fd3 100644 --- a/cookbook/security/session_expiration.rst +++ b/cookbook/security/session_expiration.rst @@ -49,9 +49,8 @@ firewall listener: ), )); - To adjust the max idle time before the session is marked as expired, you can -set the ``max_idle_time`` option value in seconds. By default the value of this +set the ``max_idle_time`` option value in seconds. By default, the value of this option is equal to the ``session.gc_maxlifetime`` configuration option of PHP. The ``max_idle_time`` option value **should be less or equal** to the ``session.gc_maxlifetime`` value. @@ -96,7 +95,7 @@ The ``max_idle_time`` option value **should be less or equal** to the // ... 'session_expiration' => array( 'max_idle_time' => 600, - ) + ), ), ), )); @@ -145,7 +144,7 @@ to this URL and no exception will be thrown: // ... 'session_expiration' => array( 'expiration_url' => '/session-expired', - ) + ), ), ), )); From d7041386765be6291a75d43490db8ffd98c208ee Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Antonio=20J=2E=20Garc=C3=ADa=20Lagar?= Date: Fri, 19 Dec 2014 14:19:56 +0100 Subject: [PATCH 4/4] Uppercase Session --- cookbook/security/session_expiration.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/cookbook/security/session_expiration.rst b/cookbook/security/session_expiration.rst index 084faf66fd3..5abf6c10a7c 100644 --- a/cookbook/security/session_expiration.rst +++ b/cookbook/security/session_expiration.rst @@ -1,7 +1,7 @@ .. index:: - single: Security; Expiration of Idle sessions + single: Security; Expiration of Idle Sessions -Expiration of Idle sessions +Expiration of Idle Sessions =========================== To be able to expire idle sessions, you have to activate the ``session_expiration``