Improve the documentation for custom authenticators by detailing the concept of user identifier normalization. Introduced theNormalizedUserBadge example to demonstrate how to simplify and standardize identifiers.

carsonbot added Status: Needs Review Security labels

Feb 7, 2025

carsonbot added this to the7.3 milestone

Feb 7, 2025

xabbuh reviewed

Feb 7, 2025

View reviewed changes

security/custom_authenticator.rst OutdatedShow resolvedHide resolved

Spomky force-pushed thefeatures/userid-normalizer branch fromb58b83b toa7df8a2Compare

February 7, 2025 21:35

alamirault reviewed

Mar 23, 2025

View reviewed changes

security/custom_authenticator.rstShow resolvedHide resolved

security/custom_authenticator.rst Outdated

Comment on lines 320 to 327

		.. note::

		Similarly, Google normalizes email addresses so that "john.doe", "j.hon.d.oe",
		and "johndoe" all correspond to the same account.
		This involves removing dots and converting the email address to lowercase
		(though normalization specifics depend on your use case).

Copy link

Contributor

alamiraultMar 23, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

With the other note below, I'm not sure this one is needed

Copy link

ContributorAuthor

SpomkyMay 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

I believe both notes provide valuable context and would prefer to keep tthem:

The first shows a well-known real-world example (Google).
The second one highlights enterprise-specific formats where normalization is important.

Spomky force-pushed thefeatures/userid-normalizer branch froma7df8a2 tobf84645Compare

May 8, 2025 11:50

Introduce user identifier normalization for enhanced consistency

ac6a258

Added support for normalizing user identifiers in Symfony 7.3 to ensure consistent comparison and storage. Updated documentation with implementation examples, highlighting best practices like converting identifiers to lowercase and handling various formats. This improvement reduces the risk of duplicates and improves reliability in user authentication.

Spomky force-pushed thefeatures/userid-normalizer branch frombf84645 toac6a258Compare

May 8, 2025 11:54

alamirault reviewed

May 9, 2025

View reviewed changes

security/custom_authenticator.rst

Comment on lines +278 to +322

		For instance, the example below uses a normalizer that converts usernames to a normalized, ASCII-only, lowercase format,
		suitable for consistent comparison and storage.

		// src/Security/NormalizedUserBadge.php
		namespace App\Security;

		use Symfony\Component\Security\Http\Authenticator\Passport\Badge\UserBadge;
		use Symfony\Component\String\UnicodeString;
		use function Symfony\Component\String\u;

		final class NormalizedUserBadge extends UserBadge
		{
		public function __construct(string $identifier)
		{
		$callback = static fn (string $identifier) => u($identifier)->normalize(UnicodeString::NFKC)->ascii()->lower()->toString();

		parent::__construct($identifier, null, $callback);
		}
		}

		// src/Security/PasswordAuthenticator.php
		namespace App\Security;

		final class PasswordAuthenticator extends AbstractLoginFormAuthenticator
		{
		// Simplified for brievety
		public function authenticate(Request $request): Passport
		{
		$username = (string) $request->request->get('username', '');
		$password = (string) $request->request->get('password', '');

		$request->getSession()
		->set(SecurityRequestAttributes::LAST_USERNAME, $username);

		return new Passport(
		new NormalizedUserBadge($username),
		new PasswordCredentials($password),
		[
		//All other useful badges
		]
		);
		}
		}

		.. note::

Copy link

Contributor

alamiraultMay 9, 2025•
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

Php code was not rendered. I added:: and.. code-block:: php (Not 100% sure it's the best way)
I replace(string) $request->request->get() by$request->request->getString

Suggested change

	For instance, the example below uses a normalizer that converts usernames to a normalized, ASCII-only, lowercase format,
	suitable for consistent comparison and storage.

	// src/Security/NormalizedUserBadge.php
	namespace App\Security;

	use Symfony\Component\Security\Http\Authenticator\Passport\Badge\UserBadge;
	use Symfony\Component\String\UnicodeString;
	use function Symfony\Component\String\u;

	final class NormalizedUserBadge extends UserBadge
	{
	public function __construct(string $identifier)
	{
	$callback = static fn (string $identifier) => u($identifier)->normalize(UnicodeString::NFKC)->ascii()->lower()->toString();

	parent::__construct($identifier, null, $callback);
	}
	}

	// src/Security/PasswordAuthenticator.php
	namespace App\Security;

	final class PasswordAuthenticator extends AbstractLoginFormAuthenticator
	{
	// Simplified for brievety
	public function authenticate(Request $request): Passport
	{
	$username = (string) $request->request->get('username', '');
	$password = (string) $request->request->get('password', '');

	$request->getSession()
	->set(SecurityRequestAttributes::LAST_USERNAME, $username);

	return new Passport(
	new NormalizedUserBadge($username),
	new PasswordCredentials($password),
	[
	//All other useful badges
	]
	);
	}
	}

	..note::
	For instance, the example below uses a normalizer that converts usernames to a normalized, ASCII-only, lowercase format,
	suitable for consistent comparison and storage::

	// src/Security/NormalizedUserBadge.php
	namespace App\Security;

	use Symfony\Component\Security\Http\Authenticator\Passport\Badge\UserBadge;
	use Symfony\Component\String\UnicodeString;
	use function Symfony\Component\String\u;

	final class NormalizedUserBadge extends UserBadge
	{
	public function __construct(string $identifier)
	{
	$callback = static fn (string $identifier) => u($identifier)->normalize(UnicodeString::NFKC)->ascii()->lower()->toString();

	parent::__construct($identifier, null, $callback);
	}
	}

	..code-block::php

	// src/Security/PasswordAuthenticator.php
	namespace App\Security;

	final class PasswordAuthenticator extends AbstractLoginFormAuthenticator
	{
	// Simplified for brievety
	public function authenticate(Request $request): Passport
	{
	$username = $request->request->getString('username');
	$password = $request->request->getString('password');

	$request->getSession()
	->set(SecurityRequestAttributes::LAST_USERNAME, $username);

	return new Passport(
	new NormalizedUserBadge($username),
	new PasswordCredentials($password),
	[
	//All other useful badges
	]
	);
	}
	}

	..note::