Symfony security component documentation is bad structured

[Smolky]

In the security component, in the first section, called Authentication. the first paragraph says:

When a request points to a secured area, and one of the listeners from the firewall map is able to extract the user's credentials from the current Request object, it should create a token, containing these credentials. The next thing the listener should do is ask the authentication manager to validate the given token, and return an authenticated token if the supplied credentials were found to be valid. The listener should then store the authenticated token using the token storage:

In the point of view from a user that is starting to use this component, this documentation strategy is very frustating

What is a firewall map? (I know it's explained futhermore). Why is has to be able to get the users' credentials from the Request? This means you could be already authenticated or you just submit an login form? What is a Token? Why I need a token with credentials? How long does this token is being valid? What is a TokenStorage? What is his purpose?

I miss very much the following sections:

• Key concepts
• Flow diagrams
• Class diagrams
• Public Api (interfaces) and default implementations

[mpdude]

Just came here to open an issue for this. 100% agree, even as a long time Symfony user I feel it is hard to understand!

Last time I read the chapter it looked like this and from what I recall, that was easier to understand.

Not sure whether #5289 or #5463 are going to help.

[javiereguiluz]

We agree that the Symfony Security docs need a lot of improvements. This is in our priority list ... but it's taking us a lot of time because of the massive complexity of the Security internals.

In any case, to focus all our discussions about this in one place, we've created a meta issue in #7496 and we've linked this issue from there. That's why we're closing your issue ... but only to avoid duplicated discussions. We won't forget about what you said here. Thanks!

[Nerogee]

@Smolky your good question just pointed out many questions as I had. First, sorry to post on this closed issue. My reason is there may be others who was confused by this security component may come here to seek help.

I found the security component is baked into a shape that is very hard to modified to fit my situation. For example, I have a page which some content are restricted to authorized user and some are not. Even a non-authenticated user (anonymous user can access). Can the security component be used to meet this requirement without massive modification?

[Smolky]

Hi. I'm not expert in Symfony, so I think it is better to post your question as a new post (including the version of Symfony you're using). Anyway, I think that in StackOverflow you will find help faster than here.