feature #5921 [2.8] Document some Security changes (WouterJ)

This PR was merged into the 2.8 branch.

Discussion
----------

[2.8] Document some Security changes

| Q | A
| --- | ---
| Doc fix? | no
| New docs? | yes (symfony/symfony#15131, symfony/symfony#16493, symfony/symfony#15151
| Applies to | 2.8+
| Fixed tickets | -

Commits
-------

0526ca0 Document deprecation of supports{Attribute,Class}() methods
22026ee Document Security key to secret renamings
4036d26 Use new Simple{Form,Pre}AuthenticatorInterface namespaces

Author: weaverryan

components/security/authorization.rst

@@ -90,10 +90,10 @@ 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)``
+``supportsAttribute($attribute)`` (deprecated as of 2.8)
     will be used to check if the voter knows how to handle the given attribute;
 
-``supportsClass($class)``
+``supportsClass($class)`` (deprecated as of 2.8)
     will be used to check if the voter is able to grant or deny access for
     an object of the given class;
 
@@ -103,6 +103,12 @@ manager to use them:
     i.e. ``VoterInterface::ACCESS_GRANTED``, ``VoterInterface::ACCESS_DENIED``
     or ``VoterInterface::ACCESS_ABSTAIN``;
 
+.. note::
+
+    The ``supportsAttribute()`` and ``supportsClass()`` methods are deprecated
+    as of Symfony 2.8 and no longer required in 3.0. These methods should not
+    be called outside the voter class.
+
 The Security component contains some standard voters which cover many use
 cases:
 

cookbook/security/api_key_authentication.rst

@@ -16,8 +16,14 @@ passed as a query string parameter or via an HTTP header.
 The API Key Authenticator
 -------------------------
 
+.. versionadded:: 2.8
+    The ``SimplePreAuthenticatorInterface`` interface was moved to the
+    ``Symfony\Component\Security\Http\Authentication`` namespace in Symfony
+    2.8. Prior to 2.8, it was located in the
+    ``Symfony\Component\Security\Core\Authentication`` namespace.
+
 Authenticating a user based on the Request information should be done via a
-pre-authentication mechanism. The :class:`Symfony\\Component\\Security\\Core\\Authentication\\SimplePreAuthenticatorInterface`
+pre-authentication mechanism. The :class:`Symfony\\Component\\Security\\Http\\Authentication\\SimplePreAuthenticatorInterface`
 allows you to implement such a scheme really easily.
 
 Your exact situation may differ, but in this example, a token is read
@@ -27,13 +33,13 @@ value and then a User object is created::
     // src/AppBundle/Security/ApiKeyAuthenticator.php
     namespace AppBundle\Security;
 
-    use Symfony\Component\Security\Core\Authentication\SimplePreAuthenticatorInterface;
+    use Symfony\Component\HttpFoundation\Request;
+    use Symfony\Component\Security\Core\Authentication\Token\PreAuthenticatedToken;
     use Symfony\Component\Security\Core\Authentication\Token\TokenInterface;
     use Symfony\Component\Security\Core\Exception\AuthenticationException;
-    use Symfony\Component\Security\Core\Authentication\Token\PreAuthenticatedToken;
-    use Symfony\Component\HttpFoundation\Request;
-    use Symfony\Component\Security\Core\User\UserProviderInterface;
     use Symfony\Component\Security\Core\Exception\BadCredentialsException;
