Grant-MIGraphPermission.ps1

<#PSScriptInfo

.VERSION 1.0.6

.GUID 0b801f6d-e4f2-4968-a5d2-d959dc0dd7c5

.AUTHOR Elliot Huffman

.COMPANYNAME

.COPYRIGHT Elliot Huffman 2022

.TAGS Azure AD AAD IAM Identity_And_Access_Management MI Managed_Identity

.LICENSEURI https://github.com/elliot-huffman/Powershell-Doodads/blob/main/LICENSE

.PROJECTURI

.ICONURI

.EXTERNALMODULEDEPENDENCIES Microsoft.Graph.Authentication,Microsoft.Graph.Applications 

.REQUIREDSCRIPTS

.EXTERNALSCRIPTDEPENDENCIES

.RELEASENOTES
1.0.6: Change to Microsoft.Graph.Beta to support new features.
1.0.5: Disable access token validation since it is not working with Install-PSM. Will be re-enabled later.
1.0.4: Fix a bug where the Get-MgServicePrincipal changed requiring the use of a switch type for the 'All' parameter.

.PRIVATEDATA

#> 

#Requires -Module Microsoft.Graph.Authentication
#Requires -Module Microsoft.Graph.Beta.Applications

# Ensure the appropriate pre-requirements for the script


<#
.SYNOPSIS
    Grants Graph API Permissions to Managed Identity Service Principals
.DESCRIPTION
    Grants API permissions to managed identities. The default setting is the MS Graph API but other APIs registered in Azure AD are supported. Such as MDE, EXO, etc.
    Returns false on failure
.EXAMPLE
    PS C:\> Grant-MIGraphPermission
    Launches the GUI to walk the user through picking out the API permissions to grant to a Managed Identity
.PARAMETER CLIMode
    This switch forces the suppression of GUI elements and forces headless mode.
    This is useful if used in an automation system where a GUI will gum up the works.
    Errors will be thrown if a required param is not specified in CLI only mode.
.PARAMETER ObjectID
    This is the identity that is going to have the permission granted to it.
    By default the GUI returns a list of managed identities however this can be any service principal.
.PARAMETER PermissionName
    This is the display name of the permission the be granted to the target ObjectID.
.PARAMETER GraphServicePrincipalID
    This is the GUID of the service principal that is the permissions provider.
    By default the service provider is the Microsoft Graph API, however you can grant permissions on other providers too by providing their GUID.
    Common providers are as below:
        - Microsoft Graph API: 00000003-0000-0000-c000-000000000000
        - Defender for Endpoint: fc780465-2017-40d4-a0c5-307022471b92
        - Defender for Cloud Apps: 05a65629-4c1b-48c1-a78b-804c4abdd4af
        - Exchange Online: 00000002-0000-0ff1-ce00-000000000000
        - SharePoint Online: 00000003-0000-0ff1-ce00-000000000000
        - Yammer: 00000005-0000-0ff1-ce00-000000000000
        - Universal Print: da9b70f6-5323-4ce6-ae5c-88dcc5082966
.PARAMETER AccessToken
    This parameter is used to pass an access token into this script rather than going through the authentication process via GUI.
    This is useful for fully automated processes that are able to provide their own access tokens and run this script without human interaction.
    
    The audience should be "https://graph.microsoft.com" for the token, otherwise it won't work.
    There is input validation to help catch access tokens that don't have the correct audience.
    
    The access token should minimally have the scopes (permissions) of 'Directory.Read.All', 'AppRoleAssignment.ReadWrite.All', and 'Application.ReadWrite.All'.
    Scopes that have these basic set of permissions or greater will work (e.g. Global Admin).
    
    Example use cases:
        - CI/CD Pipeline
        - Dot Sourced Loading this script from another
.INPUTS
    Switch
    System.GUID
    System.GUID[]
    System.String
    System.String[]
.OUTPUTS
    System.Boolean
.NOTES
    This script requires the Microsoft.Graph.Authentication and Microsoft.Graph.Applications modules to be installed before execution.
    If the GUI mode is to be used, ISE must be installed as some Windows Forms components are included in ISE that this script uses (Out-GridView).

    This script requires the minimum Azure AD permissions of:
        - Directory.Read.All
        - AppRoleAssignment.ReadWrite.All
        - Application.ReadWrite.All
    These permission may be granted by a more widely scoped permission such as "Global admin" or "Directory.ReadWrite.All", etc..
