Rethink Symfony Security docs

[javiereguiluz]

There are some PRs:

• Older attempt to rewrite docs: [Pre-Draft][WIP] Started rewriting Security component docs #5463
• Newer attempt to reorganize all contents: Revamped the main security article #7293

There are some issues with ideas:

• Authentication is not clearly explained (Authentication is not clearly explained #6823)
• Better explain roles, attributes, expressions, ACL permission maps, etc. ([DX] Fix the documentation about the Symfony security #4158)
• Rewrite Firewall introduction (Rewrite firewall introduction #4759)
• Add article showing an overview of the internals ([Security] Add article showing an overview of the internals #5289) (Security documentation: The Big Picture is missing #7532) ("Deep into" articles #7297)
• Explain key concepts (e.g. Token), add flow diagrams, etc. (Symfony security component documentation is bad structured #6861)

---

Now, let's make some decisions about what to do with this.

[linaori]

Some time ago, I wrote a few blog posts about security. While they are slightly opinionated, they have helped a lot of people understand the concept of the security bundle/component and how authentication works.

• https://stovepipe.systems/post/decoupling-your-security-user
• https://stovepipe.systems/post/the-basics-of-symfony-security
• https://stovepipe.systems/post/symfony-security-roles-vs-voters

@Ricknox has written a blog post based on the decoupling, with examples and all, but it seems his blog is down (hint hint)

You're free to grab what ever content/ideas you want from my blog posts. When I have some time, I might be able to help around as well.

[gnugat]

if it can help, here's a summary of Symfony Authentication, based on Kris Wallsmith's talk:

Authentication

Are you who you say you are?

• Firewalls:
  • listen on kernel.event
  • have many listeners
• Authentication Listeners:
  • map client data from request to token
  • pass token to authentication manager
  • update state of security context
• Authentication Managers:
  • responsible of authenticating the token
  • call the appropriate authentication provider
  • handle exceptions
  • have many authentication providers
• Authentication Providers:
  • perform authentication using client data in the token
  • mark the token as authenticated
  • attach the user to the token
  • may rely on user provider
• User Providers:
  • retrieve the user (from a database, a configuration file, etc)

References

• Kris Wallsmith' slides: Love and Loss: a Symfony Security play

[gnugat]

Maybe it's worth adding a few words of caution regarding FOSUserBundle? Here's an article that says it all (although to be fair this is true for any bundles): Do not use FOSUserBundle.

[jkufner]

Here is the first draft of a diagram presenting the security internals. The goal of this diagram is to map the most important components and their connections. I drew it as I digged through Symfony source code. It is incomplete, however, I would like to have some feedback whether it reflects reality and how it is understandable so far.

[Nerogee]

Would it be a good idea to provide some guides on how to build customized Authentication and Authorization system ? I have an application which is already built with the ACL part, user and role (and role to resources mapping) and the security component seem not the right choice even though I have not completely understood how dose it work. Within security component, how can I

1. hook my customized login form after successfully login with security component and store user state in whatever forms. It would be token storage, session, or cookie and things about 'remember me', how should it be done with security component.

2. After user is authenticated, and a page is presented. But some content is restricted only to user who has permission and some are not. Even anonymous user can see that content. In such case, how does the ACL play its part along with authenticated user? (I believe this is something has to be implemented at controller level instead of the early stage of request event)

3. How to authenticate following requests from an already authenticated user? (it is not like the login form where usually username is passed along with password. How does security component play its part here? )

I can built my own authentication and authorization system on top of symfony. But I believe it's better to utilize existing component. This is why i came across to security component. Soon after a few hours of reading the documentation, i got more confusion, as stated here #6861 than answers.

[ghost]

Like @iltar told, the blogpost is at https://ricknox.com/blog/2017/01/decoupling-the-security-entity.html

What can I do to help continue this issue? cc/ @javiereguiluz @weaverryan

[weaverryan]

This is such a big issue, that I'm not sure where to start honestly! But, I would love to help support people - looking at you @ricknox! ;) - in working towards improving this.

What's the first step? We ultimately need to rewrite/revamp the main security chapter. To do that, we should list all of the most problems/tasks that you do with security (@xabbuh says that here: #7293 (comment)). Then, we can rewrite the main article and start to organize the sub-articles (and possible remove some, as I think we should emphasize Guard much more than true custom authentication setups).

And unrelated to the docs, we should probably improve the Flex recipe for security: https://github.com/symfony/recipes/blob/master/symfony/security-bundle/3.3/config/packages/security.yaml. This file could have a lot more commented-out options and links to documentation.

If we're going to do this, we should move quickly. In a couple of months, we will need to massively update the docs on master anyways, for Flex changes. If we've made some significant changes before then, that's great: it will make that job much easier. If not, we will likely just make some quicker changes to security, but on master only.

Cheers!

[javiereguiluz]

Honest (and unpopular) opinion: we shouldn't work on this until the Security code/features are updated/simplified/fixed.

[darius-v]

Tried to go by this documentation page:

https://symfony.com/doc/current/security/form_login_setup.html

And was getting error:

"The child node "providers" at path "security" must be configured."

Step of how to fix this should be added to documentation. I found part of anwser here:

https://stackoverflow.com/questions/27250259/fosoauthserverbundle-the-child-node-providers-at-path-security-must-be-con and here:

http://symfony.com/doc/current/security.html#loading-users-from-the-database

Login page works now.

But on submit again error which can be fixed by this:

https://stackoverflow.com/questions/25248490/symfony2-this-authentication-method-requires-a-session-error-on-login-check

framework:
    # ...
    session: ~

[javiereguiluz]

Closing in favor of #10423, which is making great improvements in Security docs.