Missing documentation on custom credentials and badges

[michnovka]

I recently spent some time implementing custom authenticators and I think the available documentation is insufficient.

Let me describe a sample case with a login form which has

• TOTP token (which has TOTP secret saved on User entity)
• IP filter (with WhitelistedIP entity)
• captcha

I was doing it all wrong, I started with injecting the user repository, then user from username to get the TOTP code and valuating it. Same with whitelisted IPs. And then I would use $request session to compare captcha. All this was done first and if all checks passed, then I would create a new UserBadge($user->getUserIdentifier()). Otherwise Id throw from the authenticate().

This is more or less how it is hinted at https://symfony.com/doc/current/security/custom_authenticator.html

I believe we lack a whole section here which explains how custom badges (for Credentials or just other type of badges) can be created and how they should be checked with EventSubscriber for CheckPassportEvent

When searching online, the most relevant post i found was @wouterj 's https://wouterj.nl/2020/04/authenticators-new-symfony-security which is outdated and it says to use VerifyAuthenticatorCredentialsEvent (which is not exiting at least in Symfony 7)

There is some mention of the correct CheckPassportEvent in https://symfonycasts.com/screencast/symfony-security/security-subscriber (even though it is used without badges).

There is a single mention in official docs about

Dispatched after the authenticator created the [security passport](https://symfony.com/doc/current/security/custom_authenticator.html#security-passport). Listeners of this event do the actual authentication checks (like checking the passport, validating the CSRF token, etc.)

And then there is this blog post which links to that @wouterj 's blog that I posted above

I did not find anywhere any section on custom credentials/custom badges and I think it should be added