EntraAuth.Graph.Application.psm1
|
function ConvertFrom-Application { <# .SYNOPSIS Converts raw App Registration objects from the Graph API to a more user-friendly format. .DESCRIPTION Converts raw App Registration objects from the Graph API to a more user-friendly format. .PARAMETER InputObject The raw App Registration object to convert. .PARAMETER Raw Actually, don't convert the object after all. .EXAMPLE PS C:\> Invoke-EntraRequest -Path "applications/$ObjectId" | ConvertFrom-Application Converts the raw App Registration object to a more user-friendly format. #> [CmdletBinding()] param ( [Parameter(ValueFromPipeline = $true)] $InputObject, [switch] $Raw ) begin { $scopeTypeMap = @{ $true = 'Delegated' $false = 'Application' } } process { if ($Raw) { return $InputObject } $scopes = foreach ($resource in $InputObject.requiredResourceAccess) { foreach ($access in $resource.resourceAccess) { [PSCustomObject]@{ PSTypeName = 'EntraAuth.Graph.Scope' ApplicationId = $InputObject.appId ApplicationName = $InputObject.DisplayName Resource = $resource.resourceAppId ResourceName = $script:cache.ServicePrincipalByAppID."$($resource.resourceAppId)".displayName Type = $scopeTypeMap[($access.type -eq 'Scope')] Scope = $access.id ScopeName = $script:cache.ScopesByID."$($access.id)".value ConsentRequired = $null HasConsent = $null PrincipalName = $null PrincipalID = $null } } } [PSCustomObject]@{ PSTypeName = 'EntraAuth.Graph.Application' Id = $InputObject.id AppID = $InputObject.AppID DisplayName = $InputObject.DisplayName Scopes = $scopes Object = $InputObject } } } function Invoke-TerminatingException { <# .SYNOPSIS Throw a terminating exception in the context of the caller. .DESCRIPTION Throw a terminating exception in the context of the caller. Masks the actual code location from the end user in how the message will be displayed. .PARAMETER Cmdlet The $PSCmdlet variable of the calling command. .PARAMETER Message The message to show the user. .PARAMETER Exception A nested exception to include in the exception object. .PARAMETER Category The category of the error. .PARAMETER ErrorRecord A full error record that was caught by the caller. Use this when you want to rethrow an existing error. .EXAMPLE PS C:\> Invoke-TerminatingException -Cmdlet $PSCmdlet -Message 'Unknown calling module' Terminates the calling command, citing an unknown caller. #> [CmdletBinding()] Param ( [Parameter(Mandatory = $true)] $Cmdlet, [string] $Message, [System.Exception] $Exception, [System.Management.Automation.ErrorCategory] $Category = [System.Management.Automation.ErrorCategory]::NotSpecified, [System.Management.Automation.ErrorRecord] $ErrorRecord ) process { if ($ErrorRecord -and -not $Message) { $Cmdlet.ThrowTerminatingError($ErrorRecord) } $exceptionType = switch ($Category) { default { [System.Exception] } 'InvalidArgument' { [System.ArgumentException] } 'InvalidData' { [System.IO.InvalidDataException] } 'AuthenticationError' { [System.Security.Authentication.AuthenticationException] } 'InvalidOperation' { [System.InvalidOperationException] } } if ($Exception) { try { $newException = $Exception.GetType()::new($Message, $Exception) } catch { $newException = [System.Exception]::new($Message, $Exception) } } elseif ($ErrorRecord) { try { $newException = $ErrorRecord.Exception.GetType()::new($Message, $ErrorRecord.Exception) } catch { $newException = [System.Exception]::new($Message, $Exception) } } else { $newException = $exceptionType::new($Message) } $record = [System.Management.Automation.ErrorRecord]::new($newException, (Get-PSCallStack)[1].FunctionName, $Category, $Target) $Cmdlet.ThrowTerminatingError($record) } } function Resolve-Application { <# .SYNOPSIS Returns the App Registration object identified by the provided identifier. .DESCRIPTION Returns the App Registration object identified by the provided identifier. This is an internal extension of the Get-EAGAppRegistration command, enabling caching of results for repeated resolutions of the same identifiers during a single instance of the calling command. Hence this helper can be called repeatedly from the same caller and it will resolve the same App Registration only once. This command always returns an obbject with the following properties: - Success: A boolean indicating if the resolution was successful. - Result: The resolved App Registration object(s). - Message: A message indicating the result of the resolution. The caller is responsible for handling error cases. Scopes Needed: Application.Read.All .PARAMETER DisplayName DisplayName of the App Registration to resolve. .PARAMETER ApplicationId ApplicationId (ClientID) of the App Registration to resolve. .PARAMETER ObjectId ObjectId of the App Registration to resolve. .PARAMETER Cache A hashtable used as cache for resolved App Registrations. The content of that hashtable will be updated by the results of this command. Provide it repeatedly to new calls to this command to avoid repeated resolutions. .PARAMETER Unique Whether ambiguous results should be considered an error. .PARAMETER Services A hashtable mapping which EntraAuth service should be called for Graph requests. Example: @{ Graph = 'GraphBeta' } Generally, this parameter should receive a passed through -ServiceMap parameter from a public command. .EXAMPLE PS C:\> Resolve-Application -DisplayName "MyWebApp" -Unique Resolves the App Registration with the display name "MyWebApp", will fail if multiple apps with that name exist. #> [CmdletBinding()] param ( [AllowEmptyString()] [AllowNull()] [string] $DisplayName, [Alias('AppId', 'ClientID')] [AllowEmptyString()] [AllowNull()] [string] $ApplicationId, [Alias('Id')] [AllowEmptyString()] [AllowNull()] [string] $ObjectId, [hashtable] $Cache = @{ }, [switch] $Unique, [hashtable] $Services = @{} ) process { $appIdentifier = "$($DisplayName)|$($ApplicationId)|$($ObjectId)" $result = [PSCustomObject]@{ Success = $false Result = $null Message = '' } if ($Cache.Keys -contains $appIdentifier) { $result.Result = $Cache[$appIdentifier] } else { $param = @{ ServiceMap = $Services } if ($DisplayName) { $param.DisplayName = $DisplayName } if ($ApplicationId) { $param.ApplicationId = $ApplicationId } if ($ObjectId) { $param.ObjectId = $ObjectId } $result.Result = Get-EAGAppRegistration @param $Cache[$appIdentifier] = $result.Result } if (-not $result.Result) { $result.Message = "No application found! (Name: $DisplayName | AppID: $ApplicationId | ID: $ObjectId)" return $result } if ($result.Result.Count -gt 1 -and $Unique) { $names = @($result.Result).ForEach{ '+ {0} (Created: {1:yyyy-MM-dd} | ID: {2} | AppID: {3})' -f $_.DisplayName, $_.Object.createdDateTime, $_.Id, $_.AppID } $result.Message = "Ambiguous Application: More than one App Registration was found to add Scopes to:`n$($names -join "`n")`nPlease provide a unique identifier and try again." return $result } $result.Success = $true $result } } function Resolve-Scope { <# .SYNOPSIS Resolves scopes, from either name or ID, into a standardized object. .DESCRIPTION Resolves scopes, from either name or ID, into a standardized object. These scopes are cached for performance reasons. Scope Needed: Application.Read.All .PARAMETER Scope Name or ID of the scope to resolve. .PARAMETER Resource The resource (API) to which the permissions/scopes apply. This can be specified as a display name, application ID, object ID or Service Principal Name. Examples: + 'Microsoft Graph' + '00000003-0000-0000-c000-000000000000' + 'https://graph.microsoft.com' .PARAMETER Type Type of the scope to resolve. Valid Options: - Delegated: Permissions that apply to interactive sessions, where the application acts on behalf of the signed-in user. - Application: Permissions that apply to unattended sessions, where the application acts as itself. .PARAMETER Services A hashtable mapping which EntraAuth service should be called for Graph requests. Example: @{ Graph = 'GraphBeta' } Generally, this parameter should receive a passed through -ServiceMap parameter from a public command. .EXAMPLE PS C:\> Resolve-Scope -Scope "User.Read.All" -Resource "Microsoft Graph" -Type Application Resolves the User.Read.All application permission for Microsoft Graph. #> [CmdletBinding()] param ( [string] $Scope, [string] $Resource, [ValidateSet('Delegated', 'Application')] [string] $Type, [hashtable] $Services = @{} ) process { $identity = "$Scope|$Resource|$Type" if ($script:cache.ResolvedScopes[$identity]) { return $script:cache.ResolvedScopes[$identity] } $filter = "serviceprincipalNames/any(x:x eq '$Resource')" if ($Resource -as [Guid]) { $filter = "id eq '$Resource' or appId eq '$Resource' or serviceprincipalNames/any(x:x eq '$Resource')" } $servicePrincipal = Get-EAGServicePrincipal -ServiceMap $Services -Filter $filter if (-not $servicePrincipal) { $script:cache.ResolvedScopes[$identity] = [PSCustomObject]@{ ID = '00000000-0000-0000-0000-000000000000' Value = '<not identified>' ConsentRequired = $null Resource = '00000000-0000-0000-0000-000000000000' ResourceName = 'Unknown' Type = 'Unknown' } return $script:cache.ResolvedScopes[$identity] } if ($servicePrincipal.Count -gt 1) { if ($servicePrincipal | Where-Object Id -EQ $Resource) { $servicePrincipal = $servicePrincipal | Where-Object Id -EQ $Resource } elseif ($servicePrincipal | Where-Object AppId -EQ $Resource) { $servicePrincipal = $servicePrincipal | Where-Object AppId -EQ $Resource } else { $servicePrincipal = $servicePrincipal | Select-Object -First 1 } } foreach ($scopeEntry in $servicePrincipal.Scopes.Delegated) { $entry = [PSCustomObject]@{ ID = $scopeEntry.id Value = $scopeEntry.value ConsentRequired = $scopeEntry.type -eq 'Admin' Resource = $servicePrincipal.Id ResourceName = $servicePrincipal.DisplayName Type = 'Delegated' } $script:cache.ResolvedScopes["$($entry.ID)|$Resource|Delegated"] = $entry $script:cache.ResolvedScopes["$($entry.Value)|$Resource|Delegated"] = $entry $script:cache.ResolvedScopes["$($entry.ID)|$($servicePrincipal.Id)|Delegated"] = $entry $script:cache.ResolvedScopes["$($entry.Value)|$($servicePrincipal.Id)|Delegated"] = $entry $script:cache.ResolvedScopes["$($entry.ID)|$($servicePrincipal.AppId)|Delegated"] = $entry $script:cache.ResolvedScopes["$($entry.Value)|$($servicePrincipal.AppId)|Delegated"] = $entry } foreach ($scopeEntry in $servicePrincipal.Scopes.Application) { $entry = [PSCustomObject]@{ ID = $scopeEntry.id Value = $scopeEntry.value ConsentRequired = $true Resource = $servicePrincipal.Id ResourceName = $servicePrincipal.DisplayName Type = 'Application' } $script:cache.ResolvedScopes["$($entry.ID)|$Resource|Application"] = $entry $script:cache.ResolvedScopes["$($entry.Value)|$Resource|Application"] = $entry $script:cache.ResolvedScopes["$($entry.ID)|$($servicePrincipal.Id)|Application"] = $entry $script:cache.ResolvedScopes["$($entry.Value)|$($servicePrincipal.Id)|Application"] = $entry $script:cache.ResolvedScopes["$($entry.ID)|$($servicePrincipal.AppId)|Application"] = $entry $script:cache.ResolvedScopes["$($entry.Value)|$($servicePrincipal.AppId)|Application"] = $entry } if ($script:cache.ResolvedScopes[$identity]) { return $script:cache.ResolvedScopes[$identity] } # Case: Scope not found $script:cache.ResolvedScopes[$identity] = [PSCustomObject]@{ ID = '00000000-0000-0000-0000-000000000000' Value = '<not identified>' ConsentRequired = $null Resource = '00000000-0000-0000-0000-000000000000' ResourceName = 'Unknown' Type = 'Unknown' } return $script:cache.ResolvedScopes[$identity] } } function Resolve-ScopePrincipal { <# .SYNOPSIS Resolves the identity of a user that consented to a scope. .DESCRIPTION Resolves the identity of a user that consented to a scope. These identities are cached for performance reasons. Scopes Needed: User.ReadBasic.All (Delegated), User.Read.All (Application) .PARAMETER ID The ObjectID of the user to resolve. .PARAMETER Services A hashtable mapping which EntraAuth service should be called for Graph requests. Example: @{ Graph = 'GraphBeta' } Generally, this parameter should receive a passed through -ServiceMap parameter from a public command. .EXAMPLE PS C:\> Resolve-ScopePrincipal -ID "11111111-1111-1111-1111-111111111111" Resolves the user with the ObjectID "11111111-1111-1111-1111-111111111111". #> [CmdletBinding()] param ( [AllowNull()] [string] $ID, [hashtable] $Services = @{} ) process { if (-not $ID) { [PSCustomObject]@{ Name = '' ID = '' } return } if ($script:cache.Principals[$ID]) { return $script:cache.Principals[$ID] } try { $user = Invoke-EntraRequest -Service $Services.Graph -Path "users/$ID" -Query @{ '$select' = 'id', 'displayName' } -WarningAction SilentlyContinue -ErrorAction Stop $script:cache.Principals[$ID] = [PSCustomObject]@{ Name = $user.displayName ID = $user.id } } catch { $script:cache.Principals[$ID] = [PSCustomObject]@{ Name = '' ID = $ID } } $script:cache.Principals[$ID] } } function Resolve-ServicePrincipal { <# .SYNOPSIS Resolves Service Principals, based on an identifiable property. .DESCRIPTION Resolves Service Principals, based on an identifiable property. These Service Principals are cached for performance reasons. Valid identifiers: - DisplayName - Client ID (App ID) - Object ID - Service Principal Name This command always returns an obbject with the following properties: - Success: A boolean indicating if the resolution was successful. - Result: The resolved App Registration object(s). - Message: A message indicating the result of the resolution. The caller is responsible for handling error cases. Scopes Needed: Application.Read.All .PARAMETER Identity The identifier of the Service Principal to resolve. Valid identifiers: - DisplayName - Client ID (App ID) - Object ID - Service Principal Name .PARAMETER Properties Specific properties to retrieve from the Service Principal objects. Will always include 'id', 'appid', 'displayName', and 'servicePrincipalNames', no matter what is specified. .PARAMETER Cache A hashtable used as cache for resolved Service Principals. The content of that hashtable will be updated by the results of this command. Provide it repeatedly to new calls to this command to avoid repeated resolutions. .PARAMETER Unique Whether ambiguous results should be considered an error. .PARAMETER Services A hashtable mapping which EntraAuth service should be called for Graph requests. Example: @{ Graph = 'GraphBeta' } Generally, this parameter should receive a passed through -ServiceMap parameter from a public command. .EXAMPLE PS C:\> Resolve-ServicePrincipal -Identity "Microsoft Graph" -Cache $spns Resolves the Service Principal with the display name "Microsoft Graph". .EXAMPLE PS C:\> Resolve-ServicePrincipal -Identity "https://graph.microsoft.com" -Cache $spns Resolves the Service Principal with the specified Service Principal Name. #> [CmdletBinding()] param ( [string] $Identity, [string[]] $Properties = @('id', 'appid', 'displayName', 'servicePrincipalType', 'servicePrincipalNames', 'appRoles', 'oauth2PermissionScopes', 'resourceSpecificApplicationPermissions'), [hashtable] $Cache = @{}, [switch] $Unique, [hashtable] $Services = @{} ) process { if ($Properties -notcontains 'id') { $Properties = @($Properties) + 'id' } if ($Properties -notcontains 'appid') { $Properties = @($Properties) + 'appid' } if ($Properties -notcontains 'displayName') { $Properties = @($Properties) + 'displayName' } if ($Properties -notcontains 'servicePrincipalNames') { $Properties = @($Properties) + 'servicePrincipalNames' } $result = [PSCustomObject]@{ Success = $false Result = $null Message = '' } if ($cache.Keys -contains $Identity) { $result.Result = $cache[$Identity] } else { $filter = "serviceprincipalNames/any(x:x eq '$Identity') or displayName eq '$Identity'" if ($Identity -as [guid]) { $filter = "id eq '$Identity' or appId eq '$Identity' or serviceprincipalNames/any(x:x eq '$Identity') or displayName eq '$Identity'" } $result.Result = Get-EAGServicePrincipal -Filter $filter -Properties $Properties -ServiceMap $services # De-Ambiguate to unique identifiers in case of multiple results if ($result.Result.Count -gt 1) { if ($result.Result.id -contains $Identity) { $result.Result = $result.Result | Where-Object id -EQ $Identity } elseif ($result.Result.appId -contains $Identity) { $result.Result = $result.Result | Where-Object appId -EQ $Identity } elseif ($result.Result.servicePrincipalNames -contains $Identity) { $result.Result = $result.Result | Where-Object servicePrincipalNames -Contains $Identity } } $cache[$Identity] = $result.Result } if (-not $result.Result) { $result.Message = "Resource not found: $Identity" return $result } if ($servicePrincipal.Count -gt 1 -and $Unique) { $names = @($servicePrincipal).ForEach{ '+ {0} (ID: {1} | AppID: {2})' -f $_.DisplayName, $_.Id, $_.AppID } $result.Message = "Ambiguous Resource: More than one Service Principal was found for the specified name:`n$($names -join "`n")`nPlease provide a unique identifier and try again." return $result } $result.Success = $true $result } } function Add-EAGAppScope { <# .SYNOPSIS Adds API permissions (scopes) to an app registration. .DESCRIPTION Adds API permissions (scopes) to an app registration. This allows the app to access specific APIs with the granted permissions, once consent has been granted,. Scopes Needed: Application.Read.All, AppRoleAssignment.ReadWrite.All .PARAMETER DisplayName Display name of the app registration to add scopes to. .PARAMETER ApplicationId Application ID (Client ID) of the app registration to add scopes to. .PARAMETER ObjectId Object ID of the app registration to add scopes to. .PARAMETER Scope Permission scopes to add to the app registration. .PARAMETER Type Type of the permission scopes to add. Valid Options: - Delegated: Permissions that apply to interactive sessions, where the application acts on behalf of the signed-in user. - Application: Permissions that apply to unattended sessions, where the application acts as itself. .PARAMETER Resource The resource (API) to which the permissions/scopes apply. This can be specified as a display name, application ID, object ID or Service Principal Name. Examples: + 'Microsoft Graph' + '00000003-0000-0000-c000-000000000000' + 'https://graph.microsoft.com' .PARAMETER Consent Indicates whether to automatically grant consent for the added scopes. .PARAMETER ServiceMap Optional hashtable to map service names to specific EntraAuth service instances. Used for advanced scenarios where you want to use something other than the default Graph connection. Example: @{ Graph = 'GraphBeta' } This will switch all Graph API calls to use the beta Graph API. .PARAMETER WhatIf If this switch is enabled, no actions are performed but informational messages will be displayed that explain what would happen if the command were to run. .PARAMETER Confirm If this switch is enabled, you will be prompted for confirmation before executing any operations that change state. .EXAMPLE PS C:\> Add-EAGAppScope -DisplayName "MyWebApp" -Resource "Microsoft Graph" -Scope "User.Read.All" -Type Application Adds the User.Read.All application permission for Microsoft Graph to the app registration named "MyWebApp". #> [CmdletBinding(SupportsShouldProcess = $true, DefaultParameterSetName = 'Filter')] param ( [Parameter(ParameterSetName = 'Filter', ValueFromPipelineByPropertyName = $true)] [string] $DisplayName, [Parameter(ParameterSetName = 'Filter', ValueFromPipelineByPropertyName = $true)] [Alias('AppId', 'ClientID')] [string] $ApplicationId, [Parameter(Mandatory = $true, ParameterSetName = 'Identity', ValueFromPipelineByPropertyName = $true)] [Alias('Id')] [string] $ObjectId, [Parameter(Mandatory = $true)] [string[]] $Scope, [Parameter(Mandatory = $true)] [ValidateSet('Delegated','Application')] [string] $Type, [Parameter(Mandatory = $true)] [string] $Resource, [switch] $Consent, [hashtable] $ServiceMap ) begin { $services = $script:serviceSelector.GetServiceMap($ServiceMap) Assert-EntraConnection -Service $services.Graph -Cmdlet $PSCmdlet $filter = "serviceprincipalNames/any(x:x eq '$Resource') or displayName eq '$Resource'" if ($Resource -as [guid]) { $filter = "id eq '$Resource' or appId eq '$Resource' or serviceprincipalNames/any(x:x eq '$Resource') or displayName eq '$Resource'" } $servicePrincipal = Get-EAGServicePrincipal -Filter $filter -Properties id, appid, displayName, servicePrincipalType, appRoles, oauth2PermissionScopes, resourceSpecificApplicationPermissions -ServiceMap $ServiceMap if (-not $servicePrincipal) { Invoke-TerminatingException -Cmdlet $PSCmdlet -Message "Resource not found: $Resource" -Category ObjectNotFound } if ($servicePrincipal.Count -gt 1) { $names = @($servicePrincipal).ForEach{ '+ {0} (ID: {1} | AppID: {2})' -f $_.DisplayName, $_.Id, $_.AppID } Invoke-TerminatingException -Cmdlet $PSCmdlet -Message "Ambiguous Resource: More than one Service Principal was found for the specified name:`n$($names -join "`n")`nPlease provide a unique identifier and try again." -Category LimitsExceeded } $resolvedScopes = foreach ($entry in $Scope) { $scopeEntry = Resolve-Scope -Scope $entry -Resource $servicePrincipal.ID -Type $Type -Services $services if ($scopeEntry.ScopeName -eq '<not identified>') { Write-Error "Scope $entry of type $Type not found on Service Principal $($servicePrincipal.DisplayName) ($($servicePrincipal.ID) | $Resource)" continue } $scopeEntry } if (-not $resolvedScopes) { Invoke-TerminatingException -Cmdlet $PSCmdlet -Message "No valid scopes found! Use 'Get-EAGScopeDefinition' to find the valid scopes for the resource and try again." } } process { #region Resolve Application Data # Note: Can't cache, since previous process blocks might have affected the same object $result = Resolve-Application -DisplayName $DisplayName -ApplicationId $ApplicationId -ObjectId $ObjectId -Unique -Services $services if (-not $result.Success) { Write-Error $result.Message return } $application = $result.Result #endregion Resolve Application Data $body = @{ requiredResourceAccess = @() } $newAccess = [PSCustomObject]@{ resourceAppId = $servicePrincipal.AppId resourceAccess = @() } foreach ($access in $application.object.requiredResourceAccess) { if ($access.resourceAppId -ne $servicePrincipal.AppId) { $body.requiredResourceAccess += $access continue } foreach ($entry in $access.resourceAccess) { $newAccess.resourceAccess += $entry } } foreach ($scopeEntry in $resolvedScopes) { if ($newAccess.resourceAccess.id -contains $scopeEntry.ID) { continue } $accessEntry = [PSCustomObject]@{ id = $scopeEntry.ID type = 'Scope' } if ($scopeEntry.Type -ne 'Delegated') { $accessEntry.type = 'Role' } $newAccess.resourceAccess += $accessEntry } $body.requiredResourceAccess += $newAccess Write-Verbose ($body | ConvertTo-Json -Depth 99) if (-not $PSCmdlet.ShouldProcess($application.Id, "Adding scopes $($resolvedScopes.Value -join ', ')")) { return } try { $null = Invoke-EntraRequest -Method PATCH -Path "applications/$($application.Id)" -Body $body -Header @{ 'content-type' = 'application/json' } } catch { $PSCmdlet.WriteError($_) return } if (-not $Consent) { return } Grant-EAGScopeConsent -ApplicationID $application.AppID -Scope $Scope -Type $Type -Resource $Resource } } function Add-EAGMsiScope { <# .SYNOPSIS Adds API permissions (scopes) to a Managed Service Identity. .DESCRIPTION The Add-EAGMsiScope cmdlet adds application permissions (scopes) to a Managed Service Identity (MSI). This allows the MSI to access specific APIs with the granted permissions. Scopes Needed: Application.Read.All, AppRoleAssignment.ReadWrite.All .PARAMETER DisplayName The display name of the Managed Service Identity to add permissions to. .PARAMETER ApplicationId The Application ID (Client ID) of the Managed Service Identity to add permissions to. .PARAMETER ObjectId The Object ID of the Managed Service Identity to add permissions to. .PARAMETER Scope The permission scopes to add to the Managed Service Identity. These are the API permissions that will be granted. .PARAMETER Resource The resource (API) to which the permissions/scopes apply. This can be specified as a display name, application ID, object ID or Service Principal Name. Examples: + 'Microsoft Graph' + '00000003-0000-0000-c000-000000000000' + 'https://graph.microsoft.com' .PARAMETER ServiceMap %SERVCICEMAP% .PARAMETER WhatIf If this switch is enabled, no actions are performed but informational messages will be displayed that explain what would happen if the command were to run. .PARAMETER Confirm If this switch is enabled, you will be prompted for confirmation before executing any operations that change state. .EXAMPLE PS C:\> Add-EAGMsiScope -DisplayName "MyWebApp" -Resource "Microsoft Graph" -Scope "User.Read.All" Adds the User.Read.All application permission for Microsoft Graph to the MSI named "MyWebApp". .EXAMPLE PS C:\> Add-EAGMsiScope -ApplicationId "11111111-1111-1111-1111-111111111111" -Resource "00000003-0000-0000-c000-000000000000" -Scope "User.Read.All", "Group.Read.All" Adds the User.Read.All and Group.Read.All application permissions for Microsoft Graph (identified by its app ID) to the MSI with the specified application ID. #> [CmdletBinding(DefaultParameterSetName = 'Filter', SupportsShouldProcess = $true)] param ( [Parameter(ParameterSetName = 'Filter', ValueFromPipelineByPropertyName = $true)] [string] $DisplayName, [Parameter(ParameterSetName = 'Filter', ValueFromPipelineByPropertyName = $true)] [Alias('AppId', 'ClientID')] [string] $ApplicationId, [Parameter(Mandatory = $true, ParameterSetName = 'Identity', ValueFromPipelineByPropertyName = $true)] [Alias('Id')] [string] $ObjectId, [Parameter(Mandatory = $true)] [string[]] $Scope, [Parameter(Mandatory = $true)] [string] $Resource, [hashtable] $ServiceMap ) begin { $services = $script:serviceSelector.GetServiceMap($ServiceMap) Assert-EntraConnection -Service $services.Graph -Cmdlet $PSCmdlet $filter = "serviceprincipalNames/any(x:x eq '$Resource') or displayName eq '$Resource'" if ($Resource -as [guid]) { $filter = "id eq '$Resource' or appId eq '$Resource' or serviceprincipalNames/any(x:x eq '$Resource') or displayName eq '$Resource'" } $servicePrincipal = Get-EAGServicePrincipal -Filter $filter -Properties id, appid, displayName, servicePrincipalType, appRoles, oauth2PermissionScopes, resourceSpecificApplicationPermissions -ServiceMap $ServiceMap if (-not $servicePrincipal) { Invoke-TerminatingException -Cmdlet $PSCmdlet -Message "Resource not found: $Resource" -Category ObjectNotFound } if ($servicePrincipal.Count -gt 1) { $names = @($servicePrincipal).ForEach{ '+ {0} (ID: {1} | AppID: {2})' -f $_.DisplayName, $_.Id, $_.AppID } Invoke-TerminatingException -Cmdlet $PSCmdlet -Message "Ambiguous Resource: More than one Service Principal was found for the specified name:`n$($names -join "`n")`nPlease provide a unique identifier and try again." -Category LimitsExceeded } $resolvedScopes = foreach ($entry in $Scope) { $scopeEntry = Resolve-Scope -Scope $entry -Resource $servicePrincipal.ID -Type 'Application' -Services $services if ($scopeEntry.ScopeName -eq '<not identified>') { Write-Error "Scope $entry of type $Type not found on Service Principal $($servicePrincipal.DisplayName) ($($servicePrincipal.ID) | $Resource)" continue } $scopeEntry } if (-not $resolvedScopes) { Invoke-TerminatingException -Cmdlet $PSCmdlet -Message "No valid scopes found! Use 'Get-EAGScopeDefinition' to find the valid scopes for the resource and try again." } $servicePrincipals = @{} } process { #region Resolve Application Data $identity = $ObjectId if (-not $identity) { $identity = $ApplicationId } if (-not $identity) { $identity = $DisplayName } if (-not $identity) { Write-Error -Message "Managed Identity not specified! Provide at least one of ObjectId, ApplicationId or DisplayName." return } $result = Resolve-ServicePrincipal -Identity $identity -Properties id, appId, displayName -Cache $servicePrincipals -Unique -Services $services if (-not $result.Success) { Write-Error "Error resolving Managed Identity for $($identity):`n$($result.Message)" return } $appSPN = $result.Result #endregion Resolve Application Data $applicationGrants = Invoke-EntraRequest -Service $services.Graph -Path "servicePrincipals/$($appSPN.id)/appRoleAssignments" foreach ($resolvedScope in $resolvedScopes) { if ($resolvedScope.ID -in $applicationGrants.appRoleId) { Write-Verbose "Skipping Application scope $($resolvedScope.Value) - already added to $($appSPN.DisplayName)" continue } if (-not $PSCmdlet.ShouldProcess("$($appSPN.DisplayName) ($($appSPN.AppID))", "Grant consent for scope $($resolvedScope.Value) of resource $($resolvedScope.ResourceName)")) { continue } Write-Verbose "Processing scope:`n$($resolvedScope | ConvertTo-Json)" $grant = @{ "principalId" = $appSPN.id "resourceId" = $resolvedScope.Resource "appRoleId" = $resolvedScope.ID } Write-Verbose "Adding scope $($resolvedScope.id) ($($resolvedScope.Value))) to Managed Identity $($appSPN.appid) ($($appSPN.displayName))" try { $null = Invoke-EntraRequest -Method POST -Path "servicePrincipals/$($appSPN.id)/appRoleAssignments" -Body $grant -Header @{ 'content-type' = 'application/json' } } catch { Write-Error $_ } } } } function Get-EAGAppRegistration { <# .SYNOPSIS Lists application registrations in the connected Entra ID tenant. .DESCRIPTION Lists application registrations in the connected Entra ID tenant. You can filter the results by display name, application ID, or custom filter. Scopes Needed: Application.Read.All .PARAMETER DisplayName Display name of the app registration to retrieve. .PARAMETER ObjectId Object ID of the app registration to retrieve. .PARAMETER ApplicationId Application ID (Client ID) of the app registration to retrieve. .PARAMETER Filter Additional OData filter expression to apply when searching for app registrations. .PARAMETER Properties Specific properties to retrieve from the app registration objects. .PARAMETER Raw When specified, returns the raw API response objects instead of the formatted PowerShell objects. Useful for accessing detailed properties not exposed at the top level, but less user-friendly. .PARAMETER ServiceMap Optional hashtable to map service names to specific EntraAuth service instances. Used for advanced scenarios where you want to use something other than the default Graph connection. Example: @{ Graph = 'GraphBeta' } This will switch all Graph API calls to use the beta Graph API. .EXAMPLE PS C:\> Get-EAGAppRegistration Retrieves all app registrations in the Entra ID tenant. .EXAMPLE PS C:\> Get-EAGAppRegistration -DisplayName "MyWebApp" Retrieves the app registration with the display name "MyWebApp". .EXAMPLE PS C:\> Get-EAGAppRegistration -DisplayName 'Dept-*' -Properties 'displayName', 'appId' Retrieves all app registrations that start with "Dept-" and returns only the display name and app ID properties. #> [CmdletBinding()] param ( [Parameter(ParameterSetName = 'Filter')] [string] $DisplayName, [Parameter(Mandatory = $true, ParameterSetName = 'Identity')] [Alias('Id')] [string] $ObjectId, [Parameter(ParameterSetName = 'Filter', ValueFromPipelineByPropertyName = $true)] [Alias('AppId', 'ClientID')] [string] $ApplicationId, [Parameter(ParameterSetName = 'Filter', ValueFromPipelineByPropertyName = $true)] [string] $Filter, [string[]] $Properties, [switch] $Raw, [hashtable] $ServiceMap = @{} ) begin { $services = $script:serviceSelector.GetServiceMap($ServiceMap) Assert-EntraConnection -Service $services.Graph -Cmdlet $PSCmdlet } process { $query = @{ } if ($Properties) { $query['$select'] = $Properties } if ($ObjectId) { try { Invoke-EntraRequest -Service $services.Graph -Path "applications/$ObjectId" -Query $query | ConvertFrom-Application -Raw:$Raw } catch { $PSCmdlet.WriteError($_) } return } $filterBuilder = [FilterBuilder]::new() if ($DisplayName -and $DisplayName -ne '*') { $filterBuilder.Add('displayName', 'eq', $DisplayName) } if ($ApplicationId) { $filterBuilder.Add('appId', 'eq', $ApplicationId) } if ($Filter) { $filterBuilder.CustomFilter = $Filter } if ($filterBuilder.Count() -gt 0) { $query['$filter'] = $filterBuilder.Get() } Invoke-EntraRequest -Service $services.Graph -Path 'applications' -Query $query | ConvertFrom-Application -Raw:$Raw } } function Get-EAGManagedIdentity { <# .SYNOPSIS Retrieves Managed Service Identities from Entra ID. .DESCRIPTION The Get-EAGManagedIdentity cmdlet retrieves Managed Service Identities (MSIs) from Entra ID. It allows you to search for MSIs by display name, application ID, or object ID, and filter the results. This cmdlet is a specialized wrapper around Get-EAGServicePrincipal that filters for service principals of type 'ManagedIdentity'. Scopes Needed: Application.Read.All .PARAMETER DisplayName The display name of the Managed Service Identity to retrieve. .PARAMETER ObjectId The Object ID of the Managed Service Identity to retrieve. When specified, returns a single MSI with the exact matching ID. .PARAMETER ApplicationId The Application ID (Client ID) of the Managed Service Identity to retrieve. Also known as AppId or ClientID. .PARAMETER Filter Additional OData filter expression to apply when searching for MSIs. .PARAMETER Properties Specific properties to retrieve from the MSI objects. .PARAMETER Raw When specified, returns the raw API response objects instead of the formatted PowerShell objects. Useful for accessing detailed properties not exposed at the top level, but less user-friendly. .PARAMETER ServiceMap Optional hashtable to map service names to specific EntraAuth service instances. Used for advanced scenarios where you want to use something other than the default Graph connection. Example: @{ Graph = 'GraphBeta' } This will switch all Graph API calls to use the beta Graph API. .EXAMPLE PS C:\> Get-EAGManagedIdentity Retrieves all Managed Service Identities in the Entra ID tenant. .EXAMPLE PS C:\> Get-EAGManagedIdentity -DisplayName "MyWebApp" Retrieves the Managed Service Identity with the display name "MyWebApp". .EXAMPLE PS C:\> Get-EAGManagedIdentity -ApplicationId "11111111-1111-1111-1111-111111111111" Retrieves the Managed Service Identity with the specified application ID. #> [CmdletBinding(DefaultParameterSetName = 'Filter')] param ( [Parameter(ParameterSetName = 'Filter')] [string] $DisplayName, [Parameter(Mandatory = $true, ParameterSetName = 'Identity')] [Alias('Id')] [string] $ObjectId, [Parameter(ParameterSetName = 'Filter', ValueFromPipelineByPropertyName = $true)] [Alias('AppId', 'ClientID')] [string] $ApplicationId, [Parameter(ParameterSetName = 'Filter', ValueFromPipelineByPropertyName = $true)] [string] $Filter, [string[]] $Properties, [switch] $Raw, [hashtable] $ServiceMap = @{} ) begin { $services = $script:serviceSelector.GetServiceMap($ServiceMap) Assert-EntraConnection -Service $services.Graph -Cmdlet $PSCmdlet } process { $common = @{ ServiceMap = $services } if ($Properties) { $common.Properties = $Properties } if ($Raw) { $common.Raw = $Raw } if ($ObjectID) { Get-EAGServicePrincipal @common -ObjectId $ObjectId return } $param = @{ Filter = "servicePrincipalType eq 'ManagedIdentity'" } if ($DisplayName) { $param.DisplayName = $DisplayName } if ($ApplicationId) { $param.ApplicationId = $ApplicationId } if ($Filter) { $param.Filter = $param.Filter, $Filter -join ' and ' } Get-EAGServicePrincipal @common @param } } function Get-EAGScope { <# .SYNOPSIS Lists scopes applied to app registrations, service principals, and managed identities. .DESCRIPTION Lists scopes applied to app registrations, service principals, and managed identities. Scopes Needed: Application.Read.All, User.ReadBasic.All (Delegated), User.Read.All (Application) .PARAMETER Type Filter scopes by type. Valid Options: - All: All scopes (default) - Delegated: Delegated scopes - Application: Application scopes .PARAMETER DisplayName The displayname of the app registration or service principal to filter by. .PARAMETER ApplicationId The Application ID (Client ID) of the app registration or service principal to filter by. .PARAMETER ObjectId The Object ID of the app registration or service principal to filter by. .PARAMETER ClearCache Indicates whether to clear the cache of resolved scopes and principals. This should only be needed when developing an application and modifying/updating scope definitions. .PARAMETER ServiceMap Optional hashtable to map service names to specific EntraAuth service instances. Used for advanced scenarios where you want to use something other than the default Graph connection. Example: @{ Graph = 'GraphBeta' } This will switch all Graph API calls to use the beta Graph API. .EXAMPLE PS C:\> Get-EAGScope -DisplayName "MyWebApp" Retrieves all scopes applied to the app registration or service principal with the display name "MyWebApp". .EXAMPLE PS C:\> Get-EAGScope -ApplicationId "11111111-1111-1111-1111-111111111111" Retrieves all scopes applied to the app registration or service principal with the specified application ID. #> [CmdletBinding(DefaultParameterSetName = 'Filter')] param ( [ValidateSet('All', 'Delegated', 'Application')] [string] $Type = 'All', [Parameter(ParameterSetName = 'Filter', ValueFromPipelineByPropertyName = $true)] [string] $DisplayName, [Parameter(ParameterSetName = 'Filter', ValueFromPipelineByPropertyName = $true)] [Alias('AppId', 'ClientID')] [string] $ApplicationId, [Parameter(Mandatory = $true, ParameterSetName = 'Identity', ValueFromPipelineByPropertyName = $true)] [Alias('Id')] [string] $ObjectId, [switch] $ClearCache, [hashtable] $ServiceMap = @{} ) begin { $services = $script:serviceSelector.GetServiceMap($ServiceMap) Assert-EntraConnection -Service $services.Graph -Cmdlet $PSCmdlet #region Functions function Get-DelegateScope { [CmdletBinding()] param ( [AllowNull()] $Application, $ServicePrincipal, [hashtable] $Services ) $grants = Invoke-EntraRequest -Service $Services.Graph -Path oauth2PermissionGrants -Query @{ '$filter' = "clientId eq '$($ServicePrincipal.Id)'" } #region Process Granted Scopes $scopesProcessed = @{} foreach ($grant in $grants) { $principal = Resolve-ScopePrincipal -ID $grant.principalId -Services $Services foreach ($scope in $grant.scope.Trim() -split ' ') { $scopeData = Resolve-Scope -Scope $scope -Resource $grant.resourceId -Type 'Delegated' -Services $Services [PSCustomObject]@{ PSTypeName = 'EntraAuth.Graph.Scope' ApplicationId = $ServicePrincipal.AppID ApplicationName = $ServicePrincipal.DisplayName Resource = $grant.resourceId ResourceName = $script:cache.ServicePrincipalByID."$($grant.resourceId)".displayName Type = 'Delegated' Scope = $scopeData.Id ScopeName = $scopeData.value ConsentRequired = $scopeData.ConsentRequired HasConsent = $true PrincipalName = $principal.Name PrincipalID = $principal.ID } $scopesProcessed[$scopeData.id] = $scopeData } } #endregion Process Granted Scopes if (-not $Application) { return } #region Process Non-Granted Scopes foreach ($resourceReq in $Application.requiredResourceAccess) { foreach ($resourceEntry in $resourceReq.resourceAccess) { if ($resourceEntry.type -ne 'Scope') { continue } if ($scopesProcessed[$resourceEntry.id]) { continue } $scopeData = Resolve-Scope -Scope $resourceEntry.id -Resource $resourceReq.resourceAppId -Type 'Delegated' -Services $Services [PSCustomObject]@{ PSTypeName = 'EntraAuth.Graph.Scope' ApplicationId = $ServicePrincipal.AppID ApplicationName = $ServicePrincipal.DisplayName Resource = $resourceReq.resourceAppId ResourceName = $scopeData.ResourceName Type = 'Delegated' Scope = $scopeData.Id ScopeName = $scopeData.value ConsentRequired = $scopeData.ConsentRequired HasConsent = $false PrincipalName = $null PrincipalID = $null } } } #endregion Process Non-Granted Scopes } function Get-ApplicationScope { [CmdletBinding()] param ( [AllowNull()] $Application, $ServicePrincipal, [hashtable] $Services ) #region Process Granted Scopes $scopesProcessed = @{} $appRoleAssignments = Invoke-EntraRequest -Service $Services.Graph -Path "servicePrincipals/$($ServicePrincipal.id)/appRoleAssignments" foreach ($roleAssignment in $appRoleAssignments) { $scopeData = Resolve-Scope -Scope $roleAssignment.appRoleId -Resource $roleAssignment.resourceId -Type 'Application' -Services $Services [PSCustomObject]@{ PSTypeName = 'EntraAuth.Graph.Scope' ApplicationId = $ServicePrincipal.AppID ApplicationName = $ServicePrincipal.DisplayName Resource = $roleAssignment.resourceId ResourceName = $roleAssignment.resourceDisplayName Type = 'Application' Scope = $scopeData.Id ScopeName = $scopeData.value ConsentRequired = $true HasConsent = $true PrincipalName = $null PrincipalID = $null } $scopesProcessed[$scopeData.id] = $scopeData } #endregion Process Granted Scopes if (-not $Application) { return } #region Process Non-Granted Scopes foreach ($resourceReq in $Application.requiredResourceAccess) { foreach ($resourceEntry in $resourceReq.resourceAccess) { if ($resourceEntry.type -ne 'Role') { continue } if ($scopesProcessed[$resourceEntry.id]) { continue } $scopeData = Resolve-Scope -Scope $resourceEntry.id -Resource $resourceReq.resourceAppId -Type 'Application' -Services $Services [PSCustomObject]@{ PSTypeName = 'EntraAuth.Graph.Scope' ApplicationId = $ServicePrincipal.AppID ApplicationName = $ServicePrincipal.DisplayName Resource = $resourceReq.resourceAppId ResourceName = $scopeData.ResourceName Type = 'Application' Scope = $scopeData.Id ScopeName = $scopeData.value ConsentRequired = $true HasConsent = $false PrincipalName = $null PrincipalID = $null } } } #endregion Process Non-Granted Scopes } #endregion Functions if ($ClearCache) { $script:cache.ResolvedScopes.Clear() $script:cache.Principals.Clear() } } process { $param = @{} if ($DisplayName) { $param.DisplayName = $DisplayName } if ($ApplicationId) { $param.ApplicationId = $ApplicationId } if ($ObjectId) { $param.ObjectId = $ObjectId } $servicePrincipals = Get-EAGServicePrincipal @param -Properties id, appid, displayName, servicePrincipalType, appRoles, oauth2PermissionScopes, resourceSpecificApplicationPermissions -ServiceMap $ServiceMap foreach ($servicePrincipal in $servicePrincipals) { $application = Get-EAGAppRegistration -ApplicationId $servicePrincipal.AppID -ServiceMap $ServiceMap -Raw if ($Type -in 'All', 'Delegated') { Get-DelegateScope -Application $application -ServicePrincipal $servicePrincipal -Services $services } if ($Type -in 'All', 'Application') { Get-ApplicationScope -Application $application -ServicePrincipal $servicePrincipal -Services $services } } } } function Get-EAGScopeDefinition { <# .SYNOPSIS Retrieves scope definitions from service principals / Enterprise applications. .DESCRIPTION Retrieves scope definitions from service principals / Enterprise applications. This does NOT return assigned or granted scopes on the apps. It provides the scopes provided BY the service in question. .PARAMETER Name The name of the scope to filter by. .PARAMETER Type The type of scopes to retrieve. Valid Options: - All: All scopes (default) - Delegated: Delegated scopes - Application: Application scopes - AppResource: Resource-specific Application scopes .PARAMETER DisplayName Filter by display name of the service principal. .PARAMETER ApplicationId Filter by application ID of the service principal. .PARAMETER ObjectId Filter by object ID of the service principal. .PARAMETER Resource Filter by the resource Identifier of the service. .PARAMETER Force Include disabled scopes. .PARAMETER ServiceMap Optional hashtable to map service names to specific EntraAuth service instances. Used for advanced scenarios where you want to use something other than the default Graph connection. Example: @{ Graph = 'GraphBeta' } This will switch all Graph API calls to use the beta Graph API. .EXAMPLE PS C:\> Get-EAGScopeDefinition -Name "User.Read" Retrieves all scopes with the name "User.Read". .EXAMPLE PS C:\> Get-EAGScopeDefinition -DisplayName 'Microsoft Graph' Retrieves all scopes provided by the service principal with the display name 'Microsoft Graph'. .EXAMPLE PS C:\> Get-EAGScopeDefinition -DisplayName 'Microsoft Graph' -Name User.* Retrieves all scopes with the name starting with 'User.' provided by the service principal with the display name 'Microsoft Graph'. .EXAMPLE PS C:\> Get-EAGScopeDefinition -Resource https://graph.microsoft.com -Name Group.* Retrieves all scopes with the name starting with 'Group.' provided by the service principal with the service principal name 'https://graph.microsoft.com'. #> [CmdletBinding(DefaultParameterSetName = 'Filter')] param ( [string] $Name = '*', [ValidateSet('All', 'Delegated', 'Application', 'AppResource')] [string] $Type = 'All', [Parameter(ParameterSetName = 'Filter', ValueFromPipelineByPropertyName = $true)] [string] $DisplayName, [Parameter(ParameterSetName = 'Filter', ValueFromPipelineByPropertyName = $true)] [Alias('AppId', 'ClientID')] [string] $ApplicationId, [Parameter(Mandatory = $true, ParameterSetName = 'Identity', ValueFromPipelineByPropertyName = $true)] [Alias('Id')] [string] $ObjectId, [Parameter(Mandatory = $true, ParameterSetName = 'Resource')] [string] $Resource, [switch] $Force, [hashtable] $ServiceMap = @{} ) begin { $services = $script:serviceSelector.GetServiceMap($ServiceMap) Assert-EntraConnection -Service $services.Graph -Cmdlet $PSCmdlet function New-ScopeDefinition { [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSUseShouldProcessForStateChangingFunctions", "")] [CmdletBinding()] param ( [string] $ResourceID, [string] $ResourceName, [string] $Type, [string] $ScopeID, [string] $ScopeName, [string] $Description, [bool] $Consent = $true, [bool] $Enabled, $Object ) if ($Object) { $Enabled = $Object.isEnabled $ScopeID = $Object.id $ScopeName = $Object.value } [PSCustomObject]@{ PSTypeName = 'EntraAuth.Graph.ScopeDefinition' ResourceID = $ResourceID ResourceName = $ResourceName Type = $Type ScopeID = $ScopeID ScopeName = $ScopeName Description = $Description ConsentRequired = $Consent Enabled = $Enabled } } } process { $param = @{} if ($DisplayName) { $param.DisplayName = $DisplayName } if ($ApplicationId) { $param.ApplicationId = $ApplicationId } if ($ObjectId) { $param.ObjectId = $ObjectId } if ($Resource) { $filter = "serviceprincipalNames/any(x:x eq '$Resource')" if ($Resource -as [guid]) { $filter = "id eq '$Resource' or appId eq '$Resource' or serviceprincipalNames/any(x:x eq '$Resource')" } $param.Filter = $filter } $servicePrincipals = Get-EAGServicePrincipal @param -Properties id, appid, displayName, servicePrincipalType, appRoles, oauth2PermissionScopes, resourceSpecificApplicationPermissions -ServiceMap $ServiceMap foreach ($servicePrincipal in $servicePrincipals) { $spnData = @{ ResourceID = $servicePrincipal.ID; ResourceName = $servicePrincipal.displayName } if ($Type -in 'All', 'Delegated') { foreach ($scope in $servicePrincipal.Scopes.Delegated) { if (-not $scope.isEnabled -and -not $Force) { continue } if ($scope.value -notlike $Name) { continue } New-ScopeDefinition @spnData -Object $scope -Type Delegated -Description $scope.adminConsentDescription -Consent ($scope.type -eq 'Admin') } } if ($Type -in 'All', 'Application') { foreach ($scope in $servicePrincipal.Scopes.Application) { if (-not $scope.isEnabled -and -not $Force) { continue } if ($scope.value -notlike $Name) { continue } New-ScopeDefinition @spnData -Object $scope -Type Application -Description $scope.description } } if ($Type -in 'All', 'AppResource') { foreach ($scope in $servicePrincipal.Scopes.AppResource) { if (-not $scope.isEnabled -and -not $Force) { continue } if ($scope.value -notlike $Name) { continue } New-ScopeDefinition @spnData -Object $scope -Type AppResource -Description $scope.description } } } } } function Get-EAGServicePrincipal { <# .SYNOPSIS Lists service principals in the connected Entra ID tenant. .DESCRIPTION Lists service principals in the connected Entra ID tenant. Scope Needed: Application.Read.All .PARAMETER DisplayName The display name of the service principal to filter by. .PARAMETER ObjectId The Object ID of the service principal to filter by. .PARAMETER ApplicationId The Application ID (Client ID) of the service principal to filter by. .PARAMETER Filter Additional OData filter expression to apply when searching for service principals. .PARAMETER Properties Specific properties to retrieve from the service principal objects. .PARAMETER Raw When specified, returns the raw API response objects instead of the formatted PowerShell objects. Useful for accessing detailed properties not exposed at the top level, but less user-friendly. .PARAMETER ServiceMap Optional hashtable to map service names to specific EntraAuth service instances. Used for advanced scenarios where you want to use something other than the default Graph connection. Example: @{ Graph = 'GraphBeta' } This will switch all Graph API calls to use the beta Graph API. .EXAMPLE PS C:\> Get-EAGServicePrincipal Retrieves all service principals in the Entra ID tenant. .EXAMPLE PS C:\> Get-EAGServicePrincipal -DisplayName "MyWebApp" Retrieves the service principal with the display name "MyWebApp". .EXAMPLE PS C:\> Get-EAGServicePrincipal -DisplayName 'Dept-*' -Properties 'displayName', 'appId' Retrieves all service principals that start with "Dept-" and returns only the display name and app ID properties. #> [CmdletBinding()] param ( [Parameter(ParameterSetName = 'Filter')] [string] $DisplayName, [Parameter(Mandatory = $true, ParameterSetName = 'Identity')] [Alias('Id')] [string] $ObjectId, [Parameter(ParameterSetName = 'Filter', ValueFromPipelineByPropertyName = $true)] [Alias('AppId', 'ClientID')] [string] $ApplicationId, [Parameter(ParameterSetName = 'Filter', ValueFromPipelineByPropertyName = $true)] [string] $Filter, [string[]] $Properties, [switch] $Raw, [hashtable] $ServiceMap = @{} ) begin { $services = $script:serviceSelector.GetServiceMap($ServiceMap) Assert-EntraConnection -Service $services.Graph -Cmdlet $PSCmdlet function ConvertFrom-ServicePrincipal { [CmdletBinding()] param ( [Parameter(ValueFromPipeline = $true)] $InputObject, [switch] $Raw ) process { #region Feed the Cache if ($InputObject.AppID) { if (-not $script:cache.ServicePrincipalByAppID[$InputObject.AppID]) { $script:cache.ServicePrincipalByAppID[$InputObject.AppID] = [PSCustomObject]@{ Type = $InputObject.servicePrincipalType Id = $InputObject.id AppID = $InputObject.AppID DisplayName = $InputObject.DisplayName } } else { # Depending on selected we might lose individual properties if we overwrite all $current = $script:cache.ServicePrincipalByAppID[$InputObject.AppID] if ($InputObject.servicePrincipalType) { $current.Type = $InputObject.servicePrincipalType } if ($InputObject.id) { $current.Id = $InputObject.id } if ($InputObject.AppID) { $current.AppID = $InputObject.AppID } if ($InputObject.DisplayName) { $current.DisplayName = $InputObject.DisplayName } } } if ($InputObject.ID) { if (-not $script:cache.ServicePrincipalByID[$InputObject.ID]) { $script:cache.ServicePrincipalByID[$InputObject.ID] = [PSCustomObject]@{ Type = $InputObject.servicePrincipalType Id = $InputObject.id AppID = $InputObject.AppID DisplayName = $InputObject.DisplayName } } else { # Depending on selected we might lose individual properties if we overwrite all $current = $script:cache.ServicePrincipalByID[$InputObject.ID] if ($InputObject.servicePrincipalType) { $current.Type = $InputObject.servicePrincipalType } if ($InputObject.id) { $current.Id = $InputObject.id } if ($InputObject.AppID) { $current.AppID = $InputObject.AppID } if ($InputObject.DisplayName) { $current.DisplayName = $InputObject.DisplayName } } } foreach ($scope in $InputObject.AppRoles) { $script:cache.ScopesByID[$scope.id] = $scope } foreach ($scope in $InputObject.oauth2PermissionScopes) { $script:cache.ScopesByID[$scope.id] = $scope } foreach ($scope in $InputObject.resourceSpecificApplicationPermissions) { $script:cache.ScopesByID[$scope.id] = $scope } #endregion Feed the Cache if ($Raw) { return $InputObject } [PSCustomObject]@{ PSTypeName = 'EntraAuth.Graph.ServicePrincipal' Type = $InputObject.servicePrincipalType Id = $InputObject.id AppID = $InputObject.AppID DisplayName = $InputObject.DisplayName AppDisplayName = $InputObject.AppDisplayName AppOwnerOrg = $InputObject.AppOwnerOrganizationId AssignmentRequired = $InputObject.appRoleAssignmentRequired ServicePrincipalNames = $InputObject.servicePrincipalNames Scopes = @{ Delegated = @($InputObject.oauth2PermissionScopes) Application = @($InputObject.appRoles) AppResource = @($InputObject.resourceSpecificApplicationPermissions) } Object = $InputObject } } } } process { $query = @{ } if ($Properties) { $query['$select'] = $Properties } if ($ObjectId) { try { Invoke-EntraRequest -Service $services.Graph -Path "servicePrincipals/$ObjectId" -Query $query | ConvertFrom-ServicePrincipal -Raw:$Raw } catch { $PSCmdlet.WriteError($_) } return } $filterBuilder = [FilterBuilder]::new() if ($DisplayName -and $DisplayName -ne '*') { $filterBuilder.Add('displayName', 'eq', $DisplayName) } if ($ApplicationId) { $filterBuilder.Add('appId', 'eq', $ApplicationId) } if ($Filter) { $filterBuilder.CustomFilter = $Filter } if ($filterBuilder.Count() -gt 0) { $query['$filter'] = $filterBuilder.Get() } Invoke-EntraRequest -Service $services.Graph -Path 'servicePrincipals' -Query $query | ConvertFrom-ServicePrincipal -Raw:$Raw } } function Grant-EAGScopeConsent { <# .SYNOPSIS Grants consent for a scope on an App Registration. .DESCRIPTION Grants consent for a scope on an App Registration. Consent is required for scopes configured on an app registration to take effect in the tenant. The App Registration is a manifest, the declaration of the application in use. The Enterprise Application / Service Principal is the actual object that represents the application in the tenant. Granting "Admin Consent" to scopes on an App Registration will copy those onto the Enterprise Application / Service Principal, hence making them take effect. Note: Managed Identities are also Service Principals, but they do not have an App Registration. There is no consent of "Consent", as there is no manifest's proposal to consent to. This does not mean that Managed Identities cannot have scopes, but they require a different approach. Use "Add-EAGMsiScope" to add scopes to Managed Identities. Scopes Needed: Application.Read.All, AppRoleAssignment.ReadWrite.All .PARAMETER DisplayName Display name of the app registration whose scopes to grant consent to. .PARAMETER ApplicationId Application ID (Client ID) of the app registration whose scopes to grant consent to. .PARAMETER ObjectId Object ID of the app registration whose scopes to grant consent to. .PARAMETER Scope The permission scopes to grant consent to. .PARAMETER Type Type of the permission scopes to grant consent to. Valid Options: - Delegated: Permissions that apply to interactive sessions, where the application acts on behalf of the signed-in user. - Application: Permissions that apply to unattended sessions, where the application acts as itself. .PARAMETER Resource The resource (API) to which the permissions/scopes apply. This can be specified as a display name, application ID, object ID or Service Principal Name. Examples: + 'Microsoft Graph' + '00000003-0000-0000-c000-000000000000' + 'https://graph.microsoft.com' .PARAMETER ServiceMap Optional hashtable to map service names to specific EntraAuth service instances. Used for advanced scenarios where you want to use something other than the default Graph connection. Example: @{ Graph = 'GraphBeta' } This will switch all Graph API calls to use the beta Graph API. .PARAMETER WhatIf If this switch is enabled, no actions are performed but informational messages will be displayed that explain what would happen if the command were to run. .PARAMETER Confirm If this switch is enabled, you will be prompted for confirmation before executing any operations that change state. .EXAMPLE PS C:\> Grant-EAGScopeConsent -DisplayName "MyWebApp" -Resource "Microsoft Graph" -Scope "User.Read.All" -Type Application Grants consent for the User.Read.All application permission for Microsoft Graph to the app registration named "MyWebApp". .EXAMPLE PS C:\> Grant-EAGScopeConsent -ApplicationId "11111111-1111-1111-1111-111111111111" -Resource "00000003-0000-0000-c000-000000000000" -Scope "User.Read.All", "Group.Read.All" -Type Delegated Grants consent for the User.Read.All and Group.Read.All delegated permissions for Microsoft Graph (identified by its app ID) to the app registration with the specified application ID. .EXAMPLE PS C:\> Get-EAGAppRegistration -DisplayName MyTaskApp | Grant-EAGScopeConsent -Resource "https://graph.microsoft.com" -Scope "User.ReadBasic.All" -Type Delegated Grants consent for the User.ReadBasic.All delegated permission for Microsoft Graph to the app registration named "MyTaskApp". #> [CmdletBinding(DefaultParameterSetName = 'Filter', SupportsShouldProcess = $true)] param ( [Parameter(ParameterSetName = 'Filter', ValueFromPipelineByPropertyName = $true)] [string] $DisplayName, [Parameter(ParameterSetName = 'Filter', ValueFromPipelineByPropertyName = $true)] [Alias('AppId', 'ClientID')] [string] $ApplicationId, [Parameter(Mandatory = $true, ParameterSetName = 'Identity', ValueFromPipelineByPropertyName = $true)] [Alias('Id')] [string] $ObjectId, [Parameter(Mandatory = $true, ValueFromPipelineByPropertyName = $true)] [string[]] $Scope, [Parameter(Mandatory = $true, ValueFromPipelineByPropertyName = $true)] [ValidateSet('Delegated','Application')] [string] $Type, [Parameter(Mandatory = $true, ValueFromPipelineByPropertyName = $true)] [string] $Resource, [hashtable] $ServiceMap ) begin { $services = $script:serviceSelector.GetServiceMap($ServiceMap) Assert-EntraConnection -Service $services.Graph -Cmdlet $PSCmdlet $principals = @{ } $applications = @{ } $servicePrincipals = @{ } } process { #region Resolve Scope Data $result = Resolve-ServicePrincipal -Identity $Resource -Cache $principals -Unique -Services $services if (-not $result.Success) { Write-Error -Message $result.Message return } $servicePrincipal = $result.Result $resolvedScopes = foreach ($entry in $Scope) { $scopeEntry = Resolve-Scope -Scope $entry -Resource $servicePrincipal.ID -Type $Type -Services $services if ($scopeEntry.ScopeName -eq '<not identified>') { Write-Error "Scope $entry of type $Type not found on Service Principal $($servicePrincipal.DisplayName) ($($servicePrincipal.ID) | $Resource)" continue } $scopeEntry } if (-not $resolvedScopes) { Write-Error -Message "No valid scopes found! Use 'Get-EAGScopeDefinition' to find the valid scopes for the resource and try again." return } #endregion Resolve Scope Data #region Resolve Application Data $result = Resolve-Application -DisplayName $DisplayName -ApplicationId $ApplicationId -ObjectId $ObjectId -Cache $applications -Unique -Services $services if (-not $result.Success) { Write-Error $result.Message return } $application = $result.Result $result = Resolve-ServicePrincipal -Identity $application.AppID -Properties id -Cache $servicePrincipals -Unique -Services $services if (-not $result.Success) { Write-Error "Error resolving Enterprise Application for $($application.AppID):`n$($result.Message)" return } $appSPN = $result.Result #endregion Resolve Application Data $applicationGrants = Invoke-EntraRequest -Service $services.Graph -Path "servicePrincipals/$($appSPN.id)/appRoleAssignments" $delegatedGrants = Invoke-EntraRequest -Service $services.Graph -Path 'oauth2PermissionGrants' -Query @{ '$filter' = "clientId eq '$($appSPN.id)' and consentType eq 'AllPrincipals'" } $newDelegateGrants = @() foreach ($resolvedScope in $resolvedScopes) { if ($resolvedScope.Type -eq 'Application' -and $resolvedScope.ID -in $applicationGrants.appRoleId) { Write-Verbose "Skipping Application scope $($resolvedScope.Value) - already consented on $($application.DisplayName)" continue } if ($resolvedScope.Type -eq 'Delegated' -and $resolvedScope.Value -in @($delegatedGrants.scope -split ' ').ForEach{$_.Trim()}) { Write-Verbose "Skipping Delegated scope $($resolvedScope.Value) - already consented on $($application.DisplayName)" continue } if (-not $PSCmdlet.ShouldProcess("$($application.DisplayName) ($($application.AppID))", "Grant consent for scope $($resolvedScope.Value) of resource $($resolvedScope.ResourceName)")) { continue } Write-Verbose "Processing scope:`n$($resolvedScope | ConvertTo-Json)" switch ($resolvedScope.Type) { 'Application' { $grant = @{ "principalId" = $appSPN.id "resourceId" = $resolvedScope.Resource "appRoleId" = $resolvedScope.ID } Write-Verbose "Granting Admin consent for scope $($resolvedScope.id) ($($resolvedScope.Value))) on $($appSPN.appid) ($($appSPN.displayName))" try { $null = Invoke-EntraRequest -Method POST -Path "servicePrincipals/$($appSPN.id)/appRoleAssignments" -Body $grant -Header @{ 'content-type' = 'application/json' } } catch { Write-Error $_ } } 'Delegated' { $newDelegateGrants += $resolvedScope } default { Write-Error "Unexpected scope type: $($resolvedScope.Type)" } } } if (-not $newDelegateGrants) { return } $byResource = $newDelegateGrants | Group-Object Resource foreach ($group in $byResource) { $scopeGrant = $group.Group.Value $applicableGrant = $delegatedGrants | Where-Object resourceId -eq $group.Name if ($applicableGrant) { $scopeGrant = @(@($applicableGrant.Scope -split " ").ForEach{ $_.Trim() }) + $scopeGrant } $exampleScope = $group.Group[0] $grant = @{ "clientId" = $appSPN.id "consentType" = "AllPrincipals" "principalId" = $null "resourceId" = $exampleScope.Resource "scope" = $scopeGrant -join " " "expiryTime" = "2299-12-31T00:00:00Z" } Write-Verbose "Granting Admin consent for scope(s) $($group.Group.Value -join ', ') on $($appSPN.appid) ($($appSPN.displayName))" $method = 'POST' $apiPath = 'oauth2PermissionGrants' if ($applicableGrant) { $method = 'PATCH' $apiPath = "oauth2PermissionGrants/$($applicableGrant.id)" $grant = @{ scope = $scopeGrant -join " " } } try { $null = Invoke-EntraRequest -Method $method -Path $apiPath -Body $grant -Header @{ 'content-type' = 'application/json' } } catch { Write-Error $_ } } } } function New-EAGAppRegistration { <# .SYNOPSIS Creates a new App Registration in the connected Entra ID tenant. .DESCRIPTION Creates a new App Registration in the connected Entra ID tenant. By default, it will also create the associated Enterprise Application (service principal). Scopes Needed: Application.ReadWrite.All .PARAMETER DisplayName The display name of the App Registration. .PARAMETER Description The description of the App Registration. .PARAMETER RedirectUri Any redirect URIs to associate with the App Registration. These are needed for Delegated authentication flows, where the application acts on behalf of a user. .PARAMETER Platform When specifying a RedirectUri, what "Platform" should be configured. This determines, how authentication can be performed. Options: - MobileDesktop: This will enable the authentication, where a browser window pops up and asks the user to authenticate. (Authorization Code flow) - Web: This will enable the authentication, where the user is asked to open a specific URL and paste in a code provided, THEN authenticate. (DeviceCode flow) Generally, MobileDesktop is the preferred option, as it is more user-friendly and secure. Defaults to: MobileDesktop .PARAMETER NoEnterpriseApp Do not create the associated Enterprise Application (service principal). By default, the Enterprise Application is created automatically, as without it, the App Registration cannot really be used. .PARAMETER ServiceMap Optional hashtable to map service names to specific EntraAuth service instances. Used for advanced scenarios where you want to use something other than the default Graph connection. Example: @{ Graph = 'GraphBeta' } This will switch all Graph API calls to use the beta Graph API. .PARAMETER WhatIf If this switch is enabled, no actions are performed but informational messages will be displayed that explain what would happen if the command were to run. .PARAMETER Confirm If this switch is enabled, you will be prompted for confirmation before executing any operations that change state. .EXAMPLE PS C:\> New-EAGAppRegistration -DisplayName "DEPT-AAA-Task1" -RedirectUri "http://Localhost" Creates a new App Registration named "DEPT-AAA-Task1" with the redirect URI "http://Localhost". This could then be used to authenticate to interactively from PowerShell. .LINK https://learn.microsoft.com/en-us/graph/api/application-post-applications?view=graph-rest-1.0&tabs=http #> [CmdletBinding(SupportsShouldProcess = $true)] param ( [Parameter(Mandatory = $true)] [string] $DisplayName, [string] $Description, [string[]] $RedirectUri, [ValidateSet('MobileDesktop', 'Web')] [string] $Platform = 'MobileDesktop', [switch] $NoEnterpriseApp, [hashtable] $ServiceMap = @{} ) begin { $services = $script:serviceSelector.GetServiceMap($ServiceMap) Assert-EntraConnection -Service $services.Graph -Cmdlet $PSCmdlet } process { $body = @{ displayName = $DisplayName } if ($RedirectUri) { switch ($Platform) { MobileDesktop { $body["publicClient"] = @{ redirectUris = @($RedirectUri) } } Web { $body["web"] = @{ redirectUris = @($RedirectUri) } } default { Invoke-TerminatingException -Message "Platform not implemented yet: $Platform" -Cmdlet $PSCmdlet -Category NotImplemented } } } if ($Description) { $Body.description = $Description } Write-Verbose "Final Request Body:`n$($body | ConvertTo-Json)" if (-not $PSCmdlet.ShouldProcess($DisplayName, "Create App Registration")) { return } $appRegistration = Invoke-EntraRequest -Service $services.Graph -Method POST -Path applications -Body $body -Header @{ 'content-type' = 'application/json' } $appRegistration | ConvertFrom-Application if ($NoEnterpriseApp) { return } $null = Invoke-EntraRequest -Service $services.Graph -Method POST -Path servicePrincipals -Body @{ appId = $appRegistration.appId } -Header @{ 'content-type' = 'application/json' } } } function Remove-EAGAppRegistration { <# .SYNOPSIS Murders innocent App Registrations. .DESCRIPTION Murders innocent App Registrations. They will be gone, forever. Rest in Pieces. Scopes Needed: Application.ReadWrite.All .PARAMETER Id Object ID of the app registration to slaughter. .PARAMETER ServiceMap Optional hashtable to map service names to specific EntraAuth service instances. Used for advanced scenarios where you want to use something other than the default Graph connection. Example: @{ Graph = 'GraphBeta' } This will switch all Graph API calls to use the beta Graph API. .PARAMETER WhatIf If this switch is enabled, no actions are performed but informational messages will be displayed that explain what would happen if the command were to run. .PARAMETER Confirm If this switch is enabled, you will be prompted for confirmation before executing any operations that change state. .EXAMPLE PS C:\> Get-EAGAppRegistration -DisplayName "MyWebApp" | Remove-EAGAppRegistration Deletes the app registration with the display name "MyWebApp". #> [CmdletBinding(SupportsShouldProcess = $true)] param ( [Parameter(Mandatory = $true, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true)] [string[]] $Id, [hashtable] $ServiceMap = @{} ) begin { $services = $script:serviceSelector.GetServiceMap($ServiceMap) Assert-EntraConnection -Service $services.Graph -Cmdlet $PSCmdlet } process { foreach ($entry in $Id) { if (-not $PSCmdlet.ShouldProcess($entry, "Delete App Registration")) { continue } try { Invoke-EntraRequest -Service $services.Graph -Method DELETE -Path "applications/$entry" } catch { $PSCmdlet.WriteError($_) continue } } } } function Remove-EAGAppScope { <# .SYNOPSIS Removes API permissions (scopes) from an App Registration. .DESCRIPTION Removes API permissions (scopes) from an App Registration. Scopes Needed: Application.Read.All, AppRoleAssignment.ReadWrite.All .PARAMETER DisplayName The display name of the App Registration to remove scopes from. .PARAMETER ApplicationId The Application ID (Client ID) of the App Registration to remove scopes from. .PARAMETER ObjectId The Object ID of the App Registration to remove scopes from. .PARAMETER Scope The permissions (scopes) to remove from the App Registration. .PARAMETER Type The type of the permissions to remove. Valid Options: - Delegated: Permissions that apply to interactive sessions, where the application acts on behalf of the signed-in user. - Application: Permissions that apply to unattended sessions, where the application acts as itself. .PARAMETER Resource The resource (API) to which the permissions/scopes apply. This can be specified as a display name, application ID, object ID or Service Principal Name. Examples: + 'Microsoft Graph' + '00000003-0000-0000-c000-000000000000' + 'https://graph.microsoft.com' .PARAMETER ServiceMap Optional hashtable to map service names to specific EntraAuth service instances. Used for advanced scenarios where you want to use something other than the default Graph connection. Example: @{ Graph = 'GraphBeta' } This will switch all Graph API calls to use the beta Graph API. .PARAMETER WhatIf If this switch is enabled, no actions are performed but informational messages will be displayed that explain what would happen if the command were to run. .PARAMETER Confirm If this switch is enabled, you will be prompted for confirmation before executing any operations that change state. .EXAMPLE PS C:\> Remove-EAGAppScope -DisplayName "MyWebApp" -Resource "Microsoft Graph" -Scope "User.Read.All" -Type Application Removes the User.Read.All application permission for Microsoft Graph from the App Registration named "MyWebApp". .EXAMPLE PS C:\> Get-EAGAppRegistration -DisplayName D-AAA-Task1 | Get-EAGScope | Remove-EAGAppScope Removes all scopes from the App Registration named "D-AAA-Task1". #> [CmdletBinding(SupportsShouldProcess = $true, DefaultParameterSetName = 'Filter')] param ( [Parameter(ParameterSetName = 'Filter', ValueFromPipelineByPropertyName = $true)] [string] $DisplayName, [Parameter(ParameterSetName = 'Filter', ValueFromPipelineByPropertyName = $true)] [Alias('AppId', 'ClientID')] [string] $ApplicationId, [Parameter(Mandatory = $true, ParameterSetName = 'Identity', ValueFromPipelineByPropertyName = $true)] [Alias('Id')] [string] $ObjectId, [Parameter(Mandatory = $true, ValueFromPipelineByPropertyName = $true)] [string[]] $Scope, [Parameter(Mandatory = $true, ValueFromPipelineByPropertyName = $true)] [ValidateSet('Delegated','Application')] [string] $Type, [Parameter(Mandatory = $true, ValueFromPipelineByPropertyName = $true)] [string] $Resource, [hashtable] $ServiceMap ) begin { $services = $script:serviceSelector.GetServiceMap($ServiceMap) Assert-EntraConnection -Service $services.Graph -Cmdlet $PSCmdlet $principals = @{ } } process { #region Resolve Scope Data $result = Resolve-ServicePrincipal -Identity $Resource -Cache $principals -Unique -Services $services if (-not $result.Success) { Write-Error -Message $result.Message return } $servicePrincipal = $result.Result $resolvedScopes = foreach ($entry in $Scope) { $scopeEntry = Resolve-Scope -Scope $entry -Resource $servicePrincipal.ID -Type $Type -Services $services if ($scopeEntry.ScopeName -eq '<not identified>') { Write-Error "Scope $entry of type $Type not found on Service Principal $($servicePrincipal.DisplayName) ($($servicePrincipal.ID) | $Resource)" continue } $scopeEntry } if (-not $resolvedScopes) { Write-Error -Message "No valid scopes found! Use 'Get-EAGScopeDefinition' to find the valid scopes for the resource and try again." return } #endregion Resolve Scope Data #region Resolve Application Data # Note: Can't cache, since previous process blocks might have affected the same object $result = Resolve-Application -DisplayName $DisplayName -ApplicationId $ApplicationId -ObjectId $ObjectId -Unique -Services $services if (-not $result.Success) { Write-Error $result.Message return } $application = $result.Result #endregion Resolve Application Data $body = @{ requiredResourceAccess = @() } $newAccess = [PSCustomObject]@{ resourceAppId = $servicePrincipal.AppId resourceAccess = @() } foreach ($access in $application.object.requiredResourceAccess) { if ($access.resourceAppId -ne $servicePrincipal.AppId) { $body.requiredResourceAccess += $access continue } foreach ($entry in $access.resourceAccess) { if ($entry.id -in $resolvedScopes.ID) { continue } $newAccess.resourceAccess += $entry } } if ($newAccess.resourceAccess.Count -gt 0) { $body.requiredResourceAccess += $newAccess } Write-Verbose ($body | ConvertTo-Json -Depth 99) if (-not $PSCmdlet.ShouldProcess($application.Id, "Removing scopes $($resolvedScopes.Value -join ', ')")) { return } try { $null = Invoke-EntraRequest -Method PATCH -Path "applications/$($application.Id)" -Body $body -Header @{ 'content-type' = 'application/json' } } catch { $PSCmdlet.WriteError($_) return } } } function Remove-EAGMsiScope { <# .SYNOPSIS Removes API permissions (scopes) from a Managed Service Identity. .DESCRIPTION The Remove-EAGMsiScope cmdlet removes application permissions (scopes) from a Managed Service Identity (MSI). This is useful when you need to revoke access to specific APIs or reduce the permissions of an MSI. Scopes Needed: Application.Read.All, AppRoleAssignment.ReadWrite.All .PARAMETER DisplayName The display name of the Managed Service Identity to remove permissions from. .PARAMETER ApplicationId The Application ID (Client ID) of the Managed Service Identity to remove permissions from. .PARAMETER ObjectId The Object ID of the Managed Service Identity to remove permissions from. .PARAMETER Scope The permission scopes to remove from the Managed Service Identity. These are the API permissions that will be revoked. .PARAMETER Resource The resource (API) to which the permissions/scopes apply. This can be specified as a display name, application ID, object ID or Service Principal Name. Examples: + 'Microsoft Graph' + '00000003-0000-0000-c000-000000000000' + 'https://graph.microsoft.com' .PARAMETER ServiceMap %SERVCICEMAP% .PARAMETER WhatIf If this switch is enabled, no actions are performed but informational messages will be displayed that explain what would happen if the command were to run. .PARAMETER Confirm If this switch is enabled, you will be prompted for confirmation before executing any operations that change state. .EXAMPLE PS C:\> Remove-EAGMsiScope -DisplayName "MyWebApp" -Resource "Microsoft Graph" -Scope "User.Read.All" Removes the User.Read.All application permission for Microsoft Graph from the MSI named "MyWebApp". .EXAMPLE PS C:\> Remove-EAGMsiScope -ApplicationId "11111111-1111-1111-1111-111111111111" -Resource "00000003-0000-0000-c000-000000000000" -Scope "User.Read.All", "Group.Read.All" Removes the User.Read.All and Group.Read.All application permissions for Microsoft Graph (identified by its app ID) from the MSI with the specified application ID. #> [CmdletBinding(DefaultParameterSetName = 'Filter', SupportsShouldProcess = $true)] param ( [Parameter(ParameterSetName = 'Filter', ValueFromPipelineByPropertyName = $true)] [string] $DisplayName, [Parameter(ParameterSetName = 'Filter', ValueFromPipelineByPropertyName = $true)] [Alias('AppId', 'ClientID')] [string] $ApplicationId, [Parameter(Mandatory = $true, ParameterSetName = 'Identity', ValueFromPipelineByPropertyName = $true)] [Alias('Id')] [string] $ObjectId, [Parameter(Mandatory = $true, ValueFromPipelineByPropertyName = $true)] [string[]] $Scope, [Parameter(Mandatory = $true, ValueFromPipelineByPropertyName = $true)] [string] $Resource, [hashtable] $ServiceMap ) begin { $services = $script:serviceSelector.GetServiceMap($ServiceMap) Assert-EntraConnection -Service $services.Graph -Cmdlet $PSCmdlet $principals = @{ } $servicePrincipals = @{} } process { #region Resolve Scope Data $result = Resolve-ServicePrincipal -Identity $Resource -Cache $principals -Unique -Services $services if (-not $result.Success) { Write-Error -Message $result.Message return } $servicePrincipal = $result.Result $resolvedScopes = foreach ($entry in $Scope) { $scopeEntry = Resolve-Scope -Scope $entry -Resource $servicePrincipal.ID -Type 'Application' -Services $services if ($scopeEntry.ScopeName -eq '<not identified>') { Write-Error "Scope $entry of type $Type not found on Service Principal $($servicePrincipal.DisplayName) ($($servicePrincipal.ID) | $Resource)" continue } $scopeEntry } if (-not $resolvedScopes) { Write-Error -Message "No valid scopes found! Use 'Get-EAGScopeDefinition' to find the valid scopes for the resource and try again." return } #endregion Resolve Scope Data #region Resolve Application Data $identity = $ObjectId if (-not $identity) { $identity = $ApplicationId } if (-not $identity) { $identity = $DisplayName } if (-not $identity) { Write-Error -Message "Managed Identity not specified! Provide at least one of ObjectId, ApplicationId or DisplayName." return } $result = Resolve-ServicePrincipal -Identity $identity -Properties id, appId, displayName -Cache $servicePrincipals -Unique -Services $services if (-not $result.Success) { Write-Error "Error resolving Managed Identity for $($identity):`n$($result.Message)" return } $appSPN = $result.Result #endregion Resolve Application Data $applicationGrants = Invoke-EntraRequest -Service $services.Graph -Path "servicePrincipals/$($appSPN.id)/appRoleAssignments" foreach ($resolvedScope in $resolvedScopes) { if ($resolvedScope.ID -notin $applicationGrants.appRoleId) { Write-Verbose "Skipping Application scope $($resolvedScope.Value) - not found on $($appSPN.DisplayName)" continue } if (-not $PSCmdlet.ShouldProcess("$($appSPN.DisplayName) ($($appSPN.AppID))", "Removing scope $($resolvedScope.Value) of resource $($resolvedScope.ResourceName)")) { continue } Write-Verbose "Processing scope:`n$($resolvedScope | ConvertTo-Json)" $grantToKill = $applicationGrants | Where-Object appRoleId -EQ $resolvedScope.ID Write-Verbose "Removing scope $($resolvedScope.id) ($($resolvedScope.Value))) from Managed Identity $($appSPN.appid) ($($appSPN.displayName))" try { $null = Invoke-EntraRequest -Method DELETE -Path "servicePrincipals/$($appSPN.id)/appRoleAssignments/$($grantToKill.id)" -Header @{ 'content-type' = 'application/json' } } catch { Write-Error $_ } } } } function Remove-EAGServicePrincipal { <# .SYNOPSIS Deletes Enterprise Applications / service principals from the connected Entra ID tenant. .DESCRIPTION Deletes Enterprise Applications / service principals from the connected Entra ID tenant. Scopes Needed: Application.ReadWrite.All .PARAMETER Id Object ID of the service principal to delete. .PARAMETER ServiceMap Optional hashtable to map service names to specific EntraAuth service instances. Used for advanced scenarios where you want to use something other than the default Graph connection. Example: @{ Graph = 'GraphBeta' } This will switch all Graph API calls to use the beta Graph API. .PARAMETER WhatIf If this switch is enabled, no actions are performed but informational messages will be displayed that explain what would happen if the command were to run. .PARAMETER Confirm If this switch is enabled, you will be prompted for confirmation before executing any operations that change state. .EXAMPLE PS C:\> Get-EAGServicePrincipal -DisplayName "MyWebApp" | Remove-EAGServicePrincipal Deletes the service principal with the display name "MyWebApp". #> [CmdletBinding(SupportsShouldProcess = $true)] param ( [Parameter(Mandatory = $true, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true)] [string[]] $Id, [hashtable] $ServiceMap = @{} ) begin { $services = $script:serviceSelector.GetServiceMap($ServiceMap) Assert-EntraConnection -Service $services.Graph -Cmdlet $PSCmdlet } process { foreach ($entry in $Id) { if (-not $PSCmdlet.ShouldProcess($entry, "Delete Service Principal")) { continue } try { Invoke-EntraRequest -Service $services.Graph -Method DELETE -Path "servicePrincipals/$entry" } catch { $PSCmdlet.WriteError($_) continue } } } } function Revoke-EAGScopeConsent { <# .SYNOPSIS Revokes previously granted consent for scopes on an App Registration. .DESCRIPTION Revokes previously granted consent for scopes on an App Registration. Consent is required for scopes configured on an app registration to take effect in the tenant. Scopes Needed: Application.Read.All, AppRoleAssignment.ReadWrite.All .PARAMETER DisplayName Displayname of the app registration whose scopes to revoke consent for. .PARAMETER ApplicationId Application ID (Client ID) of the app registration whose scopes to revoke consent for. .PARAMETER ObjectId Object ID of the app registration whose scopes to revoke consent for. .PARAMETER Scope The permission scopes to revoke consent for. .PARAMETER Type Type of the permission scopes to revoke consent for. Valid Options: - Delegated: Permissions that apply to interactive sessions, where the application acts on behalf of the signed-in user. - Application: Permissions that apply to unattended sessions, where the application acts as itself. .PARAMETER Resource The resource (API) to which the permissions/scopes apply. This can be specified as a display name, application ID, object ID or Service Principal Name. Examples: + 'Microsoft Graph' + '00000003-0000-0000-c000-000000000000' + 'https://graph.microsoft.com' .PARAMETER ServiceMap Optional hashtable to map service names to specific EntraAuth service instances. Used for advanced scenarios where you want to use something other than the default Graph connection. Example: @{ Graph = 'GraphBeta' } This will switch all Graph API calls to use the beta Graph API. .PARAMETER WhatIf If this switch is enabled, no actions are performed but informational messages will be displayed that explain what would happen if the command were to run. .PARAMETER Confirm If this switch is enabled, you will be prompted for confirmation before executing any operations that change state. .EXAMPLE PS C:\> Revoke-EAGScopeConsent -DisplayName "MyWebApp" -Resource "Microsoft Graph" -Scope "User.Read.All" -Type Application Revokes consent for the User.Read.All application permission for Microsoft Graph from the app registration named "MyWebApp". #> [CmdletBinding(DefaultParameterSetName = 'Filter', SupportsShouldProcess = $true)] param ( [Parameter(ParameterSetName = 'Filter', ValueFromPipelineByPropertyName = $true)] [string] $DisplayName, [Parameter(ParameterSetName = 'Filter', ValueFromPipelineByPropertyName = $true)] [Alias('AppId', 'ClientID')] [string] $ApplicationId, [Parameter(Mandatory = $true, ParameterSetName = 'Identity', ValueFromPipelineByPropertyName = $true)] [Alias('Id')] [string] $ObjectId, [Parameter(Mandatory = $true, ValueFromPipelineByPropertyName = $true)] [string[]] $Scope, [Parameter(Mandatory = $true, ValueFromPipelineByPropertyName = $true)] [ValidateSet('Delegated', 'Application')] [string] $Type, [Parameter(Mandatory = $true, ValueFromPipelineByPropertyName = $true)] [string] $Resource, [hashtable] $ServiceMap ) begin { $services = $script:serviceSelector.GetServiceMap($ServiceMap) Assert-EntraConnection -Service $services.Graph -Cmdlet $PSCmdlet $principals = @{ } $applications = @{ } $servicePrincipals = @{ } } process { #region Resolve Scope Data $result = Resolve-ServicePrincipal -Identity $Resource -Cache $principals -Unique -Services $services if (-not $result.Success) { Write-Error -Message $result.Message return } $servicePrincipal = $result.Result $resolvedScopes = foreach ($entry in $Scope) { $scopeEntry = Resolve-Scope -Scope $entry -Resource $servicePrincipal.ID -Type $Type -Services $services if ($scopeEntry.ScopeName -eq '<not identified>') { Write-Error "Scope $entry of type $Type not found on Service Principal $($servicePrincipal.DisplayName) ($($servicePrincipal.ID) | $Resource)" continue } $scopeEntry } if (-not $resolvedScopes) { Write-Error -Message "No valid scopes found! Use 'Get-EAGScopeDefinition' to find the valid scopes for the resource and try again." return } #endregion Resolve Scope Data #region Resolve Application Data $result = Resolve-Application -DisplayName $DisplayName -ApplicationId $ApplicationId -ObjectId $ObjectId -Cache $applications -Unique -Services $services if (-not $result.Success) { Write-Error $result.Message return } $application = $result.Result $result = Resolve-ServicePrincipal -Identity $application.AppID -Properties id -Cache $servicePrincipals -Unique -Services $services if (-not $result.Success) { Write-Error "Error resolving Enterprise Application for $($application.AppID):`n$($result.Message)" return } $appSPN = $result.Result #endregion Resolve Application Data $applicationGrants = Invoke-EntraRequest -Service $services.Graph -Path "servicePrincipals/$($appSPN.id)/appRoleAssignments" $delegatedGrants = Invoke-EntraRequest -Service $services.Graph -Path 'oauth2PermissionGrants' -Query @{ '$filter' = "clientId eq '$($appSPN.id)' and consentType eq 'AllPrincipals'" } $oldDelegateGrants = @() foreach ($resolvedScope in $resolvedScopes) { if ($resolvedScope.Type -eq 'Application' -and $resolvedScope.ID -notin $applicationGrants.appRoleId) { Write-Verbose "Skipping Application scope $($resolvedScope.Value) - no consent found for $($application.DisplayName)" continue } if ($resolvedScope.Type -eq 'Delegated' -and $resolvedScope.Value -notin @($delegatedGrants.scope -split ' ').ForEach{ $_.Trim() }) { Write-Verbose "Skipping Delegated scope $($resolvedScope.Value) - no consent found for $($application.DisplayName)" continue } if (-not $PSCmdlet.ShouldProcess("$($application.DisplayName) ($($application.AppID))", "Revoke consent for scope $($resolvedScope.Value) of resource $($resolvedScope.ResourceName)")) { continue } Write-Verbose "Processing scope:`n$($resolvedScope | ConvertTo-Json)" switch ($resolvedScope.Type) { 'Application' { $toRevoke = $applicationGrants | Where-Object appRoleId -EQ $resolvedScope.ID Write-Verbose "Revoking Admin consent for scope $($resolvedScope.id) ($($resolvedScope.Value))) on $($appSPN.appid) ($($appSPN.displayName))" try { $null = Invoke-EntraRequest -Method DELETE -Path "servicePrincipals/$($appSPN.id)/appRoleAssignments/$($toRevoke.id)" -Header @{ 'content-type' = 'application/json' } } catch { Write-Error $_ } } 'Delegated' { $oldDelegateGrants += $resolvedScope } default { Write-Error "Unexpected scope type: $($resolvedScope.Type)" } } } if (-not $oldDelegateGrants) { return } $byResource = $oldDelegateGrants | Group-Object Resource foreach ($group in $byResource) { $applicableGrant = $delegatedGrants | Where-Object resourceId -eq $group.Name $survivingScopes = @($applicableGrant.Scope -split " ").ForEach{ $_.Trim() } | Where-Object { $_ -notin $group.Group.Value } Write-Verbose "Revoking Admin consent for scope(s) $($group.Group.Value -join ', ') on $($appSPN.appid) ($($appSPN.displayName))" if (-not $survivingScopes) { try { $null = Invoke-EntraRequest -Method DELETE -Path "oauth2PermissionGrants/$($applicableGrant.id)" -Header @{ 'content-type' = 'application/json' } } catch { Write-Error $_ } continue } $grant = @{ scope = $survivingScopes -join " " } try { $null = Invoke-EntraRequest -Method 'PATCH' -Path "oauth2PermissionGrants/$($applicableGrant.id)" -Body $grant -Header @{ 'content-type' = 'application/json' } } catch { Write-Error $_ } } } } class FilterBuilder { [System.Collections.ArrayList]$Entries = @() [string]$CustomFilter [void]Add([string]$Property, [string]$Operator, $Value) { $null = $this.Entries.Add( @{ Property = $Property Operator = $Operator Value = $Value } ) } [int]Count() { $myCount = $this.Entries.Count if ($this.CustomFilter) { $myCount++ } return $myCount } [string]Get() { $segments = foreach ($entry in $this.Entries) { $valueString = $entry.Value -as [string] if ($null -eq $entry.Value) { $valueString = "''" } if ($entry.Value -is [string]) { $valueString = "'$($entry.Value)'" if ($entry.Value -match '\*$' -and $entry.Operator -eq 'eq') { "startswith($($entry.Property), '$($entry.Value.TrimEnd('*'))')" continue } } '{0} {1} {2}' -f $entry.Property, $entry.Operator, $valueString } if ($this.CustomFilter) { if ($segments) { $segments = @($segments) + $this.CustomFilter } else { $segments = $this.CustomFilter } } return $segments -join ' and ' } } class ServiceSelector { [string]GetService([hashtable]$ServiceMap, [string]$Name) { if ($ServiceMap[$Name]) { return $ServiceMap[$Name] } return $script:_services[$Name] } [hashtable]GetServiceMap([hashtable]$ServiceMap) { $map = $script:_services.Clone() if ($ServiceMap) { foreach ($pair in $ServiceMap.GetEnumerator()) { $map[$pair.Key] = $pair.Value } } return $map } } # Graph Request Configuration $script:_services = @{ Graph = 'Graph' GraphBeta = 'GraphBeta' } $script:serviceSelector = [ServiceSelector]::new() # Caches for frequent lookups $script:cache = @{ ServicePrincipalByAppID = @{} ServicePrincipalByID = @{} ScopesByID = @{} ResolvedScopes = @{} Principals = @{} } |