internal/functions/user/Resolve-UserLookupId.ps1

function Resolve-UserLookupId {
    <#
    .SYNOPSIS
        Resolves a user identity to the value read from users/{0}: object id, then userPrincipalName, then mail.

    .DESCRIPTION
        An object id is returned as it is. Anything else is looked up by userPrincipalName
        first and by mail only when no UPN matches; when neither matches, the identity
        itself is returned so the direct read reports the failure.

        The order matters: the mail lookup used to run first, and when user B's mail equals
        user A's userPrincipalName (a renamed account, a shared alias) a request for A
        returned B.

        Errors are not handled here: the caller runs this inside its protected command.

    .PARAMETER Identity
        Object id, userPrincipalName or mail of the user.

    .PARAMETER Service
        The Entra service to query.

    .EXAMPLE
        PS C:\> $userId = Resolve-UserLookupId -Identity 'john@contoso.com' -Service $service

        Returns the object id of the user whose UPN, or else whose mail, is john@contoso.com.
    #>

    [CmdletBinding()]
    [OutputType([string])]
    param (
        [Parameter(Mandatory = $true)]
        [string] $Identity,
        [Parameter(Mandatory = $true)]
        [string] $Service
    )

    if ($Identity -match '^(\{){0,1}[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}(\}){0,1}$') {
        return $Identity.Trim('{', '}')
    }
    foreach ($propertyName in 'userPrincipalName', 'mail') {
        [hashtable] $lookupQuery = @{
            '$select' = 'id'
            '$Filter' = ("{0} eq '{1}'" -f $propertyName, (ConvertTo-ODataFilterString -Value $Identity))
        }
        $match = @(Invoke-EntraRequest -Service $Service -Path 'users' -Query $lookupQuery -Method Get -ErrorAction Stop | Where-Object { $null -ne $_ -and -not [string]::IsNullOrWhiteSpace($_.id) })[0]
        if (-not [object]::Equals($match, $null)) {
            return [string] $match.id
        }
    }
    $Identity
}