[Security] AuthenticatorManager to make "authenticators" first-class security

[wouterj]

Q	A
Branch?	master
Bug fix?	no
New feature?	yes
Deprecations?	no
Tickets	-
License	MIT
Doc PR	tbd

The tl;dr

The old authentication listener + authentication provider system was replaced by a new "authenticator" system (similar to Guard authentication). All existing "auth systems" (e.g. form_login are now written as an "authenticator" in core).

Instead of each "authentication system" registering its own listener in the Firewall, there is now only one listener: AuthenticatorManagerListener

• Firewall -> executes AuthenticatorManagerListener
• AuthenticatorManagerListener -> calls AuthenticatorManager
• AuthenticatorManager -> calls each authenticator

This PR contains no deprecations and the "new system" is marked as experimental. This allows to continue to develop the new Security system during the 5.x release cycle without disturbing Symfony users. In 5.4, we can deprecate "old" Security and remove it completely in 6.0.

Important Decisions

• A) The new authentication manager - AuthenticatorManager - now dispatches 3 important "hook" events:

  • VerifyAuthenticatorCredentialsEvent: occurs at the point when a "password" needs to be checked. Allows us to centralize password checking, CSRF validation, password upgrading and the "user checker" logic.
  • LoginSuccessEvent: Dispatched after a successful authentication. E.g. used by remember me listener.
  • LoginFailedEvent: Dispatched after an unsuccessful authentication. Also used by remember me (and in theory could be used for login throttling).

• B) getCredentials(), getUser() and checkCredentials() methods from old Guard are gone: their logic is centralized.
  Authenticators now have an authenticate(Request $request): PassportInterface method. A passport contains the user object, the credentials and any other add-in Security badges (e.g. CSRF):

  public function authenticate(Request $request): PassportInterface
  {
      return new Passport(
          $user,
          new PasswordCredentials($request->get('_password')),
          [
              new CsrfBadge($request->get('_token'))
          ]
      );
  }

  All badges (including the credentials) need to be resolved by listeners to VerifyAuthenticatorCredentialsEvent. There is build-in core support for the following badges/credentials:

  • PasswordCredentials: validated using the password encoder factory
  • CustomCredentials: allows a closure to do credentials checking
  • CsrfTokenBadge: automatic CSRF token verification
  • PasswordUpgradeBadge: enables password migration
  • RememberMeBadge: enables remember-me support for this authenticator

• C) AuthenticatorManager contains all logic to authenticate
  As authenticators always relate to HTTP, the AuthenticatorManager contains all logic to authenticate. It has three methods, the most important two are:

  • authenticateRequest(Request $request): TokenInterface: Doing what is previously done by a listener and an authentication provider;
  • authenticateUser(UserInterface $user, AuthenticatorInterface $authenticator, Request $request, array $badges = []) for manual login in e.g. a controller.

• D) One AuthenticatorManager per firewall
  In the old system, there was 1 authentication manager containing all providers and each firewall had a specific firewall listener. In the new system, each firewall has a specific authentication manager.

• E) Pre-authentication tokens are dropped.
  As everything is now handled inside AuthenticatorManager and everything is stored in the Security Passport, there was no need for a token anymore (removing lots of confusion about what information is inside the token).

  This change deprecates 2 authentication calls: one in AuthorizationChecker#isGranted() and one in AccessListener. These seem now to be mis-used to reload users (e.g. re-authenticate the user after you change their roles). This (some "way" to change a user's roles without logging them out) needs to be "fixed"/added in another PR.

• F) The remember me service now uses all user providers
  Previously, only user providers of authentication providers listening on that firewall were used. This change is due to practical reasons and we don't think it is common to have 2 user providers supporting the same user instance. In any case, you can always explicitly configure the user provider under remember_me.

• G) Auth Providers No Longer Clear the Token on Auth Failure
  Previously, authentication providers did $this->tokenStorage->setToken(null) upon authentication failure. This is not yet implemented: our reasoning is that if you've authenticated successfully using e.g. the login form, why should you be logged out if you visit the same login form and enter wrong credentials?
  The pre-authenticated authenticators are an exception here, they do reset the token upon authentication failure, just like the old system.

