Added third chapter, on authorization

Author: matthiasnoback

components/security/authentication.rst

@@ -12,7 +12,7 @@ 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.
 The listener should then store the authenticated token in the security context:
 
-.. code-block:: php
+::
 
     use Symfony\Component\Security\Http\Firewall\ListenerInterface;
     use Symfony\Component\Security\Core\SecurityContextInterface;
@@ -22,10 +22,14 @@ The listener should then store the authenticated token in the security context:
 
     class SomeAuthenticationListener implements ListenerInterface
     {
-        /* @var SecurityContextInterface */
+        /**
+         * @var SecurityContextInterface
+         */
         private $securityContext;
 
-        /* @var AuthenticationManagerInterface */
+        /**
+         * @var AuthenticationManagerInterface
+         */
         private $authenticationManager;
 
         // string Uniquely identifies the secured area
@@ -37,6 +41,9 @@ The listener should then store the authenticated token in the security context:
         {
             $request = $event->getRequest();
 
+            $username = ...;
+            $password = ...;
+
             $unauthenticatedToken = new UsernamePasswordToken(
                 $username,
                 $password,
@@ -60,13 +67,12 @@ The authentication manager
 
 The default authentication manager is an instance of :class:`Symfony\\Component\\Security\\Core\\Authentication\\AuthenticationProviderManager`:
 
-.. code-block:: php
+::
 
     use Symfony\Component\Security\Core\Authentication\AuthenticationProviderManager;
 
-    $providers = array(
-        // instances of Symfony\Component\Security\Core\Authentication\AuthenticationProviderInterface
-    );
+    // instances of Symfony\Component\Security\Core\Authentication\AuthenticationProviderInterface
+    $providers = array(...);
 
     $authenticationManager = new AuthenticationProviderManager($providers);
 
@@ -85,6 +91,8 @@ authentication providers, each supporting a different type of token.
     You may of course write your own authentication manager, it only has
     to implement :class:`Symfony\\Component\\Security\\Core\\Authentication\\AuthenticationManagerInterface`.
 
+.. _authentication_providers:
+
 Authentication providers
 ------------------------
 
@@ -113,7 +121,7 @@ It fetches the user's data from a ``UserProvider``, uses a ``PasswordEncoder``
 to create a hash of the password and returns an authenticated token if the
 password was valid.
 
-.. code-block:: php
+::
 
     use Symfony\Component\Security\Core\Authentication\Provider\DaoAuthenticationProvider;
     use Symfony\Component\Security\Core\User\UserChecker;
@@ -131,7 +139,8 @@ password was valid.
     // for some extra checks: is account enabled, locked, expired, etc.?
     $userChecker = new UserChecker();
 
-    $encoderFactory = new EncoderFactory(/* ... encoders */);
+    // an array of password encoders (see below)
+    $encoderFactory = new EncoderFactory(...);
 
     $provider = new DaoAuthenticationProvider(
         $userProvider,
@@ -159,18 +168,25 @@ strategies for different types of users.
 The default :class:`Symfony\\Component\\Security\\Core\\Encoder\\EncoderFactory`
 receives an array of encoders:
 
-.. code-block:: php
+::
 
     use Symfony\Component\Security\Core\Encoder\EncoderFactory;
     use Symfony\Component\Security\Core\Encoder\MessageDigestPasswordEncoder;
 
     $defaultEncoder = new MessageDigestPasswordEncoder('sha512', true, 5000);
     $weakEncoder = new MessageDigestPasswordEncoder('md5', true, 1);
 
-    $encoderFactory = new EncoderFactory(array(
+    $encoders = array(
         'Symfony\\Component\\Security\\Core\\User\\User' => $defaultEncoder,
         'Acme\\Entity\\LegacyUser' => $weakEncoder,
-    ));
+        ...
+    );
+
+    $encoderFactory = new EncoderFactory($encoders);
+
+Each encoder should implement :class:`Symfony\\Component\\Security\\Core\\Encoder\\PasswordEncoderInterface`
+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
 ~~~~~~~~~~~~~~~~~
@@ -180,17 +196,18 @@ with the user object as its first argument, it will return an encoder of
 type :class:`Symfony\\Component\\Security\\Core\\Encoder\\PasswordEncoderInterface`
 which should be used to encode this user's password:
 
-.. code-block:: php
+::
 
-    $user = // ... fetch a user of type Acme\Entity\LegacyUser
+    // fetch a user of type Acme\Entity\LegacyUser
+    $user = ...
 
     $encoder = $encoderFactory->getEncoder($user);
 
     // will return $weakEncoder (see above)
 
     $encodedPassword = $encoder->encodePassword($password, $user->getSalt());
 
-    // or check if the password is valid:
+    // check if the password is valid:
 
     $validPassword = $encoder->isPasswordValid(
         $user->getPassword(),

components/security/authorization.rst

@@ -0,0 +1,224 @@
+.. index::
+   single: Security, Authorization
+
+Authorization
+=============
+
+When any of the authentication providers (see :ref:`authentication_providers`)
+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\\SecurityContext` using its
+``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`.
+
+An authorization decision will always be based on a few things:
+
+The current token
+    The token`s ``getRoles()`` method will be used to retrieve the roles
+    of the current user (e.g. "ROLE_SUPER_ADMIN")
+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.
+
+Access decision manager
+-----------------------
+
+Since choosing whether or not a user is authorized to perform a certain
+action can be a complicated process, the standard :class:`Symfony\\Component\\Security\\Core\\Authorization\\AccessDecisionManager`
+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
+
+``consensus``
+    Grant access if there are more voters granting access then there are denying
+
+``unanimous``
+    Only grant access if none of the voters has denied access
+
+::
+
+    use Symfony\Component\Security\Core\Authorization\AccessDecisionManager;
+
+    // instances of Symfony\Component\Security\Core\Authorization\Voter\VoterInterface
+    $voters = array(...);
+
+    // one of "affirmative", "consensus", "unanimous"
+    $strategy = ...;
+
+    // whether or not to grant access when all voters abstain
+    $allowIfAllAbstainDecisions = ...;
+
+    // whether or not to grant access when there is no majority (applies only to the "consensus" strategy)
+    $allowIfEqualGrantedDeniedDecisions = ...;
+
+    $accessDecisionManager = new AccessDecisionManager($voters, $strategy,
+        $allowIfAllAbstainDecisions, $allowIfEqualGrantedDeniedDecisions);
+
+Voters
+------
+
+Voters are instances
+of :class:`Symfony\\Component\\Security\\Core\\Authorization\\Voter\\VoterInterface`,
+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
+    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``.
+
+The security component contains some standard voters which cover many use
+cases:
+
+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
+level of authentication, i.e. is the user fully authenticated, or only based
+on a "remember-me" cookie, or even authenticated anonymously?
+
+::
+
+    use Symfony\Component\Security\Core\Authentication\AuthenticationTrustResolver;
+
+    $anonymousClass = 'Symfony\Component\Security\Core\Authentication\Token\AnonymousToken';
+    $rememberMeClass = 'Symfony\Component\Security\Core\Authentication\Token\RememberMeToken';
+
+    $trustResolver = new AuthenticationTrustResolver($anonymousClass, $rememberMeClass);
+
+    $authenticatedVoter = new AuthenticatedVoter($trustResolver);
+
+    // instance of Symfony\Component\Security\Core\Authentication\Token\TokenInterface
+    $token = ...
+
+    // any object
+    $object = ...
+
+    $vote = $authenticatedVoter->vote($token, $object, array('IS_AUTHENTICATED_FULLY');
+
+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
+roles returned by the token's ``getRoles()`` method.
+
+::
+
+    use Symfony\Component\Security\Core\Authorization\Voter\RoleVoter;
+
+    $roleVoter = new RoleVoter('ROLE_');
+
+    $roleVoter->vote($token, $object, 'ROLE_ADMIN');
+
+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.
+
+::
+
+    use Symfony\Component\Security\Core\Authorization\Voter\RoleHierarchyVoter;
+    use Symfony\Component\Security\Core\Role\RoleHierarchy;
+
+    $hierarchy = array(
+        'ROLE_SUPER_ADMIN' => array('ROLE_ADMIN', 'ROLE_USER'),
+    );
+
+    $roleHierarchy = new RoleHierarchy($hierarchy);
+
+    $roleHierarchyVoter = new RoleHierarchyVoter($roleHierarchy);
+
+.. note::
+
+    When you make your own voter, you may of course use its constructor
+    to inject any dependencies it needs to come to a decision.
+
+Roles
+-----
+
+Roles are objects that give expression to a certain right the user has.
+The only requirement is that they implement :class:`Symfony\\Component\\Security\\Core\\Role\\RoleInterface`,
+which means they should also have a ``getRole()`` method that returns a
+string representation of the role itself. The default :class:`Symfony\\Component\\Security\\Core\\Role\\Role`
+simply returns its first constructor argument:
+
+::
+
+    use Symfony\Component\Security\Core\Role\Role;
+
+    $role = new Role('ROLE_ADMIN');
+
+    // will echo 'ROLE_ADMIN'
+    echo $role->getRole();
+
+.. 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
+    automatically converted from strings to these simple ``Role`` objects.
+
+Using the decision manager
+--------------------------
+
+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`,
+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`).
+
+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.
+
+::
+
+    use Symfony\Component\Security\Http\AccessMap;
+    use Symfony\Component\HttpFoundation\RequestMatcher;
+    use Symfony\Component\Security\Http\Firewall\AccessListener;
+
+    $accessMap = new AccessMap();
+    $requestMatcher = new RequestMatcher('^/admin');
+    $accessMap->add($requestMatcher, array('ROLE_ADMIN'));
+
+    $accessListener = new AccessListener($securityContext, $accessDecisionManager,
+        $accessMap, $authenticationManager);
+
+Security context
+~~~~~~~~~~~~~~~~
+
+The access decision manager is also available to other parts of the application
+by means of the ``isGranted($attribute)`` method of the :class:`Symfony\\Component\\Security\\Core\\SecurityContext`.
+A call to this method will directly delegate the question to the access
+decision manager.
+
+::
+
+    use Symfony\Component\Security\SecurityContext;
+    use Symfony\Component\Security\Core\Exception\AccessDeniedException;
+
+    $securityContext = new SecurityContext();
+
+    if (!$securityContext->isGranted('ROLE_ADMIN')) {
+        throw new AccessDeniedException();
+    }