#>

# Cmdlet bind script so that it can perform advanced operations
[CmdletBinding(
    DefaultParameterSetName = 'GUI Mode',
    SupportsShouldProcess = $true
)]

# Initialize the parameters for the script
param(
    [Parameter(
        Mandatory = $true,
        Position = 0,
        ParameterSetName = 'CLI Mode'
    )]
    [Switch]$CLIMode,
    [Parameter(
        Mandatory = $true,
        Position = 1,
        ValueFromPipeline = $true,
        ValueFromPipelineByPropertyName = $true,
        ParameterSetName = 'CLI Mode'
    )]
    [Parameter(ParameterSetName = 'GUI Mode')]
    [ValidateNotNullOrEmpty()]
    [System.GUID[]]$ObjectID,
    [Parameter(
        Mandatory = $true,
        Position = 2,
        ValueFromPipeline = $true,
        ValueFromPipelineByPropertyName = $true,
        ParameterSetName = 'CLI Mode'
    )]
    [Parameter(ParameterSetName = 'GUI Mode')]
    [ValidateNotNullOrEmpty()]
    [System.String[]]$PermissionName,
    [ValidateNotNullOrEmpty()]
    [System.GUID]$GraphServicePrincipalID = '00000003-0000-0000-c000-000000000000',
    # [ValidateScript({ ([System.Text.Encoding]::ASCII.GetString([System.Convert]::FromBase64String(($_ -split '\.')[1])) | ConvertFrom-Json).aud -eq 'https://graph.microsoft.com' })]
    [System.Security.SecureString]$AccessToken
)

# Initialize processing
begin {
    # Stop execution on error
    $ErrorActionPreference = 'Stop'

    # Write Verbose info
    Write-Verbose -Message 'Logging into Azure AD'
    
    # Check if an access token has been provided
    if ($null -ne $AccessToken) {
        # Log into the Graph API using the provided access token
        Connect-MgGraph -AccessToken $AccessToken
    } else {
        # Log into the Graph API using Azure AD authentication
        Connect-MgGraph -Scopes 'Directory.Read.All', 'AppRoleAssignment.ReadWrite.All', 'Application.ReadWrite.All'
    }

    # Write Verbose info
    Write-Verbose -Message 'Calculating GUI or CLI mode'

    # Check to see if GUI mode is forced or necessary
    if ($CLIMode) {
        # If CLI mode is $true, the operator is forcing the execution of no GUI in headless only
        [System.Boolean]$GUIMode = $false
    } elseif (!$ObjectID -or !$PermissionName) {
        # If the ObjectID or PermissionName parameters are not specified and the script is not forced CLI only, GUI is implied.
        [System.Boolean]$GUIMode = $true
    } else {
        # If the parameters are present as expected, set the GUI mode to be off as no user selection is necessary.
        [System.Boolean]$GUIMode = $false
    }
}

