Firewalls (Authentication)?

When a user makes a request to a URL that‘s protected by a firewall, the security system is activated. The job of the firewall is to determine whether or not the user needs to be authenticated, and if they do, to send a response back to the user initiating the authentication process.

A firewall is activated when the URL of an incoming request matches the configured firewall‘s regular expression pattern config value. In this example, the pattern (^/) will match every incoming request. The fact that the firewall is activated does not mean, however, that the HTTP authentication username and password box is displayed for every URL. For example, any user can access /foowithout being prompted to authenticate.

This works first because the firewall allows anonymous users via the anonymous configuration parameter. In other words, the firewall doesn‘t require the user to fully authenticate immediately. And because no special role is needed to access /foo (under the access_control section), the request can be fulfilled without ever asking the user to authenticate.

If you remove the anonymous key, the firewall will always make a user fully authenticate immediately.

Access Controls (Authorization)?

If a user requests /admin/foo, however, the process behaves differently. This is because of theaccess_control configuration section that says that any URL matching the regular expression pattern^/admin (i.e. /admin or anything matching /admin/*) requires the ROLE_ADMIN role. Roles are the basis for most authorization: a user can access /admin/foo only if it has the ROLE_ADMIN role.

Like before, when the user originally makes the request, the firewall doesn‘t ask for any identification. However, as soon as the access control layer denies the user access (because the anonymous user doesn‘t have the ROLE_ADMIN role), the firewall jumps into action and initiates the authentication process. The authentication process depends on the authentication mechanism you‘re using. For example, if you‘re using the form login authentication method, the user will be redirected to the login page. If you‘re using HTTP authentication, the user will be sent an HTTP 401 response so that the user sees the username and password box.

The user now has the opportunity to submit its credentials back to the application. If the credentials are valid, the original request can be re-tried.

In this example, the user ryan successfully authenticates with the firewall. But since ryan doesn‘t have the ROLE_ADMIN role, they‘re still denied access to /admin/foo. Ultimately, this means that the user will see some sort of message indicating that access has been denied.

Finally, if the admin user requests /admin/foo, a similar process takes place, except now, after being authenticated, the access control layer will let the request pass through:

The request flow when a user requests a protected resource is straightforward, but incredibly flexible. As you‘ll see later, authentication can be handled in any number of ways, including via a form login, X.509 certificate, or by authenticating the user via Twitter. Regardless of the authentication method, the request flow is always the same:

1. A user accesses a protected resource;
2. The application redirects the user to the login form;
3. The user submits its credentials (e.g. username/password);
4. The firewall authenticates the user;
5. The authenticated user re-tries the original request.

Securing Specific URL Patterns?

The most basic way to secure part of your application is to secure an entire URL pattern. You‘ve seen this already in the first example of this chapter, where anything matching the regular expression pattern ^/admin requires the ROLE_ADMIN role.

You can define as many URL patterns as you need - each is a regular expression.

Understanding how access_control works?

For each incoming request, Symfony2 checks each access_control entry to find one that matches the current request. As soon as it finds a matching access_control entry, it stops - only the firstmatching access_control is used to enforce access.

Each access_control has several options that configure two different things:

• 1. should the incoming request match this access control entry
• 2. once it matches, should some sort of access restriction be enforced:

Securing by IP?

Certain situations may arise when you may need to restrict access to a given path based on IP. This is particularly relevant in the case of Edge Side Includes (ESI), for example. When ESI is enabled, it‘s recommended to secure access to ESI URLs. Indeed, some ESI may contain some private content like the current logged in user‘s information. To prevent any direct access to these resources from a web browser (by guessing the ESI URL pattern), the ESI route must be secured to be only visible from the trusted reverse proxy cache.

New in version 2.3: Version 2.3 allows multiple IP addresses in a single rule with the ips: [a, b]construct. Prior to 2.3, users should create one rule per IP address to match and use the ip key instead of ips.

Here is an example of how you might secure all ESI routes that start with a given prefix, /esi, from outside access:

Here is how it works when the path is /esi/something coming from the 10.0.0.1 IP:

• The first access control rule is ignored as the path matches but the ip does not match either of the IPs listed;
• The second access control rule is enabled (the only restriction being the path and it matches): as the user cannot have the ROLE_NO_ACCESS role as it‘s not defined, access is denied (the ROLE_NO_ACCESS role can be anything that does not match an existing role, it just serves as a trick to always deny access).

Now, if the same request comes from 127.0.0.1 or ::1 (the IPv6 loopback address):

• Now, the first access control rule is enabled as both the path and the ip match: access is allowed as the user always has the IS_AUTHENTICATED_ANONYMOUSLY role.
• The second access rule is not examined as the first rule matched.

Securing by an Expression?

New in version 2.4: The allow_if functionality was introduced in Symfony 2.4.

Once an access_control entry is matched, you can deny access via the roles key or use more complex logic with an expression in the allow_if key:

In this case, when the user tries to access any URL starting with /_internal/secure, they will only be granted access if the IP address is 127.0.0.1 or if the user has the ROLE_ADMIN role.

Inside the expression, you have access to a number of different variables and functions includingrequest, which is the Symfony Request object (see Request).

For a list of the other functions and variables, see functions and variables.

Forcing a Channel (http, https)?

You can also require a user to access a URL via SSL; just use the requires_channel argument in anyaccess_control entries. If this access_control is matched and the request is using the http channel, the user will be redirected to https:

Securing a Controller?

Protecting your application based on URL patterns is easy, but may not be fine-grained enough in certain cases. When necessary, you can easily force authorization from inside a controller:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

// ...
use Symfony\Component\Security\Core\Exception\AccessDeniedException;

public function helloAction($name)
{
    if (false === $this->get(‘security.context‘)->isGranted(‘ROLE_ADMIN‘)) {
        throw new AccessDeniedException();
    }

    // ...
}

Thanks to the SensioFrameworkExtraBundle, you can also secure your controller using annotations:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

// ...
use Sensio\Bundle\FrameworkExtraBundle\Configuration\Security;

/**
 * @Security("has_role(‘ROLE_ADMIN‘)")
 */
public function helloAction($name)
{
    // ...
}

For more information, see the FrameworkExtraBundle documentation.

Securing other Services?

In fact, anything in Symfony can be protected using a strategy similar to the one seen in the previous section. For example, suppose you have a service (i.e. a PHP class) whose job is to send emails from one user to another. You can restrict use of this class - no matter where it‘s being used from - to users that have a specific role.

For more information on how you can use the Security component to secure different services and methods in your application, see How to secure any Service or Method in your Application.

Access Control Lists (ACLs): Securing Individual Database Objects?

Imagine you are designing a blog system where your users can comment on your posts. Now, you want a user to be able to edit their own comments, but not those of other users. Also, as the admin user, you yourself want to be able to edit all comments.

The Security component comes with an optional access control list (ACL) system that you can use when you need to control access to individual instances of an object in your system. Without ACL, you can secure your system so that only certain users can edit blog comments in general. But withACL, you can restrict or allow access on a comment-by-comment basis.

For more information, see the cookbook article: How to use Access Control Lists (ACLs).

Where do Users come from? (User Providers)?

During authentication, the user submits a set of credentials (usually a username and password). The job of the authentication system is to match those credentials against some pool of users. So where does this list of users come from?

In Symfony2, users can come from anywhere - a configuration file, a database table, a web service, or anything else you can dream up. Anything that provides one or more users to the authentication system is known as a "user provider". Symfony2 comes standard with the two most common user providers: one that loads users from a configuration file and one that loads users from a database table.

1
2
3

users:
    - { name: 77, password: pass, roles: ‘ROLE_USER‘ }
    - { name: user-name, password: pass, roles: ‘ROLE_USER‘ }

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

// src/Acme/UserBundle/Entity/User.php
namespace Acme\UserBundle\Entity;

use Symfony\Component\Security\Core\User\UserInterface;
use Doctrine\ORM\Mapping as ORM;

/**
 * @ORM\Entity
 */
class User implements UserInterface
{
    /**
     * @ORM\Column(type="string", length=255)
     */
    protected $username;

    // ...
}

Encoding the User‘s Password?

So far, for simplicity, all the examples have stored the users‘ passwords in plain text (whether those users are stored in a configuration file or in a database somewhere). Of course, in a real application, you‘ll want to encode your users‘ passwords for security reasons. This is easily accomplished by mapping your User class to one of several built-in "encoders". For example, to store your users in memory, but obscure their passwords via sha1, do the following:

By setting the iterations to 1 and the encode_as_base64 to false, the password is simply run through the sha1 algorithm one time and without any extra encoding. You can now calculate the hashed password either programmatically (e.g. hash(‘sha1‘, ‘ryanpass‘)) or via some online tool likefunctions-online.com

If you‘re creating your users dynamically (and storing them in a database), you can use even tougher hashing algorithms and then rely on an actual password encoder object to help you encode passwords. For example, suppose your User object is Acme\UserBundle\Entity\User (like in the above example). First, configure the encoder for that user:

In this case, you‘re using the stronger sha512 algorithm. Also, since you‘ve simply specified the algorithm (sha512) as a string, the system will default to hashing your password 5000 times in a row and then encoding it as base64. In other words, the password has been greatly obfuscated so that the hashed password can‘t be decoded (i.e. you can‘t determine the password from the hashed password).

New in version 2.2: As of Symfony 2.2 you can also use the PBKDF2 and BCrypt password encoders.

1
2
3
4
5
6

$factory = $this->get(‘security.encoder_factory‘);
$user = new Acme\UserBundle\Entity\User();

$encoder = $factory->getEncoder($user);
$password = $encoder->encodePassword(‘ryanpass‘, $user->getSalt());
$user->setPassword($password);

Retrieving the User Object?

After authentication, the User object of the current user can be accessed via the security.contextservice. From inside a controller, this will look like:

1
2
3
4

public function indexAction()
{
    $user = $this->get(‘security.context‘)->getToken()->getUser();
}

In a controller this can be shortcut to:

1
2
3
4

public function indexAction()
{
    $user = $this->getUser();
}

In a Twig Template this object can be accessed via the app.user key, which calls theGlobalVariables::getUser() method:

Using Multiple User Providers?

Each authentication mechanism (e.g. HTTP Authentication, form login, etc) uses exactly one user provider, and will use the first declared user provider by default. But what if you want to specify a few users via configuration and the rest of your users in the database? This is possible by creating a new provider that chains the two together:

Now, all authentication mechanisms will use the chain_provider, since it‘s the first specified. Thechain_provider will, in turn, try to load the user from both the in_memory and user_db providers.

You can also configure the firewall or individual authentication mechanisms to use a specific provider. Again, unless a provider is specified explicitly, the first provider is always used:

In this example, if a user tries to log in via HTTP authentication, the authentication system will use the in_memory user provider. But if the user tries to log in via the form login, the user_db provider will be used (since it‘s the default for the firewall as a whole).

For more information about user provider and firewall configuration, see the SecurityBundle Configuration ("security").

Hierarchical Roles?

Instead of associating many roles to users, you can define role inheritance rules by creating a role hierarchy:

In the above configuration, users with ROLE_ADMIN role will also have the ROLE_USER role. TheROLE_SUPER_ADMIN role has ROLE_ADMIN, ROLE_ALLOWED_TO_SWITCH and ROLE_USER (inherited fromROLE_ADMIN).

Access Control in Controllers?

Protecting your application based on URL patterns is easy, but may not be fine-grained enough in certain cases. When necessary, you can easily force authorization from inside a controller:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

// ...
use Symfony\Component\Security\Core\Exception\AccessDeniedException;

public function helloAction($name)
{
    if (false === $this->get(‘security.context‘)->isGranted(‘ROLE_ADMIN‘)) {
        throw new AccessDeniedException();
    }

    // ...
}

Access Control in Other Services?

In fact, anything in Symfony can be protected using a strategy similar to the one seen in the previous section. For example, suppose you have a service (i.e. a PHP class) whose job is to send emails from one user to another. You can restrict use of this class - no matter where it‘s being used from - to users that have a specific role.

For more information on how you can use the Security component to secure different services and methods in your application, see How to secure any Service or Method in your Application.

Access Control in Templates?

If you want to check if the current user has a role inside a template, use the built-in helper function:

New in version 2.4: The expression functionality was introduced in Symfony 2.4.

You can also use expressions inside your templates:

For more details on expressions and security, see Complex Access Controls with Expressions.

Access Control Lists (ACLs): Securing Individual Database Objects?

Imagine you are designing a blog system where your users can comment on your posts. Now, you want a user to be able to edit their own comments, but not those of other users. Also, as the admin user, you yourself want to be able to edit all comments.

The Security component comes with an optional access control list (ACL) system that you can use when you need to control access to individual instances of an object in your system. Without ACL, you can secure your system so that only certain users can edit blog comments in general. But withACL, you can restrict or allow access on a comment-by-comment basis.

For more information, see the cookbook article: How to use Access Control Lists (ACLs).

Comparing Strings?

The time it takes to compare two strings depends on their differences. This can be used by an attacker when the two strings represent a password for instance; it is known as a Timing attack.

Internally, when comparing two passwords, Symfony uses a constant-time algorithm; you can use the same strategy in your own code thanks to the StringUtils class:

1
2
3
4

use Symfony\Component\Security\Core\Util\StringUtils;

// is password1 equals to password2?
$bool = StringUtils::equals($password1, $password2);

Generating a secure Random Number?

Whenever you need to generate a secure random number, you are highly encouraged to use the Symfony SecureRandom class:

1
2
3
4

use Symfony\Component\Security\Core\Util\SecureRandom;

$generator = new SecureRandom();
$random = $generator->nextBytes(10);

The nextBytes() methods returns a random string composed of the number of characters passed as an argument (10 in the above example).

The SecureRandom class works better when OpenSSL is installed but when it‘s not available, it falls back to an internal algorithm, which needs a seed file to work correctly. Just pass a file name to enable it:

1
2

$generator = new SecureRandom(‘/some/path/to/store/the/seed.txt‘);
$random = $generator->nextBytes(10);