internal/functions/Get-GraphGroup.ps1


<#
    .SYNOPSIS
        Gets a security group from Azure AD / Entra ID.
 
    .DESCRIPTION
        Looks up one Entra ID security entry by ObjectId or display name. The Graph filter
        matches the start of the display name when the value is not an ObjectId.
 
    .PARAMETER Group
        ObjectId or display name of the Entra ID security group.
 
    .EXAMPLE
        PS C:\> Get-GraphGroup -Group "env-123"
 
        Retrieves the entry matching that object id or display name.
        It uses -Group to select the entry.
 
    .NOTES
        Author: Mötz Jensen (@Splaxi)
#>

function Get-GraphGroup {
    [CmdletBinding()]
    param (
        [Parameter(Mandatory = $true)]
        [ValidateNotNullOrEmpty()]
        [Alias('EntraGroup')]
        [string] $Group
    )

    end {
        $secureTokenGraph = Get-BapAccessToken -Graph
        $tokenGraphValue = ConvertFrom-SecureString -AsPlainText -SecureString $secureTokenGraph

        $headersGraphApi = @{
            "Authorization" = "Bearer $($tokenGraphValue)"
            "Content-Type"  = "application/json"
        }

        if (Test-Guid -InputObject $Group) {
            # Validate that the Security Group exists in Azure AD / Entra ID
            $uriGraph = "https://graph.microsoft.com/v1.0/groups?`$filter=id eq '$Group'"
        }
        else {
            $uriGraph = "https://graph.microsoft.com/v1.0/groups?`$filter=startswith(displayName, '$Group')"
        }

        $colGroups = Invoke-RestMethod -Method Get `
            -Uri $uriGraph `
            -Headers $headersGraphApi 4> $null | `
            Select-Object -ExpandProperty Value

        if ($colGroups.Count -eq 0) {
            $messageString = "The supplied ObjectId / Entra Group: <c='em'>$Group</c> didn't return any matching Security Group in Azure AD / Entra ID. Please verify that the ObjectId is correct - try running the <c='em'>Get-AzADGroup</c> cmdlet."
            Write-PSFMessage -Level Important -Message $messageString
            Stop-PSFFunction -Message "Stopping because Security Group was NOT found based on the ObjectId." -Exception $([System.Exception]::new($($messageString -replace '<[^>]+>', ''))) -StepsUpward 1
        }

        if ($colGroups.Count -gt 1) {
            $messageString = "The supplied ObjectId / Entra Group: <c='em'>$Group</c> returned multiple matching Security Groups in Azure AD / Entra ID. Please verify that the ObjectId is correct - try running the <c='em'>Get-AzADGroup</c> cmdlet."
            Write-PSFMessage -Level Important -Message $messageString
            Stop-PSFFunction -Message "Stopping because multiple Security Groups were found based on the ObjectId." -Exception $([System.Exception]::new($($messageString -replace '<[^>]+>', ''))) -StepsUpward 1
        }

        $colGroups[0]
    }
}