# Process each object passed on the command line
process {
    # Write Verbose info
    Write-Verbose -Message 'Getting an instance of the Graph API App Service Principal'

    # Get the GraphAPI instance
    [Microsoft.Graph.Beta.PowerShell.Models.MicrosoftGraphServicePrincipal]$GraphAppSP = Get-MgBetaServicePrincipal -Filter "AppID eq '$GraphServicePrincipalID'"

    # Write debug info
    Write-Debug -Message "$(Get-Date -Format 'HH:mm:ss') - Graph API SP Info:"
    Write-Debug -Message "$(Get-Date -Format 'HH:mm:ss') - `$GraphAppSP: $GraphAppSP"

    # If in GUI mode
    if ($GUIMode) {
        # Write Verbose info
        Write-Verbose -Message 'Getting a list of all managed identities and render it in a picker dialog for the end user to select one.'

        # Get a list of Managed Identities and make the user select one of them
        [Microsoft.Graph.Beta.PowerShell.Models.MicrosoftGraphServicePrincipal[]]$SelectedPrincipalList = Get-MgBetaServicePrincipal -Filter "ServicePrincipalType eq 'ManagedIdentity'" -All | Out-GridView -Title 'Select the Managed Identity to Assign Permission' -OutputMode 'Multiple'
    } else {
        # Write Verbose info
        Write-Verbose -Message 'Getting the specified service principal.'

        # Loop through each ID specified and save the results into a new list.
        foreach ($GUID in $ObjectID) {
            # Pull the specified Object ID's graph object
            [Microsoft.Graph.Beta.PowerShell.Models.MicrosoftGraphServicePrincipal[]]$SelectedPrincipalList += Get-MgBetaServicePrincipal -ServicePrincipalId $GUID
        }
    }

    # Write debug info
    Write-Debug -Message "$(Get-Date -Format 'HH:mm:ss') - Selected Principal List:"
    Write-Debug -Message "$(Get-Date -Format 'HH:mm:ss') - `$SelectedPrincipal: $SelectedPrincipalList"

    # Write Verbose info
    Write-Verbose -Message 'Validating principal selection was successful'
        
    # Throw an error and end execution if the end user doesn't select an object
    if (($null -eq $SelectedPrincipalList) -or ($SelectedPrincipalList.Count -eq 0)) {
        # Write an error to the console
        Write-Error -Message 'No principals were selected successfully.
        If GUI was used, this usually indicates that the end user closed the dialog.
        If CLI was used, ths was most likely due to an incorrect GUID.'

        # Return false to the caller to indicate failure
        return $false
    }

    # Route execution based on GUI mode
    if ($GUIMode) {
        # Write Verbose info
        Write-Verbose -Message 'Getting a list of all app roles/permissions and render it in a picker dialog for the end user to select one.'

        # Get the specified permission that needs to be assigned
        [Microsoft.Graph.Beta.PowerShell.Models.MicrosoftGraphAppRole[]]$AppRoleList = $GraphAppSP.AppRoles | Out-GridView -Title 'Select the Permission to Assign' -OutputMode 'Multiple'
    } else {
        # Write Verbose info
        Write-Verbose -Message 'Getting the specified app role/permission'

        # Loop through each permission requested and enrich the permission provided with system context
        foreach ($RoleName in $PermissionName) {
            # Add each context instance to the app role list
            [Microsoft.Graph.Beta.PowerShell.Models.MicrosoftGraphAppRole[]]$AppRoleList += $GraphAppSP.AppRoles | Where-Object -FilterScript { $_.Value -eq $RoleName }
        }         
    }

    # Write debug info
    Write-Debug -Message "$(Get-Date -Format 'HH:mm:ss') - List of selected app roles/permissions:"
    Write-Debug -Message "$(Get-Date -Format 'HH:mm:ss') - `$AppRoleList: $AppRoleList"


    # Write Verbose info
    Write-Verbose -Message 'Validating role selection was successful'

    # Throw an error and end execution if the end user doesn't select an object
    if (($null -eq $AppRoleList) -or ($AppRoleList.Count -eq 0)) {
        # Write an error to the console
        Write-Error -Message 'No API roles were selected successfully.
        If GUI was used, this usually indicates that the end user closed the dialog.
        If CLI was used, ths was most likely due to an incorrect permission name being specified.'

        # Return false to the caller to indicate failure
        return $false
    }

    # Write Verbose info
    Write-Verbose -Message 'Assigning the specified permission to the specified principal'

    # Loop through each principal specified and perform the specified role assignment
    foreach ($Principal in $SelectedPrincipalList) {
        # Loop through each of the selected app roles and assign the role to the specified principal
        foreach ($Role in $AppRoleList) {
            # Simulate the result if asked to simulate
            if ($PSCmdlet.ShouldProcess('Selected Service Principal', "Grant $($Role.Value)")) {
                # Write debug info
                Write-Debug -Message "$(Get-Date -Format 'HH:mm:ss') - Pre-Assignment Variable Dump:"
                Write-Debug -Message "$(Get-Date -Format 'HH:mm:ss') - `$Principal.ObjectId: $($Principal.Id)"
                Write-Debug -Message "$(Get-Date -Format 'HH:mm:ss') - `$GraphAppSP.ObjectId: $($GraphAppSP.Id)"
                Write-Debug -Message "$(Get-Date -Format 'HH:mm:ss') - `$Role.Id: $($Role.Id)"

                # Assign the Graph API permission to the specified service principal
                New-MgBetaServicePrincipalAppRoleAssignment -PrincipalId $Principal.Id -ServicePrincipalId $Principal.Id -AppRoleId $Role.Id -ResourceId $GraphAppSP.Id
            }
        }
    }
}

# Run the necessary cleanup commands after processing is complete
end {
    # Log out of the session
    Disconnect-MgGraph
}