+    use Symfony\Component\Security\Core\User\UserProviderInterface;
+    use Symfony\Component\Security\Http\Authentication\SimplePreAuthenticatorInterface;
 
     class ApiKeyAuthenticator implements SimplePreAuthenticatorInterface
     {
@@ -273,9 +279,9 @@ you can use to create an error ``Response``.
     // src/AppBundle/Security/ApiKeyAuthenticator.php
     namespace AppBundle\Security;
 
-    use Symfony\Component\Security\Core\Authentication\SimplePreAuthenticatorInterface;
     use Symfony\Component\Security\Core\Exception\AuthenticationException;
     use Symfony\Component\Security\Http\Authentication\AuthenticationFailureHandlerInterface;
+    use Symfony\Component\Security\Http\Authentication\SimplePreAuthenticatorInterface;
     use Symfony\Component\HttpFoundation\Response;
     use Symfony\Component\HttpFoundation\Request;
 
@@ -506,8 +512,8 @@ for security reasons. To take advantage of the session, update ``ApiKeyAuthentic
 to see if the stored token has a valid User object that can be used::
 
     // src/AppBundle/Security/ApiKeyAuthenticator.php
-    // ...
 
+    // ...
     class ApiKeyAuthenticator implements SimplePreAuthenticatorInterface
     {
         // ...

cookbook/security/custom_password_authenticator.rst

@@ -21,22 +21,28 @@ The Password Authenticator
 .. versionadded:: 2.6
     The ``UserPasswordEncoderInterface`` interface was introduced in Symfony 2.6.
 
+.. versionadded:: 2.8
+    The ``SimpleFormAuthenticatorInterface`` interface was moved to the
+    ``Symfony\Component\Security\Http\Authentication`` namespace in Symfony
+    2.8. Prior to 2.8, it was located in the
+    ``Symfony\Component\Security\Core\Authentication`` namespace.
+
 First, create a new class that implements
-:class:`Symfony\\Component\\Security\\Core\\Authentication\\SimpleFormAuthenticatorInterface`.
+:class:`Symfony\\Component\\Security\\Http\\Authentication\\SimpleFormAuthenticatorInterface`.
 Eventually, this will allow you to create custom logic for authenticating
 the user::
 
     // src/Acme/HelloBundle/Security/TimeAuthenticator.php
     namespace Acme\HelloBundle\Security;
 
     use Symfony\Component\HttpFoundation\Request;
-    use Symfony\Component\Security\Core\Authentication\SimpleFormAuthenticatorInterface;
     use Symfony\Component\Security\Core\Authentication\Token\TokenInterface;
     use Symfony\Component\Security\Core\Authentication\Token\UsernamePasswordToken;
     use Symfony\Component\Security\Core\Encoder\UserPasswordEncoderInterface;
     use Symfony\Component\Security\Core\Exception\AuthenticationException;
     use Symfony\Component\Security\Core\Exception\UsernameNotFoundException;
     use Symfony\Component\Security\Core\User\UserProviderInterface;
+    use Symfony\Component\Security\Http\Authentication\SimpleFormAuthenticatorInterface;
 
     class TimeAuthenticator implements SimpleFormAuthenticatorInterface
     {

cookbook/security/remember_me.rst

@@ -84,7 +84,8 @@ The ``remember_me`` firewall defines the following configuration options:
 
 ``secret`` (**required**)
     .. versionadded:: 2.8
-        Prior to Symfony 2.8, the ``secret`` option was named ``key``.
+        The ``secret`` option was introduced in Symfony 2.8. Prior to 2.8, it
+        was named ``key``.
 
     The value used to encrypt the cookie's content. It's common to use the
     ``secret`` value defined in the ``app/config/parameters.yml`` file.

reference/configuration/security.rst

@@ -180,7 +180,7 @@ Each part will be explained in the next section.
 
                     remember_me:
                         token_provider: name
-                        secret: someS3cretKey
+                        secret: "%secret%"
                         name: NameOfTheCookie
                         lifetime: 3600 # in seconds
                         path: /foo
@@ -227,7 +227,7 @@ Each part will be explained in the next section.
                                 domain:               ~
                         handlers:             []
                     anonymous:
-                        secret:               4f954a0667e01
+                        secret:               "%secret%"
                     switch_user:
                         provider:             ~
                         parameter:            _switch_user
@@ -246,6 +246,10 @@ Each part will be explained in the next section.
                 ROLE_ADMIN:      [ROLE_ORGANIZER, ROLE_USER]
                 ROLE_SUPERADMIN: [ROLE_ADMIN]
 
+.. versionadded:: 2.8
+    The ``secret`` option of ``anonymous`` and ``remember_me`` was introduced
+    in Symfony 2.8. Prior to 2.8, it was called ``key``.
+
 .. _reference-security-firewall-form-login:
 
 Form Login Configuration
@@ -479,7 +483,7 @@ multiple firewalls, the "context" could actually be shared:
 HTTP-Digest Authentication
 --------------------------
 
-To use HTTP-Digest authentication you need to provide a realm and a key:
+To use HTTP-Digest authentication you need to provide a realm and a secret:
 
 .. configuration-block::
 
@@ -490,15 +494,15 @@ To use HTTP-Digest authentication you need to provide a realm and a key:
             firewalls:
                 somename:
                     http_digest:
-                        key: "a_random_string"
+                        secret: "%secret%"
                         realm: "secure-api"
 
     .. code-block:: xml
 
         <!-- app/config/security.xml -->
         <security:config>
             <firewall name="somename">
-                <http-digest key="a_random_string" realm="secure-api" />
+                <http-digest secret="%secret%" realm="secure-api" />
             </firewall>
         </security:config>
 
@@ -509,12 +513,16 @@ To use HTTP-Digest authentication you need to provide a realm and a key:
             'firewalls' => array(
                 'somename' => array(
                     'http_digest' => array(
-                        'key'   => 'a_random_string',
-                        'realm' => 'secure-api',
+                        'secret' => '%secret%',
+                        'realm'  => 'secure-api',
                     ),
                 ),
             ),
         ));
 
+.. versionadded:: 2.8
+    The ``secret`` option was introduced in Symfony 2.8. Prior to 2.8, it was
+    called ``key``.
+
 .. _`PBKDF2`: https://en.wikipedia.org/wiki/PBKDF2
 .. _`ircmaxell/password-compat`: https://packagist.org/packages/ircmaxell/password-compat