Documentation: Security documentation needs more detail

[awildeep]

At the behest of Ryan Weaver I am opening an issue about the Security documentation. I originally misopened this in symfony/symfony#2320. @jalliot mentioned there being an existing issue on this subject, but I did not find any currently open.

I have been trying to get my Symfony2 application secured, and I am hitting some major pain points when trying to use only SF2 documentation (http://symfony.com/doc/current/book/security.html):

1. Implementing the Symfony\Component\Security\Core\User\UserInterface needs more detail, specifically:
   1. A basic example.
   2. Developers with a weak understanding of inheritance will not understand that the property $username is not actually the only thing that needs to be defined (and in fact does not need to be defined at all given the interface).
   3. Symfony\Component\Security\Core\User\UserInterface::equals() needs some focus here. This is an issue for security, but we do not offer any advice except that a user "The equality comparison should neither be done by referential equality
      nor by comparing identities (i.e. getId() === getId()).". This is in the interface itself, not even in the book.
   4. equals(), eraseCredentials(), getUsername(), getSalt(), getPassword(), getRoles() should all at least be mentioned, and used in the basic example.
   5. It seems this may be in progress as I see http://symfony.com/doc/current/cookbook/security/entity_provider.html exists, but currently contains nothing.
2. Custom Role class is mentioned, but never shown. I actually am not sure why I would ever need the Role class myself, but if there is a need for this maybe a recipe showing an example?

From my perspective creating a http_basic login is VERY easy to do, when your users are stored in your YML. However I think it also is applicable to the smallest portion of developers. I assume most applications are going to use custom login forms. I also assume most applications will also use a datastore (DB, nosql, kerberos, etc) to store users, and not the configuration files.

I can say as a relatively new SF2 developer, I am finding this portion of my development to be the hardest portion so far. If I only had access to the book documentation my code would never be able to use a database for user storage.

EDIT: added missing formatting for readability.

[weaverryan]

Hey Greg!

Yes, I agree with all of your points about UserInterface. There is also an AdvancedUserInterface which is not currently documented (see #416).

The original idea was not to cover it in the security chapter (since there really are a lot of details to cover), hence the stubbed out cookbook about the entity provider. If that article were filled out with all of the details you're talking about, do you think you would know to look there as you read through the security chapter?

Per custom roles, I also have no idea when these would be needed :) - hopefully someone will see my message and comment with a perfect use-case.

Also, the FosUserBundle is what most people will actually be using if they're storing users in the database. We should consider adding a link to them here - it's quite a community effort. One problem is that people do seem to cloud what is Symfony's "security" and what the FOSUserBundle does (which is really not much - mostly just a datastore for your users).

Thanks!

[awildeep]

@weaverryan;
As far as not covering it in the security chapter; what about redoing the security chapter to focus on simple user implementation? EG: YML user configuration, and roles. Then link to other article(s)/recipe(s) to discuss custom login forms, and database storage. This way the security documentation can actually be pruned down a bunch, and it will be easier to keep up-to-date with patches etc.

I was trying to do this based on Symfony2 documentation (at least as much as possible). Basically trying to treat this as an experiment if I had no previous Symfony development background. Currently an end developer has no way of knowing about FosUserBundle. Nor does that developer know the pros/cons of using FosUserBundle vs the built in security code. Nor do they know if FosUserBundle is up-to-date-and-working. If it is truly that good by comparison, should we not look into trying to incorporate the FosUserBundle into the core? I like that for truly simple applications I can use the YML configuration, and not even need a DB (FosUserBundle requires a datastore as far as I can tell). This seems like it may be off topic, and may need it's own issue somewhere?

Also to answer your question about knowing to look in the security chapter, it was the second place I looked for user auth. First I went to the source code, then to the book. This may not be a logical path to others though.

Ultimately, I believe a single solid and simple example explaining a UserInterface implementing a datastore will go a long way to helping users develop. But maybe that does not belong inside the book documentation, but instead as a separate recipe?

[althaus]

Hi there,

I found this issue as I'm currently fighting against the Security component. I based my code on the FOSUserBundle, but have some issues with simple things, which should be somehow made clearer in the doc:

"Retrieving the User Object"
In the note about anonymous users it's stated that "isAuthenticated() method of an anonymous user object will return true". This is quite misleading as I tried $user->isAuthenticated() which fails due to the fact that you're not getting a user object at all (or is this only with FOSUserBundle the case?). So $user->hasRole('IS_AUTHENTICATED_FULLY') won't work too.

I got the simple check if a user is logged in with the hint from "Access Control in Controllers" and using $this->get("security.context")->isGranted('IS_AUTHENTICATED_FULLY') at the end.

This is such a simple use case that it should stated more clearer in my eyes.

Cheers
Matthias

[hhamon]

I don't know why people always want to use the FOSUserBundle. The security component is simple enough to create a user layer for the application. FOSUserBundle is not the only solution and it does not fit all needs. It's also a very complex API regarding the security layer of Symfony.

The Symfony documentation must remain free of extra community bundles. We don't need any documentation related to the FOSUserBundle. If you want use cases for the FOSUserBundle, update the documentation of the bundle, not the Symfony documentation.

[althaus]

I'm pretty sure that my concern in not related to FOSUserBundle and you're right that external bundles shouldn't be covered by the documenation directly.

[stof]

@althaus As stated by the phpdoc of the hasRole in the UserInterface, it should not be used to check permissions. It is used by the SecurityContext when you call isGranted.
And isAuthenticated is not a method of the user but of the token.

@awildeep There is no question about using FOSUserBundle vs the built-in security code. FOSUserBundle cannot be used without the Security component and it does not provide a security authentication. It only provides the user management part.

[althaus]

@stof: Yeah... I was struggeling with this:

Anonymous users are technically authenticated, meaning that the isAuthenticated() method of an anonymous user object will return true.

I tried to combine that with $user = $this->get('security.context')->getToken()->getUser(); from the code part above the note, but this will not lead to anything working as there is no anonymous user object.

...->getUser() will just return a string anon..

This should be clarified.

[awildeep]

FYI, I don't think Symfony should include doc on 3rd party bundles. At best maybe a reference to the project, but that may also be a stretch.

@stof I agree. Which is why I don't think FOSUserBundle can be the solution. And as hhammon has stated, it is very complex.

My main point it that the UserInterface needs better documentation to allow users to actually implement a datastore other than YML.

[catchamonkey]

This really is one of the last remaining pieces of the puzzle that is required to get people en masse from 1.4 et al.

I feel we should aim for a decent cookbook that explains the implementation of the functionality that was always offered by sfGuard.

And I agree that the official docs should not point to outside Bundles, its about understanding the implementation via docs for me. Or looking at official best practices in core bundles.

[mrtorrent]

I agree that the documentation is very weak here. I worked my way through most of the security system recently in order to implement authentication against Wordpress (see here), so I now have a pretty good understanding of its workings. I'd be willing to flesh out the docs, but I know I won't have time for a few weeks, if not a couple months. If anyone decides to work on them in the meantime, feel free to get in touch with me if you're struggling to work something out and I might be able to help explain it.

[awildeep]

Honestly I gave up trying to use the SF2 security code, and opted for the FOS implementation. It is complete overkill for what I need, but the doc makes sense, is usable, and has clear doc.

I think the main reason the FOS UserBundle is so popular is that it is much easier to implement than trying to muck your way through the SF2 core functionality. I have a feeling it will continue to be more popular unless this is fixed.

Edited: changed a mistake, it is not SecurityBundle, but UserBundle. Thanks stof.

[stof]

There is no FOS SecurityBundle.
And FOSUserBundle provides the user management for the core SecurityBundle, it is not an alternate implementation of the security part

[awildeep]

@stof, I put the wrong name in.

I know it is not implementing it's own user management, but it makes using the code in the core massively easier then if you did not have it.

[weaverryan]

So, after all of this, I think that a tutorial-styled cookbook article is a good idea that covers the following:

• User class that implements the UserInterface at is persisted in some way
• Login form
• authorization via access controls and AccessDeniedException
• checking if a user is "authenticated" to show login link vs logout link

I think it should be as basic as possible, linking back to the main chapter for all the technical details. It is such a complex topic that I agree that a nice little "tutorial" can go a long way.

So, volunteers? :)

[mrtorrent]

I'm up for writing it but, as I mentioned, won't have time for a wee while yet.