[symfony#1604] Proofreading and tweaking the new security component docs

weaverryan · weaverryan · commit 54fa3be0e2cd · 2012-12-24T17:49:54.000-05:00
diff --git a/components/security/authentication.rst b/components/security/authentication.rst
@@ -1,5 +1,5 @@
 .. index::
-   single: Security, Authentication Manager
+   single: Security, Authentication
 
 Authentication
 ==============
@@ -9,7 +9,7 @@ firewall map is able to extract the user's credentials from the current
 :class:`Symfony\\Component\\HttpFoundation\\Request` object, it should create
 a token, containing these credentials. The next thing the listener should
 do is ask the authentication manager to validate the given token, and return
-an authenticated token when the supplied credentials were found to be valid.
+an *authenticated* token if the supplied credentials were found to be valid.
 The listener should then store the authenticated token in the security context::
 
     use Symfony\Component\Security\Http\Firewall\ListenerInterface;
@@ -63,7 +63,7 @@ The listener should then store the authenticated token in the security context::
     A token can be of any class, as long as it implements
     :class:`Symfony\\Component\\Security\\Core\\Authentication\\Token\\TokenInterface`.
 
-The authentication manager
+The Authentication Manager
 --------------------------
 
 The default authentication manager is an instance of
@@ -101,11 +101,12 @@ Each provider (since it implements
 has a method :method:`Symfony\\Component\\Security\\Core\\Authentication\\Provider\\AuthenticationProviderInterface::supports`
 by which the ``AuthenticationProviderManager``
 can determine if it supports the given token. If this is the case, the
-manager then calls the provider's method :class:`Symfony\\Component\\Security\\Core\\Authentication\\Provider\\AuthenticationProviderInterface::authenticate`. This method
-should return an authenticated token or throw an :class:`Symfony\\Component\\Security\\Core\\Exception\\AuthenticationException`
+manager then calls the provider's method :class:`Symfony\\Component\\Security\\Core\\Authentication\\Provider\\AuthenticationProviderInterface::authenticate`.
+This method should return an authenticated token or throw an
+:class:`Symfony\\Component\\Security\\Core\\Exception\\AuthenticationException`
 (or any other exception extending it).
 
-Authenticating users by their username and password
+Authenticating Users by their Username and Password
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 An authentication provider will attempt to authenticate a user based on
@@ -159,7 +160,7 @@ password was valid::
     It is also possible to let multiple user providers try to find the user's
     data, using the :class:`Symfony\\Component\\Security\\Core\\User\\ChainUserProvider`.
 
-The password encoder factory
+The Password encoder Factory
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The :class:`Symfony\\Component\\Security\\Core\\Authentication\\Provider\\DaoAuthenticationProvider`
@@ -186,7 +187,7 @@ Each encoder should implement :class:`Symfony\\Component\\Security\\Core\\Encode
 or be an array with a ``class`` and an ``arguments`` key, which allows the
 encoder factory to construct the encoder only when it is needed.
 
-Password encoders
+Password Encoders
 ~~~~~~~~~~~~~~~~~
 
 When the :method:`Symfony\\Component\\Security\\Core\\Encoder\\EncoderFactory::getEncoder`
diff --git a/components/security/authorization.rst b/components/security/authorization.rst
@@ -5,32 +5,31 @@ Authorization
 =============
 
 When any of the authentication providers (see :ref:`authentication_providers`)
-has verified the still unauthenticated token, an authenticated token will
+has verified the still-unauthenticated token, an authenticated token will
 be returned. The authentication listener should set this token directly
 in the :class:`Symfony\\Component\\Security\\Core\\SecurityContextInterface`
 using its :method:`Symfony\\Component\\Security\\Core\\SecurityContextInterface::setToken`
 method.
 
-From then on, the user is authenticated, i.e. means identified.
-Now, other parts of the application can use the token to decide whether
-or not the user may request a certain URI, or modify a certain object.
-This decision will be made by an instance of :class:`Symfony\\Component\\Security\\Core\\Authorization\\AccessDecisionManagerInterface`.
+From then on, the user is authenticated, i.e. identified. Now, other parts
+of the application can use the token to decide whether or not the user may
+request a certain URI, or modify a certain object. This decision will be made
+by an instance of :class:`Symfony\\Component\\Security\\Core\\Authorization\\AccessDecisionManagerInterface`.
 
 An authorization decision will always be based on a few things:
 
-The current token
+* The current token
     For instance, the token's :method:`Symfony\\Component\\Security\\Core\\Authentication\\Token\\TokenInterface::getRoles`
     method may be used to retrieve the roles of the current user (e.g.
-    "ROLE_SUPER_ADMIN"), or a decision may be based on the class of the token.
-A set of attributes
+    ``ROLE_SUPER_ADMIN``), or a decision may be based on the class of the token.
+* A set of attributes
     Each attribute stands for a certain right the user should have, e.g.
-    "ROLE_ADMIN" to make sure the user is an administrator.
-An object (optional)
-    Any object on which to decide, e.g. the current :class:`Symfony\\Component\\HttpFoundation\\Request`
-    object, or an object for which access control needs to be checked, like
+    ``ROLE_ADMIN`` to make sure the user is an administrator.
+* An object (optional)
+    Any object on which for which access control needs to be checked, like
     an article or a comment object.
 
-Access decision manager
+Access Decision Manager
 -----------------------
 
 Since deciding whether or not a user is authorized to perform a certain
@@ -39,14 +38,14 @@ itself depends on multiple voters, and makes a final verdict based on all
 the votes (either positive, negative or neutral) it has received. It
 recognizes several strategies:
 
-``affirmative`` (default)
-    Grant access as soon as any voter returns an affirmative response
+* ``affirmative`` (default)
+    grant access as soon as any voter returns an affirmative response;
 
-``consensus``
-    Grant access if there are more voters granting access then there are denying
+* ``consensus``
+    grant access if there are more voters granting access than there are denying;
 
-``unanimous``
-    Only grant access if none of the voters has denied access
+* ``unanimous``
+    only grant access if none of the voters has denied access;
 
 .. code-block:: php
 
@@ -79,23 +78,28 @@ of :class:`Symfony\\Component\\Security\\Core\\Authorization\\Voter\\VoterInterf
 which means they have to implement a few methods which allows the decision
 manager to use them:
 
-``supportsAttribute($attribute)``
-    Will be used to check if the voter knows how to handle the given attribute.
-``supportsClass($class)``
-    Will be used to check if the voter is able to grant or deny access for
-    an object of the given class.
-``vote(TokenInterface $token, $object, array $attributes)``
-    This method will do the actual voting and return a value equal to one
+* ``supportsAttribute($attribute)``
+    will be used to check if the voter knows how to handle the given attribute;
+
+* ``supportsClass($class)``
+    will be used to check if the voter is able to grant or deny access for
+    an object of the given class;
+
+* ``vote(TokenInterface $token, $object, array $attributes)``
+    this method will do the actual voting and return a value equal to one
     of the class constants of :class:`Symfony\\Component\\Security\\Core\\Authorization\\Voter\\VoterInterface`,
     i.e. ``VoterInterface::ACCESS_GRANTED``, ``VoterInterface::ACCESS_DENIED``
-    or ``VoterInterface::ACCESS_ABSTAIN``.
+    or ``VoterInterface::ACCESS_ABSTAIN``;
 
 The security component contains some standard voters which cover many use
 cases:
 
+AuthenticatedVoter
+~~~~~~~~~~~~~~~~~~
+
 The :class:`Symfony\\Component\\Security\\Core\\Authorization\\Voter\\AuthenticatedVoter`
-voter supports the attributes "IS_AUTHENTICATED_FULLY", "IS_AUTHENTICATED_REMEMBERED",
-and "IS_AUTHENTICATED_ANONYMOUSLY" and grants access based on the current
+voter supports the attributes ``IS_AUTHENTICATED_FULLY``, ``IS_AUTHENTICATED_REMEMBERED``,
+and ``IS_AUTHENTICATED_ANONYMOUSLY`` and grants access based on the current
 level of authentication, i.e. is the user fully authenticated, or only based
 on a "remember-me" cookie, or even authenticated anonymously?
 
@@ -118,30 +122,32 @@ on a "remember-me" cookie, or even authenticated anonymously?
 
     $vote = $authenticatedVoter->vote($token, $object, array('IS_AUTHENTICATED_FULLY');
 
+RoleVoter
+~~~~~~~~~
+
 The :class:`Symfony\\Component\\Security\\Core\\Authorization\\Voter\\RoleVoter`
-supports attributes starting with "ROLE_" and grants access to the user
-when the required "ROLE_*" attributes can all be found in the array of
+supports attributes starting with ``ROLE_`` and grants access to the user
+when the required ``ROLE_*`` attributes can all be found in the array of
 roles returned by the token's :method:`Symfony\\Component\\Security\\Core\\Authentication\\Token\\TokenInterface::getRoles`
-method.
-
-.. code-block:: php
+method::
 
     use Symfony\Component\Security\Core\Authorization\Voter\RoleVoter;
 
     $roleVoter = new RoleVoter('ROLE_');
 
     $roleVoter->vote($token, $object, 'ROLE_ADMIN');
 
+RoleHierarchyVoter
+~~~~~~~~~~~~~~~~~~
+
 The :class:`Symfony\\Component\\Security\\Core\\Authorization\\Voter\\RoleHierarchyVoter`
 extends :class:`Symfony\\Component\\Security\\Core\\Authorization\\Voter\\RoleVoter`
 and provides some additional functionality: it knows how to handle a
-hierarchy of roles. For instance, a "ROLE_SUPER_ADMIN" role may have subroles
-"ROLE_ADMIN" and "ROLE_USER", so that when a certain object requires the
-user to have the "ROLE_ADMIN" role, it grants access to users who in fact
-have the "ROLE_ADMIN" role, but also to users having the "ROLE_SUPER_ADMIN"
-role.
-
-.. code-block:: php
+hierarchy of roles. For instance, a ``ROLE_SUPER_ADMIN`` role may have subroles
+``ROLE_ADMIN`` and ``ROLE_USER``, so that when a certain object requires the
+user to have the ``ROLE_ADMIN`` role, it grants access to users who in fact
+have the ``ROLE_ADMIN`` role, but also to users having the ``ROLE_SUPER_ADMIN``
+role::
 
     use Symfony\Component\Security\Core\Authorization\Voter\RoleHierarchyVoter;
     use Symfony\Component\Security\Core\Role\RoleHierarchy;
@@ -179,26 +185,25 @@ first constructor argument::
 .. note::
 
     Most authentication tokens extend from :class:`Symfony\\Component\\Security\\Core\\Authentication\\Token\\AbstractToken`,
-    which means that the roles given to its constructor, will be
+    which means that the roles given to its constructor will be
     automatically converted from strings to these simple ``Role`` objects.
 
 Using the decision manager
 --------------------------
 
-The access listener
+The Access Listener
 ~~~~~~~~~~~~~~~~~~~
 
-Normally, the access decision manager will already be asked to decide whether
-or not the current user is entitled to make the current request. This is done
-by the :class:`Symfony\\Component\\Security\\Http\\Firewall\\AccessListener`,
+The access decision manager can be used at any point in a request to decide whether
+or not the current user is entitled to access a given resource. One optional,
+but useful, method for restricting access based on a URL pattern is the
+:class:`Symfony\\Component\\Security\\Http\\Firewall\\AccessListener`,
 which is one of the firewall listeners (see :ref:`firewall_listeners`) that
-will be triggered for each request matching the firewall map (see :ref:`firewall`).
+is triggered for each request matching the firewall map (see :ref:`firewall`).
 
 It uses an access map (which should be an instance of :class:`Symfony\\Component\\Security\\Http\\AccessMapInterface`)
 which contains request matchers and a corresponding set of attributes that
-are required for the current user to get access to the application.
-
-.. code-block:: php
+are required for the current user to get access to the application::
 
     use Symfony\Component\Security\Http\AccessMap;
     use Symfony\Component\HttpFoundation\RequestMatcher;
@@ -219,12 +224,10 @@ Security context
 ~~~~~~~~~~~~~~~~
 
 The access decision manager is also available to other parts of the application
-by means of the :method:`Symfony\\Component\\Security\\Core\\SecurityContext::isGranted`
+via the :method:`Symfony\\Component\\Security\\Core\\SecurityContext::isGranted`
 method of the :class:`Symfony\\Component\\Security\\Core\\SecurityContext`.
 A call to this method will directly delegate the question to the access
-decision manager.
-
-.. code-block:: php
+decision manager::
 
     use Symfony\Component\Security\SecurityContext;
     use Symfony\Component\Security\Core\Exception\AccessDeniedException;
diff --git a/components/security/firewall.rst b/components/security/firewall.rst
@@ -1,16 +1,14 @@
 .. index::
    single: Security, Firewall
 
-The Security Context
-====================
+The Firewall and Security Context
+=================================
 
 Central to the Security Component is the security context, which is an instance
 of :class:`Symfony\\Component\\Security\\Core\\SecurityContextInterface`. When all
 steps in the process of authenticating the user have been taken successfully,
-the security context may be asked if the authenticated user has access
-to a certain action or resource of the application.
-
-.. code-block:: php
+you can ask the security context if the authenticated user has access to a
+certain action or resource of the application::
 
     use Symfony\Component\Security\SecurityContext;
     use Symfony\Component\Security\Core\Exception\AccessDeniedException;
@@ -25,18 +23,16 @@ to a certain action or resource of the application.
 
 .. _firewall:
 
-A firewall for HTTP requests
-============================
+A Firewall for HTTP Requests
+----------------------------
 
 Authenticating a user is done by the firewall. An application may have
 multiple secured areas, so the firewall is configured using a map of these
 secured areas. For each of these areas, the map contains a request matcher
 and a collection of listeners. The request matcher gives the firewall the
 ability to find out if the current request points to a secured area.
 The listeners are then asked if the current request can be used to authenticate
-the user.
-
-.. code-block:: php
+the user::
 
     use Symfony\Component\Security\Http\FirewallMap;
     use Symfony\Component\HttpFoundation\RequestMatcher;
@@ -53,10 +49,8 @@ the user.
 
     $map->add($requestMatcher, $listeners, $exceptionListener);
 
-The firewall map will be given to the firewall as it's first argument, together
-with the event dispatcher that is used by the :class:`Symfony\\Component\\HttpKernel\\HttpKernel`.
-
-.. code-block:: php
+The firewall map will be given to the firewall as its first argument, together
+with the event dispatcher that is used by the :class:`Symfony\\Component\\HttpKernel\\HttpKernel`::
 
     use Symfony\Component\Security\Http\Firewall;
     use Symfony\Component\HttpKernel\KernelEvents;
@@ -76,33 +70,33 @@ further than allowed.
 .. _firewall_listeners:
 
 Firewall listeners
-------------------
+~~~~~~~~~~~~~~~~~~
 
 When the firewall gets notified of the ``kernel.request`` event, it asks
 the firewall map if the request matches one of the secured areas. The first
-secured area that matches the request, will return a set of corresponding
+secured area that matches the request will return a set of corresponding
 firewall listeners (which each implement :class:`Symfony\\Component\\Security\\Http\\Firewall\\ListenerInterface`).
 These listeners will all be asked to handle the current request. This basically
 means: find out if the current request contains any information by which
 the user might be authenticated (for instance the Basic HTTP authentication
-listener checks if the request has a header called "PHP_AUTH_USER").
+listener checks if the request has a header called ``PHP_AUTH_USER``).
 
 Exception listener
-------------------
+~~~~~~~~~~~~~~~~~~
 
 If any of the listeners throws an :class:`Symfony\\Component\\Security\\Core\\Exception\\AuthenticationException`,
 the exception listener that was provided when adding secured areas to the
 firewall map will jump in.
 
 The exception listener determines what happens next, based on the arguments
 it received when it was created. It may start the authentication procedure,
-maybe ask the user to supply his credentials again (when he has only been
+perhaps ask the user to supply his credentials again (when he has only been
 authenticated based on a "remember-me" cookie), or transform the exception
 into an :class:`Symfony\\Component\\HttpKernel\\Exception\\AccessDeniedHttpException`,
 which will eventually result in an "HTTP/1.1 403: Access Denied" response.
 
 Entry points
-------------
+~~~~~~~~~~~~
 
 When the user is not authenticated at all (i.e. when the security context
 has no token yet), the firewall's entry point will be called to "start"
@@ -112,6 +106,26 @@ which has only one method: :method:`Symfony\\Component\\Security\\Http\\EntryPoi
 This method receives the current :class:`Symfony\\Component\\HttpFoundation\\Request`
 object and the exception by which the exception listener was triggered.
 The method should return a :class:`Symfony\\Component\\HttpFoundation\\Response`
-object, for instance the page containing the login form, or in the case
-of Basic HTTP authentication a response with a "WWW-Authenticate" header,
-which will prompt the user to supply his username and password.
+object. This could be, for instance, the page containing the login form or,
+in the case of Basic HTTP authentication, a response with a ``WWW-Authenticate``
+header, which will prompt the user to supply his username and password.
+
+Flow: Firewall, Authentication, Authorization
+---------------------------------------------
+
+Hopefully you can now see a little bit about how the "flow" of the security
+context works:
+
+#. the Firewall is registered as a listener on the reques;
+#. at the beginning of the request, the Firewall checks the firewall map
+   to see if any firewall should be active for this URL;
+#. If a firewall is found on the map for this URL, its listeners are notified
+#. each listener checks to see if the current request contains any authentication
+   information - a listener may (a) authenticate a user, (b) throw an
+   ``AuthenticationException``, or (c) do nothing (because there is no
+   authentication information on the request);
+#. Once a user is authentication, you'll use :doc:`/components/security/authorization`
+   to deny access to certain resources.
+
+Read the next sections to find out more about :doc:`/components/security/authentication`
+and :doc:`/components/security/authorization`.
diff --git a/components/security/introduction.rst b/components/security/introduction.rst
@@ -20,8 +20,7 @@ Installation
 You can install the component in many different ways:
 
 * Use the official Git repository (https://github.com/symfony/Security);
-* Install it via PEAR ( `pear.symfony.com/Security`);
-* Install it via Composer (`symfony/security` on Packagist).
+* :doc:`Install it via Composer</components/using_components>` (``symfony/security`` on `Packagist`_).
 
 Sections
 --------
