Update-JiraUsersForSSO.ps1

# Name: Update-JiraUsersForSSO.ps1
# Author: James Schlackman
# Last Modified: Apr 9 2024

# Searches for and updates Jira users in preparation for SSO by changing their login name to match their email address.

#Requires -Modules JiraPS

Param(
    # Jira server to connect to
    [Parameter(Mandatory=$true)] [string]$ServerUri,
    # User search filter. Uses the same syntax as searches within the user management section of Jira.
    [Parameter(Mandatory=$true)] [string]$UserFilter,
    # If true, confirm update to each individual user. If false, batch process all users selected for update without additional confirmation.
    [Parameter()] [bool]$ConfirmChanges = $false,
    # By default, the user account used to authenticate to the API will be excluded from any change operations to prevent the login token from being expired.
    [Parameter()] [bool]$SkipAuthenticatedUser = $true
)

Import-Module JiraPS

Function Connect-JiraServer {
    Param(
        [Parameter(Mandatory=$true)] [string]$ServerUri
    )

    # Clean up server parameter
    $ServerUri = $ServerUri.Trim().TrimEnd('/').ToLower()

    # Default to https:// if protocol not specified
    If ($ServerUri -notmatch '^http(s)?:\/\/') {
        $ServerUri = "https://$ServerUri"
    }
    
    # Check for a current connection
    $currentServer = Get-JiraServerInfo -ErrorAction SilentlyContinue

    # If already connected to the correct server, return immediately
    If ($currentServer.BaseURL -eq $ServerUri) {

        Write-Host ($currentServer | Out-String)
        Return $currentServer

    } Else {

        # Set the server Uri
        Set-JiraConfigServer -Server $ServerUri

        # Get new credentials
        Do {
            $newCred = $null
            $newCred = Get-Credential
        
            # Test provided credentials
            If ($newCred) {
                $serverInfo = Get-JiraServerInfo -Credential $newCred
            } Else {
                $serverInfo = $null
            }
        } Until (![bool]$newCred -or $serverInfo)

        # If we got server info successfully, start a session with those credentials
        If ($serverInfo) {
            New-JiraSession -Credential $newCred

            Write-Host "`nConnection established." -ForegroundColor Green
            Write-Host ($serverInfo | Out-String)

            Return $serverInfo
        } Else {
            Return $null
        }
    }
}

# Attempt to connect to the server and process users
If (Connect-JiraServer -ServerUri $ServerUri) {

    If (!$SkipAuthenticatedUser) {
        Write-Warning 'Authenticated user is NOT being skipped during updates. If credentials are modified during batch update, all subsequent API operations will fail.'
    }

    Write-Host 'Finding users that match ' -NoNewline
    Write-Host $UserFilter -ForegroundColor Cyan -NoNewline
    Write-Host '...'

    $candidateUsers = Get-JiraUser -UserName $UserFilter -MaxResults 1000

    If ($candidateUsers) {

        Write-Host ('Matching users: {0}' -f @($candidateUsers).Count)
        
        If (@($candidateUsers).Count -eq 1000) {
            Write-Host 'NOTE: Maximum number of users supported by API queries has been reached. Additional users may match the specified query.'
        }
        Write-Host 'Review grid output and select users to update.'

        # Show grid for selection
        $changeUsers = $candidateUsers| Select Name,DisplayName,EmailAddress,Active,@{Name='Groups';Expression={($_.Groups -join ', ')}} | Out-GridView -Title 'Select Jira users to update' -OutputMode Multiple
        
        If ($SkipAuthenticatedUser) {
            $changeUsers = $changeUsers | Where-Object -Property Name -ne (Get-JiraSession).Username
        }

        Write-Host ('Users selected for update: {0}' -f @($changeUsers).Count)
               
        $jobActivity = 'Updating users...'

        # Process selected users
        For ($changeIndex = 0; $changeIndex -lt @($changeUsers).Count; $changeIndex++ ) {
            
            $changeUser = @($changeUsers)[$changeIndex]

            # Post job progress
            Write-Progress -Activity $jobActivity -CurrentOperation $changeUser.Name -PercentComplete ($changeIndex / @($changeUsers).Count * 100)

            # Make sure the user confirms the change if required
            $changeConfirmed = !$ConfirmChanges


            # If the username and email already match, skip this user
            If ($changeUser.Name -eq $changeUser.EmailAddress) {

                Write-Verbose "Skipping name update for user $($changeUser.Name), login name already matches email."

            } Else {
                # If the username does not match, update it
                $changeDetail = @{name = $changeUser.EmailAddress}

                # Write a summary of the changes to be submitted and ask for confirmation if required
                If ($changeConfirmed) {

                    Write-Verbose ('Username for {0} changing from {1} to {2}' -f $changeUser.DisplayName, $changeUser.Name, $changeDetail.name)

                } Else {

                    Write-Host ("`nUsername for {0} will change from " -f $changeUser.DisplayName) -NoNewline
                    Write-Host $changeUser.Name -ForegroundColor Cyan -NoNewline
                    Write-Host ' to ' -NoNewline
                    Write-Host $changeDetail.Name -ForegroundColor Cyan
                
                    $changeConfirmed = (Read-Host 'Proceed? [y/N]').Trim().ToUpper() -eq 'Y'

                }
        
                # Once the change is confirmed
                If ($changeConfirmed)
                {
                    # Submit the change to the server
                    $changeResult = Set-JiraUser -User $changeUser.Name -Property $changeDetail -PassThru
                        
                    # Report result
                    If ($changeResult -and ($changeResult.Name -eq $changeResult.EmailAddress)) {

                        If ($ConfirmChanges) {
                            Write-Host 'User update succeeded.' -ForegroundColor Green
                        } Else {
                            Write-Verbose 'User update succeeded.'
                        }
                        Write-Debug $changeResult

                    } Else {

                        Write-Host ('{0} - ' -f $changeUser.Name) -NoNewline
                        Write-Host 'User update FAILED.' -ForegroundColor Red

                    }
                }
            }
        }
        # Mark job completed
        Write-Progress -Activity $jobActivity -Completed
    }
}