[DX] Fix the documentation about the Symfony security

[javiereguiluz]

If you read this DX issue regarding the security roles, you can read one of the usual awesome replies by @stof: symfony/symfony#11728 (comment)

You'll see that the Security chapter and cookbooks need some serious improvements. Given that we are talking about Security, I think that this should be a high priority issue.

For now, this is the roadmap of changes to make:

• Never mention that IS_AUTHENTICATED_* are roles. They are not.
• Better explain the differences between roles, strings, expressions, ACL permissions maps, etc.
• ...

[stof]

Another reason why it is important to fix it: the expression-language security functions added in 2.4 (with the annotation in FrameworkExtraBundle 3.0) are defining has_role() which only checks for roles, and so will not grant access for IS_AUTHENTICATED_*. See https://groups.google.com/forum/#!topic/symfony2/cyNRtjfrI8Q for such a user support request

[weaverryan]

Hi guys!

A few thoughts/questions:

1. I was following the conversation on the linked issue, but I'm not convinced that I understand the problem (on a non-technical level) of calling both roles. This was originally done purely for simplicity. Explaining roles, attributes, etc seems a bit more complex.

2. I've always felt that the has_role() function seemed like a mistake. the isGranted() method gives us a nice interface that is able to handle true ROLE_ strings or attributes handled by any other voters. The has_role() is limited and breaks the simple, consistent API. There is an is_granted() function in the security expression-language, but it only exists with the SensioFrameworkExtraBundle. This also seems odd - why would this need to live outside of FrameworkBundle? I think I'm probably missing something here :).

Thanks!

[stof]

@weaverryan is_granted does not exist in the expression passed to isGranted directly, because it would be a circular reference: the voter depending on the full authentication manager.
SensioFrameworkExtraBundle adds the is_granted function, because it evaluates the expression outside the security voting system, so there is no circular reference. Note btw that using has_role to check for roles will thus be much faster than is_granted by calling directly the appropriate logic rather than all voters.

Regarding the distinction between roles and attributes, I think the fact that the doc does not explain this distinction is the source of many support requests about custom voters: the doc starts by saying that roles start with ROLE_, then talks about some special IS_AUTHENTICATED_* "roles" named differently (hint: not roles) and then says you can implement your own voter supporting other things (and even talking about ACLs later). After that, the logical question coming in is "what is a role ?". The first definition (the right one) does not apply anymore.
I already got someone asking me why the role hierarchy was not working for things checked by a custom voter. another time was someone being confused about $token->getRoles() not containing the IS_AUTHENTICATED_FULLY role. In both cases, the reason was a confusion between roles and permission attributes.

[weaverryan]

@stof Thanks for the explanation. But from a usability perspective, I still think it's not great. isGranted and is_granted (in Twig) are consistent ideas that we can teach. With the introduction of has_role (for technical reasons), things get shakier. And my guess is that the performance gain is a micro-optimization. I know this is outside of the scope of this docs ticket, but I think this sucks.

About your second paragraph, these are really clear reasons and it helps a lot. And now I agree that we should make a distinction between roles and attributes.