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