internal/functions/Get-GraphUser.ps1
|
<# .SYNOPSIS Gets a user from Azure AD / Entra ID. .DESCRIPTION Looks up one Entra ID account by ObjectId, display name, principal name or mail. The Graph startswith filter matches the start of the display name, principal name or mail when the value is not an ObjectId. .PARAMETER User ObjectId, display name, principal name or mail of the Entra ID account. .EXAMPLE PS C:\> Get-GraphUser -User "john@contoso.com" Retrieves the account matching that object id, name, principal name or mail. It uses -User to select the account. .NOTES Author: Mötz Jensen (@Splaxi) #> function Get-GraphUser { [CmdletBinding()] param ( [Parameter(Mandatory = $true)] [ValidateNotNullOrEmpty()] [Alias('EntraUser')] [string] $User ) end { $secureTokenGraph = Get-BapAccessToken -Graph $tokenGraphValue = ConvertFrom-SecureString -AsPlainText -SecureString $secureTokenGraph $headersGraphApi = @{ "Authorization" = "Bearer $($tokenGraphValue)" "Content-Type" = "application/json" } if (Test-Guid -InputObject $User) { # Validate that the user exists in Azure AD / Entra ID $uriGraph = "https://graph.microsoft.com/v1.0/users?`$filter=id eq '$User'" } else { $uriGraph = "https://graph.microsoft.com/v1.0/users?`$filter=startswith(displayName, '$User') or startswith(userPrincipalName, '$User') or startswith(mail, '$User')" } $colUsers = @(Invoke-RestMethod -Method Get ` -Uri $uriGraph ` -Headers $headersGraphApi 4> $null | ` Select-Object -ExpandProperty Value) if ($colUsers.Count -eq 0) { $messageString = "The supplied ObjectId / Entra User: <c='em'>$User</c> didn't return any matching User in Azure AD / Entra ID. Please verify that the ObjectId is correct - try running the <c='em'>Get-AzADUser</c> cmdlet." Write-PSFMessage -Level Important -Message $messageString Stop-PSFFunction -Message "Stopping because User was NOT found based on the ObjectId." -Exception $([System.Exception]::new($($messageString -replace '<[^>]+>', ''))) -StepsUpward 1 } if ($colUsers.Count -gt 1) { $messageString = "The supplied ObjectId / Entra User: <c='em'>$User</c> returned multiple matching Users in Azure AD / Entra ID. Please verify that the ObjectId is correct - try running the <c='em'>Get-AzADUser</c> cmdlet." Write-PSFMessage -Level Important -Message $messageString Stop-PSFFunction -Message "Stopping because multiple Users were found based on the ObjectId." -Exception $([System.Exception]::new($($messageString -replace '<[^>]+>', ''))) -StepsUpward 1 } $colUsers[0] } } |