From bad8468c8c08a8dff2bafc01feaa1011146f67fb Mon Sep 17 00:00:00 2001 From: Marek Pietrzak Date: Thu, 12 Nov 2015 16:31:18 +0000 Subject: [PATCH 1/6] Add "How to Use Multiple Guard Authenticators" cookbook documentation --- cookbook/map.rst.inc | 1 + cookbook/security/index.rst | 1 + .../multiple_guard_authenticators.rst | 167 ++++++++++++++++++ 3 files changed, 169 insertions(+) create mode 100644 cookbook/security/multiple_guard_authenticators.rst diff --git a/cookbook/map.rst.inc b/cookbook/map.rst.inc index d57650320c7..7f96d19c747 100644 --- a/cookbook/map.rst.inc +++ b/cookbook/map.rst.inc @@ -176,6 +176,7 @@ * :doc:`/cookbook/security/csrf_in_login_form` * :doc:`/cookbook/security/named_encoders` * :doc:`/cookbook/security/multiple_user_providers` + * :doc:`/cookbook/security/multiple_guard_authenticators` * :doc:`/cookbook/security/firewall_restriction` * :doc:`/cookbook/security/host_restriction` * :doc:`/cookbook/security/user_checkers` diff --git a/cookbook/security/index.rst b/cookbook/security/index.rst index ed13a2116f9..61efff1aa23 100644 --- a/cookbook/security/index.rst +++ b/cookbook/security/index.rst @@ -22,6 +22,7 @@ Authentication (Identifying/Logging in the User) csrf_in_login_form named_encoders multiple_user_providers + multiple_guard_authenticators firewall_restriction host_restriction user_checkers diff --git a/cookbook/security/multiple_guard_authenticators.rst b/cookbook/security/multiple_guard_authenticators.rst new file mode 100644 index 00000000000..6846f05f8d1 --- /dev/null +++ b/cookbook/security/multiple_guard_authenticators.rst @@ -0,0 +1,167 @@ +.. index:: + +How to Use Multiple Guard Authenticators +======================================== + +Guard authentication component allows you to easily use many different authenticators at a time. + +An entry point is a service id (of one of your authenticators) whose start() +method should be called when an anonymous user hits a page that requires authentication. + +Multiple authenticators with shared entry point +----------------------------------------------- +Let's have an example of two authenticators: one based on login form, another one on facebook login. +Both authenticators entry points redirect user to the same login page. +However, in your configuration you have to explicitly say which entry point you want to use. + +This is how your security configuration can look in action: + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/security.yml + security: + # ... + firewalls: + default: + anonymous: ~ + guard: + authenticators: + - app.form_login_authenticator + - app.facebook_connect_authenticator + entry_point: app.form_login_authenticator + + .. code-block:: xml + + + + + + + + + + + app.form_login_authenticator + app.facebook_connect_authenticator + + + + + + .. code-block:: php + + // app/config/security.php + $container->loadFromExtension('security', array( + // ... + 'firewalls' => array( + 'default' => array( + 'anonymous' => null, + 'guard' => array( + 'entry_point' => 'app.form_login_authenticator', + 'authenticators' => array( + 'app.form_login_authenticator', + 'app.facebook_connect_authenticator' + ), + ), + ), + ), + )); + +There is one limitation with this approach - you have to use exactly one entry point. + +Multiple authenticators with separate entry points +-------------------------------------------------- +Let's now have an example of two different authenticators: one based on login form, another one on an API token. +When user hits secured area he should be redirected to the login page. +Also when user hits an API endpoint, he should get a relevant API response. + +Solution for this use case is to provide guard authenticators in two separate firewalls. + +This is an example of your configuration: + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/security.yml + security: + # ... + firewalls: + api: + pattern: ^/api/ + guard: + authenticators: + - app.api_token_authenticator + default: + anonymous: ~ + guard: + authenticators: + - app.form_login_authenticator + access_control: + - { path: ^/login, roles: IS_AUTHENTICATED_ANONYMOUSLY } + - { path: ^/api, roles: ROLE_API_USER } + - { path: ^/, roles: ROLE_ADMIN } + + .. code-block:: xml + + + + + + + + + + app.api_token_authenticator + + + + + + app.form_login_authenticator + + + + + + + + + .. code-block:: php + + // app/config/security.php + $container->loadFromExtension('security', array( + // ... + 'firewalls' => array( + 'api' => array( + 'guard' => array( + 'authenticators' => array( + 'app.api_token_authenticator', + ), + ), + ), + 'default' => array( + 'anonymous' => null, + 'guard' => array( + 'authenticators' => array( + 'app.form_login_authenticator', + ), + ), + ), + ), + 'access_control' => array( + array('path' => '^/login', 'role' => 'IS_AUTHENTICATED_ANONYMOUSLY'), + array('path' => '^/api', 'role' => 'ROLE_API_USER'), + array('path' => '^/', 'role' => 'ROLE_ADMIN'), + ), + )); From 95135ae9e121857ca0e653552a859ad609329d36 Mon Sep 17 00:00:00 2001 From: Marek Pietrzak Date: Thu, 12 Nov 2015 16:49:13 +0000 Subject: [PATCH 2/6] Remove obsolete lines --- cookbook/security/multiple_guard_authenticators.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/cookbook/security/multiple_guard_authenticators.rst b/cookbook/security/multiple_guard_authenticators.rst index 6846f05f8d1..bdc8908bb39 100644 --- a/cookbook/security/multiple_guard_authenticators.rst +++ b/cookbook/security/multiple_guard_authenticators.rst @@ -1,5 +1,3 @@ -.. index:: - How to Use Multiple Guard Authenticators ======================================== From eeeb57b83d3b09ba1a6eee094bb23ff272138ed6 Mon Sep 17 00:00:00 2001 From: Marek Pietrzak Date: Thu, 12 Nov 2015 21:04:30 +0000 Subject: [PATCH 3/6] Add missing pattern to php configuration --- cookbook/security/multiple_guard_authenticators.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/cookbook/security/multiple_guard_authenticators.rst b/cookbook/security/multiple_guard_authenticators.rst index bdc8908bb39..4a0d5ba43d1 100644 --- a/cookbook/security/multiple_guard_authenticators.rst +++ b/cookbook/security/multiple_guard_authenticators.rst @@ -142,6 +142,7 @@ This is an example of your configuration: // ... 'firewalls' => array( 'api' => array( + 'pattern' => '^/api', 'guard' => array( 'authenticators' => array( 'app.api_token_authenticator', From 37fccf8360ad3d6bc02b63835df8f0779c98c2e8 Mon Sep 17 00:00:00 2001 From: Marek Pietrzak Date: Tue, 17 Nov 2015 08:30:20 +0000 Subject: [PATCH 4/6] Add missing blank lines --- cookbook/security/multiple_guard_authenticators.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/cookbook/security/multiple_guard_authenticators.rst b/cookbook/security/multiple_guard_authenticators.rst index 4a0d5ba43d1..99a88bc4454 100644 --- a/cookbook/security/multiple_guard_authenticators.rst +++ b/cookbook/security/multiple_guard_authenticators.rst @@ -8,6 +8,7 @@ method should be called when an anonymous user hits a page that requires authent Multiple authenticators with shared entry point ----------------------------------------------- + Let's have an example of two authenticators: one based on login form, another one on facebook login. Both authenticators entry points redirect user to the same login page. However, in your configuration you have to explicitly say which entry point you want to use. @@ -75,6 +76,7 @@ There is one limitation with this approach - you have to use exactly one entry p Multiple authenticators with separate entry points -------------------------------------------------- + Let's now have an example of two different authenticators: one based on login form, another one on an API token. When user hits secured area he should be redirected to the login page. Also when user hits an API endpoint, he should get a relevant API response. From ea3c900266a367f290533a1970602bd4f954d714 Mon Sep 17 00:00:00 2001 From: Marek Pietrzak Date: Wed, 10 Feb 2016 10:56:22 +0000 Subject: [PATCH 5/6] Apply changes for comments raised during review --- .../multiple_guard_authenticators.rst | 39 ++++++++++--------- 1 file changed, 20 insertions(+), 19 deletions(-) diff --git a/cookbook/security/multiple_guard_authenticators.rst b/cookbook/security/multiple_guard_authenticators.rst index 99a88bc4454..95b291851cb 100644 --- a/cookbook/security/multiple_guard_authenticators.rst +++ b/cookbook/security/multiple_guard_authenticators.rst @@ -1,17 +1,20 @@ How to Use Multiple Guard Authenticators ======================================== -Guard authentication component allows you to easily use many different authenticators at a time. +The Guard authentication component allows you to easily use many different +authenticators at a time. -An entry point is a service id (of one of your authenticators) whose start() -method should be called when an anonymous user hits a page that requires authentication. +An entry point is a service id (of one of your authenticators) whose +``start()`` method is called to start the authentication process. -Multiple authenticators with shared entry point +Multiple Authenticators with Shared Entry Point ----------------------------------------------- -Let's have an example of two authenticators: one based on login form, another one on facebook login. -Both authenticators entry points redirect user to the same login page. -However, in your configuration you have to explicitly say which entry point you want to use. +Sometimes you want to offer your users different authentication mechanisms like +a form login and a Facebook login while both entry points redirect the user to +the same login page. +However, in your configuration you have to explicitly say which entry point +you want to use. This is how your security configuration can look in action: @@ -45,7 +48,7 @@ This is how your security configuration can look in action: - + app.form_login_authenticator app.facebook_connect_authenticator @@ -74,16 +77,14 @@ This is how your security configuration can look in action: There is one limitation with this approach - you have to use exactly one entry point. -Multiple authenticators with separate entry points +Multiple Authenticators with Separate Entry Points -------------------------------------------------- -Let's now have an example of two different authenticators: one based on login form, another one on an API token. -When user hits secured area he should be redirected to the login page. -Also when user hits an API endpoint, he should get a relevant API response. - -Solution for this use case is to provide guard authenticators in two separate firewalls. - -This is an example of your configuration: +However, there are use cases where you have authenticators that protect different +parts of your application. For example, you have a login form that protects +the secured area of your application front-end and API end points that are +protected with API tokens. As you can only configure one entry point per firewall, +the solution is to split the configuration into two separate firewalls: .. configuration-block:: @@ -106,7 +107,7 @@ This is an example of your configuration: access_control: - { path: ^/login, roles: IS_AUTHENTICATED_ANONYMOUSLY } - { path: ^/api, roles: ROLE_API_USER } - - { path: ^/, roles: ROLE_ADMIN } + - { path: ^/, roles: ROLE_USER } .. code-block:: xml @@ -133,7 +134,7 @@ This is an example of your configuration: - + @@ -163,6 +164,6 @@ This is an example of your configuration: 'access_control' => array( array('path' => '^/login', 'role' => 'IS_AUTHENTICATED_ANONYMOUSLY'), array('path' => '^/api', 'role' => 'ROLE_API_USER'), - array('path' => '^/', 'role' => 'ROLE_ADMIN'), + array('path' => '^/', 'role' => 'ROLE_USER'), ), )); From a2ca764f604d3a16deba2a355379d0d28fdb9224 Mon Sep 17 00:00:00 2001 From: Marek Pietrzak Date: Wed, 10 Feb 2016 12:42:06 +0000 Subject: [PATCH 6/6] Add versionadded --- cookbook/security/multiple_guard_authenticators.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/cookbook/security/multiple_guard_authenticators.rst b/cookbook/security/multiple_guard_authenticators.rst index 95b291851cb..acb1f774422 100644 --- a/cookbook/security/multiple_guard_authenticators.rst +++ b/cookbook/security/multiple_guard_authenticators.rst @@ -1,6 +1,9 @@ How to Use Multiple Guard Authenticators ======================================== +.. versionadded:: 2.8 + The ``Guard`` component was introduced in Symfony 2.8. + The Guard authentication component allows you to easily use many different authenticators at a time.