[#2914][WIP] Additions to the new authentication articles

The biggest difference is the extension of the API article to give more
details about the user provider and to talk about how you might store
authentication information in the session.
[#3357] Many many changes thanks to @WouterJ and @xabbuh
Merge pull request #3357 from symfony/security-2914-additions

New Security Authentication Additions