get_user_by_email can silently return wrong result when "allow multiple accounts with the same email address" is set

[kkom]

Describe your environment

• Operating System version: macOS 15.2
• Firebase SDK version: 6.6.0
• Firebase Product: auth
• Python version: 3.12
• Pip version: uv 0.5.11

Describe the problem

I'm worried that the get_user_by_email function misleadingly silently skips some results.

It's typed as returning a single user record given an email address:

firebase-admin-python/firebase_admin/_auth_client.py

Lines 179 to 194 in 8ba819a

	def get_user_by_email(self, email):
	"""Gets the user data corresponding to the specified user email.
	Args:
	email: A user email address string.
	Returns:
	UserRecord: A user record instance.
	Raises:
	ValueError: If the email is None, empty or malformed.
	UserNotFoundError: If no user exists for the specified email address.
	FirebaseError: If an error occurs while retrieving the user.
	"""
	response = self._user_manager.get_user(email=email)
	return _user_mgt.UserRecord(response)

However, it is possible to configure Firebase to allow multiple accounts with the same email address: https://support.google.com/firebase/answer/9134820

It looks like the implementation takes just the first user record if more than one matches the provided email:

firebase-admin-python/firebase_admin/_user_mgt.py

Lines 583 to 602 in 8ba819a

	def get_user(self, **kwargs):
	"""Gets the user data corresponding to the provided key."""
	if 'uid' in kwargs:
	key, key_type = kwargs.pop('uid'), 'user ID'
	payload = {'localId' : [_auth_utils.validate_uid(key, required=True)]}
	elif 'email' in kwargs:
	key, key_type = kwargs.pop('email'), 'email'
	payload = {'email' : [_auth_utils.validate_email(key, required=True)]}
	elif 'phone_number' in kwargs:
	key, key_type = kwargs.pop('phone_number'), 'phone number'
	payload = {'phoneNumber' : [_auth_utils.validate_phone(key, required=True)]}
	else:
	raise TypeError('Unsupported keyword arguments: {0}.'.format(kwargs))
	body, http_resp = self._make_request('post', '/accounts:lookup', json=payload)
	if not body or not body.get('users'):
	raise _auth_utils.UserNotFoundError(
	'No user record found for the provided {0}: {1}.'.format(key_type, key),
	http_response=http_resp)
	return body['users'][0]

I'd suggest replacing it with a get_users_by_email that returns a collections of records, to avoid misleading programmers unfamiliar with the "allow multiple accounts with the same email address" option.

[google-oss-bot]

I couldn't figure out how to label this issue, so I've labeled it for a human to triage. Hang tight.