• H) CSRF Generator Service ID No Longer Configurable
  The old Form login authentication provider allowed you to configure the CSRF generator service ID. This is no longer possible with the automated CSRF listener. This feature was introduced in the first CSRF commit and didn't get any updates ever since, so we don't think this feature is required. This could also be accomplished by checking CSRF manually in your authenticator, instead of using the automated check.

Future Considerations

• Remove Security sub-components: Move CSRF to Symfony\Component\Csrf (just like mime); Deprecated Guard; Put HTTP + Core as symfony/security. This means moving the new classes to Symfony\Component\Security

• Convert LDAP to the new system

• This is fixed (and merged) by [Security] Refactor logout listener to dispatch an event instead #36243 There is a need for some listeners to listen for events on one firewall, but not another (e.g. RememberMeListener). This is now fixed by checking the $providerKey. We thought it might be nice to introduce a feature to the event dispatcher:

  • Create one event dispatcher per firewall;
  • Extend the kernel.event_subscriber tag, so that you can optionally specify the dispatcher service ID (to allow listening on events for a specific dispatcher);
  • Add a listener that always also triggers the events on the main event dispatcher, in case you want a listener that is listening on all firewalls.

• Drop the AnonymousToken and AnonymousAuthenticator: Anonymous authentication has never made much sense and complicates things (e.g. the user can be a string). For access control, an anonymous user has the same meaning as an un-authenticated one (null). This require changes in the AccessListener and AuthorizationChecker and probably also a new Security attribute (to replace IS_AUTHENTICATED_ANONYMOUSLY). Related issues: [Security] deprecate non UserInterface users #34909, [Security][RFC] Exception thrown on call to isGranted without token #30609

How to test

1. Install the Symfony demo application (or any Symfony application)
2. Clone my Symfony fork (git clone git@github.com:wouterj/symfony) and checkout my branch (git checkout security/deprecate-providers-listeners)
3. Use the link utility to link my fork to the Symfony application: /path/to/symfony-fork/link /path/to/project
4. Enable the new system by setting security.enable_authenticator_manager to true

[Nyholm]

Just note:
A user should also be able to use the provider/listener/handler/factory implementation. I love Guard but sometimes it is not enough to work with my super special authentication.

I recently had a scenario where I get a user if passed with an authenticated jwt token. I should create a user entity if it missing (by using data in auth0), if email is valid I create an authenticated token, if not, I will ask the user to login (with different authenticator).

I was not able to write a nice solution with guard for this scenario, so I had to use the “low level code”.

I’m all for promoting guard and trying to make it better, but I think it would be use the more flexible solution when needed.

[Koc]

Good movement, but AFIK it is impossible to define custom config nodes with guards. Should we add method similar to addConfiguration(NodeDefinition $builder) inside GuardFactoryInterface like already done in SecurityFactoryInterface?

[wouterj]

I’m all for promoting guard and trying to make it better, but I think it would be use the more flexible solution when needed.

Hmm, interesting. Our assumption has always been that Guard is not less flexible than the current listener-provider solution. Guard only combines them into one class, which makes it more difficult to reuse partial systems (i.e. the DaoAuthenticationProvider).

I do not fully follow your requirements, but it would be interesting to see whether or not Guard (or a modification in Guard) could have fixed your requirements.

---

For now, I would say it doesn't matter as this PR is not about deprecating the old system. It's only introducing a new system next to it, to allow experimenting (and discovering exactly cases like you mentioned). For that reason, it's maybe a good idea to mark the new classes as @experimental (or do we only mark complete components as experimental?)

@fabpot @nicolas-grekas @weaverryan what should we do to get this into the next release (probably not 4.4, but 5.0?)

[wouterj]

Good movement, but AFIK it is impossible to define custom config nodes with guards. Should we add method similar to addConfiguration(NodeDefinition $builder) inside GuardFactoryInterface like already done in SecurityFactoryInterface?

In order to be usable a class should as of now implement both interfaces, so the addConfiguration() method is added by the other interface. For clarity, we can add the methods to the new interface as well.

[fabpot]

Making it experimental means that it cannot be part of 4.4. But it can be part of 5.0.

[fabpot]

Thank you @wouterj.

[wouterj]

Fyi, @noniagriconomie, I like your review and we've not forgotten your comments. However, we wanted to finally get this one in master, so I'll submit a PR fixing your comments later this day

[noniagriconomie]

@wouterj understood, good to have the security part upgraded :)