From 3da51104acb75fb2a90610d3eae824ef3842878a Mon Sep 17 00:00:00 2001 From: Johannes Schmitt Date: Fri, 7 Jan 2011 09:21:21 +0100 Subject: [PATCH] updated encoders --- guides/security/users.rst | 104 +++++++++++++++++++++++++++++--------- 1 file changed, 79 insertions(+), 25 deletions(-) diff --git a/guides/security/users.rst b/guides/security/users.rst index b0aab6efc68..0cc10c75f69 100644 --- a/guides/security/users.rst +++ b/guides/security/users.rst @@ -75,7 +75,7 @@ Encoding Passwords ~~~~~~~~~~~~~~~~~~ Instead of storing passwords in clear, you can encode them. When doing so, you -should use a +should retrieve a :class:`Symfony\\Component\\Security\\Encoder\\PasswordEncoderInterface` object:: @@ -91,12 +91,14 @@ object:: to check the user password; read the next section to learn how to make your authentication provider aware of the encoder to use. -For most use case, use -:class:`Symfony\\Component\\Security\\Encoder\\MessageDigestPasswordEncoder`:: +If you need to encode passwords in your application code, for example when the +user is signing up, or changing his password, you can retrieve the encoder from +the :class:`Symfony\\Component\\Security\\Encoder\\EncoderFactoryInterface`:: + $factory = $this->container->get('security.encoder_factory'); $user = new User(); - $encoder = new MessageDigestPasswordEncoder('sha1'); + $encoder = $factory->getEncoder($user); $password = $encoder->encodePassword('MyPass', $user->getSalt()); $user->setPassword($password); @@ -104,6 +106,79 @@ When encoding your passwords, it's better to also define a unique salt per user (the ``getSalt()`` method can return the primary key if users are persisted in a database for instance). +.. index:: + single: Security; Configuring Encoders + +Configuring Encoders +~~~~~~~~~~~~~~~~~~~~ + +In this section, we will look at how you can set-up different encoders for your +users. An encoder can either be one of the built-in encoders ( +:class:`Symfony\\Component\\Security\\Encoder\\PlaintextPasswordEncoder`, or +:class:`Symfony\\Component\\Security\\Encoder\\MessageDigestPasswordEncoder`), +or even a custom service. The following lists all available configuration +options, you only need to select the one which suits your needs best:: + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/security.yml + security.config: + encoders: + MyBundle/Entity/MyUser: sha512 + MyBundle/Entity/MyUser: plaintext + MyBundle/Entity/MyUser: + algorithm: sha512 + encode-as-base64: true + iterations: 5 + MyBundle/Entity/MyUser: + service: my.custom.encoder.service.id + + .. code-block:: xml + + + + + + + + + + + + .. code-block:: php + + // app/config/security.php + $container->loadFromExtension('security', 'config', array( + 'encoders' => array( + 'MyBundle\Entity\MyUser' => 'sha512', + 'MyBundle\Entity\MyUser' => 'plaintext', + 'MyBundle\Entity\MyUser' => array( + 'algorithm' => 'sha512', + 'encode-as-base64' => true, + 'iterations' => 5, + ), + 'MyBundle\Entity\MyUser' => array( + 'service' => 'my.custom.encoder.service.id', + ), + ), + )); + +.. note:: + + You must define an encoder for each of your user classes, but the + configuration *must not* overlap. If you want to use the same encoder for + all classes you can simply specify + :class:`Symfony\\Component\\Security\\User\\AccountInterface` as class + since all your user classes will implemented it. + .. index:: single: Security; AdvancedAccountInterface @@ -170,10 +245,6 @@ or a prototype. It is also the best provider when writing unit tests: users: foo: { password: foo, roles: ROLE_USER } bar: { password: bar, roles: [ROLE_USER, ROLE_ADMIN] } - encoded: - password_encoder: sha1 - users: - foo: { password: 0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33, roles: ROLE_USER } .. code-block:: xml @@ -183,11 +254,6 @@ or a prototype. It is also the best provider when writing unit tests: - - - sha1 - - .. code-block:: php @@ -199,15 +265,9 @@ or a prototype. It is also the best provider when writing unit tests: 'foo' => array('password' => 'foo', 'roles' => 'ROLE_USER'), 'bar' => array('password' => 'bar', 'roles' => array('ROLE_USER', 'ROLE_ADMIN')), )), - 'encoded' => array('password_encoder' => 'sha1', 'users' => array( - 'foo' => array('password' => '0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33', 'roles' => 'ROLE_USER'), - )), ), )); -The above configuration defines two in-memory providers. As you can see, the -second one uses 'sha1' to encode the user passwords. - .. index:: single: Security; Doctrine Entity Provider single: Doctrine; Doctrine Entity Provider @@ -236,7 +296,6 @@ yourself: security.config: providers: main: - password_encoder: sha1 entity: { class: SecurityBundle:User, property: username } .. code-block:: xml @@ -244,7 +303,6 @@ yourself: - sha1 @@ -255,7 +313,6 @@ yourself: $container->loadFromExtension('security', 'config', array( 'providers' => array( 'main' => array( - 'password_encoder' => 'sha1', 'entity' => array('class' => 'SecurityBundle:User', 'property' => 'username'), ), ), @@ -326,7 +383,6 @@ yourself: security.config: providers: main: - password_encoder: sha1 document: { class: SecurityBundle:User, property: username } .. code-block:: xml @@ -334,7 +390,6 @@ yourself: - sha1 @@ -345,7 +400,6 @@ yourself: $container->loadFromExtension('security', 'config', array( 'providers' => array( 'main' => array( - 'password_encoder' => 'sha1', 'document' => array('class' => 'SecurityBundle:User', 'property' => 'username'), ), ),