MSOLLicenseManagement.psm1
|
#========================== # Utility Functions #========================== # Writes output to a log file with a time date stamp Function Write-Log { Param ([string]$string) # Get the current date [string]$date = Get-Date -Format G # Write everything to our log file ( "[" + $date + "] - " + $string) | Out-File -FilePath $LogFile -Append # If NonInteractive true then suppress host output if (!($NonInteractive)) { ( "[" + $date + "] - " + $string) | Write-Host } } # Make sure that we are connected to the MSOL Server if not connect us #TODO: Need to move from $error.clear() to try-catch Function Test-MSOLServiceConnection { # Set the Error Action Prefernce to stop $ErrorActionPreference = "Stop" # Log out some basic information since we run this at the begining of every cmdlet Write-Log ('Module version ' + (Get-Module MSOLLicenseManagement | sort-object -Property version -Descending)[0].version.tostring()) Write-Log ('Invocation ' + $PSCmdlet.MyInvocation.line) # Make sure that the MSOL Module is installed if ($null -eq (Get-Module -ListAvailable MSOnline)) { Write-Error "MSOL Module Not installed. Please install from https://docs.microsoft.com/en-us/office365/enterprise/powershell/connect-to-office-365-powershell" -ErrorAction Stop } # Make sure we are connected to the MSOL service $error.clear() # Call Get-msolaccountsku if we are not connected we will get an error if we are we will not $null = Get-MSOLAccountSKU -ErrorVariable error -ErrorAction SilentlyContinue # Check to see if we threw an error if ($error.count -gt 0) { # If we have the expected error for not being connected the call connect-msolservice if ($error.Exception -like "*You must call the Connect-MsolService cmdlet*") { Write-Log "Not Connected to MSOLService calling Connect-MSOLService" import-module MSOnline Connect-MsolService } # If we get any other error then throw and error and stop else { Write-log ("Unexpected Error encountered" + $error) Write-Error "Unexpected Error stopping execution" -ErrorAction Stop } } else { # Do nothing because we are connected } } # Updates a progress bar Function Update-Progress { Param ( [Parameter(Mandatory = $true)] [int]$CurrentCount, [Parameter(Mandatory = $true)] [int]$MaxCount, [Parameter(Mandatory = $true)] [string]$Message ) # If currentcount = maxcount we are done so we need to kill the progress bar if ($CurrentCount -ge $MaxCount) { Write-Progress -Completed -Activity "User Modification" } # Every 25 update the progress bar elseif ($CurrentCount % 25 -eq 0) { [int]$Percent = (($CurrentCount / $MaxCount) * 100) [string]$Operation = ([string]$Percent + "% " + $Message) Write-Progress -Activity "User Modification" -CurrentOperation $Operation -PercentComplete $Percent } else { # Nothing to do if not divisible by 25 } } # Test the logfile path to ensure the dir exists and that a file was provided Function Test-LogPath { param ( # Log File e.g. c:\temp\out.log [Parameter(Mandatory)] [string] $LogFile ) #Get the parent of the provided path $parent = split-path $LogFile -Parent # If the parent is null then the user provided the root of a drive for the log file if ([string]::IsNullOrEmpty($parent)) { Write-Error -Message "Log File path appears to be a drive root. Please provide a folder and file name with -logfile e.g. C:\Temp\out.log" -ErrorAction Stop break } # Verify that the parent folder exists since we won't create it if it doesn't if (!(test-path $parent)) { Write-Error -Message ("Path not found " + $parent + " ;please provide a valid path.") -ErrorAction Stop break } # Check to make sure the path contains a file with an extension if ((($LogFile).split('\'))[-1] -notmatch '\.') { Write-Error -Message ("Log file path does not appear to contain a file extension. Please provide a path and file name e.g. c:\temp\out.log") break } # Check to see if the value passed in a container (folder) if so we need to abort if (test-path $LogFile -PathType Container) { Write-Error -Message "Log File Path appears to be a folder. Please provide a file name with -logfile e.g. C:\Temp\out.log" -ErrorAction Stop break } } # Determine if we have an array with UPNs or just a single UPN / UPN array unlabeled Function Test-UserObject { param ([array]$ToTest) # See if we can get the UserPrincipalName property off of the input object # If we can't get the property then test the input and see if we can generate an acceptable object array if ($null -eq $ToTest[0].UserPrincipalName) { # Very basic check to see if this is a UPN # This deals with the input user@company.com,user2@company.com .... if ($ToTest[0] -match '@') { [array]$Output = $ToTest | Select-Object -Property @{Name = "UserPrincipalName"; Expression = { $_ } } Return $Output } # If we couldn't find the UserPrincipalName and we didn't see an @ sign then we need to abort else { Write-Log "[ERROR] - Unable to determine if input is a UserPrincipalName" Write-Log "Please provide a UPN or array of objects with the property UserPrincipalName populated" Write-Error "Unable to determine if input is a User Principal Name" -ErrorAction Stop } } # If we can pull the value of UserPrincipalName then just return the same object back else { Return $ToTest } } # Convert SkuID into Common Name Function Get-SKUCommonName { param ( [Parameter(Mandatory = $true)] [string]$Skuid, [Parameter(Mandatory = $true)] [array]$SkuArray ) # Find the Common name from the SkuID [string]$CN = ($Skuarray | where-object { $_.skuid -eq $Skuid }).CommonName # If we can't find the SkuID then we set it to "Not found" if ([string]::IsNullOrEmpty($CN)) { [string]$CN = "Not Found" } Return $CN } #========================== # Common SKU Related Functions #========================== # Validate we have provided a valid SKU or collect one if we have provided none Function Select-SKU { param ( [string]$SKUToCheck, [string]$Message ) # If we don't have a value for the SKU then we need to ask for one. if ([string]::IsNullOrEmpty($SKUToCheck)) { Write-Log ("No SKU value provided. Please select from the availible account SKUs") # Setup a counter $i = 1 # Write out the provided message Write-Host "`n$Message`n" # Get all of the SKUs and display them with a "selection number" $TenantSKU = Get-MSOLAccountSKU ForEach ($sku in $TenantSKU) { Write-Host ([string]$i + " - " + $sku.SKUPartNumber) $i++ } # Collect the selected item from the user [int]$Selected = 0 While (($Selected -ge $i) -or ($Selected -le 0) -or ($null -eq $Selected)) { [int]$Selected = Read-Host ("`nSelect the Number for the SKU to use.") } Return ($TenantSKU[$Selected - 1].AccountSkuID) } # We need to verify that the submitted SKU is valid else { Write-Log ("Verifying SKU " + $SKUToCheck) # If we can't find it then throw and error and abort if ($null -eq (Get-MSOLAccountSKU | Where-Object { $_.AccountSKUID -eq $SKUToCheck })) { Write-Log ("[ERROR] - Did not find SKU with ID: " + $SKUToCheck) Write-Error ("Unable to locate SKU " + $SKUToCheck) -ErrorAction Stop } # If we found it log it else { Write-Log ("Found SKU") Return $SKUToCheck.ToUpper() } } } # sets list of enabled plans to provided list Function Set-EnabledPlan { param ( [string]$SKU, [string[]]$PlansToEnable ) Write-Log "Determining plans to Disable" [string[]]$Output = (Get-MsolAccountSku | Where-Object { $_.accountskuid -eq $SKU }).servicestatus.serviceplan.servicename Foreach ($PlanToRemove in $PlansToEnable) { # Take out each of the plans that were provided to us $Output = $Output | Where-Object { $_ -ne $PlanToRemove } } Return $Output } # Creates the LicenseOptions variable for setting diabled plans Function Set-LicenseOption { param ( [string[]]$DisabledPlansArray, [Parameter(Mandatory = $true)] [string]$SKU ) # if there are no plans to disable we create the default option set if ($null -eq $DisabledPlansArray) { Write-log "Setting all SKU Plans to Enabled" $licenseOptions = New-MsolLicenseOptions -AccountSKUId $SKU } # Otherwise add the disabled plans to the option set else { Write-Log "Setting Disabled Plans License Options" Write-Log ("Disabled Plans: " + $DisabledPlansArray) $licenseOptions = New-MsolLicenseOptions -AccountSKUId $SKU -DisabledPlans $DisabledPlansArray } Return $licenseOptions } # Tests a list of plans agiast availible plans in the SKU # Return the first plan that fails or null Function Test-Plan { param ( [string[]]$Plan, [string]$Sku ) Write-Log "Validating Provided Plans" $PlansInSKU = (Get-MsolAccountSku | Where-Object { $_.accountskuid -eq $sku }).servicestatus.serviceplan.servicename # Take each of the provided plans and check it against the plans we found in the SKU foreach ($PlanToCheck in $Plan) { if ($PlansInSKU -contains $PlanToCheck) { } # If we don't find it then throw an error and stop else { Write-Log ("[ERROR] - Failed to find plan: " + $PlanToCheck) Write-Error ("Invalid plan " + $PlanToCheck + " provided in plan list. Please correct input and try again.") -ErrorAction Stop } } # If we validate them all then log it Write-Log "All Plans Valid" } ########################################## # Functions to Support change over to MS Graph ########################################## Function Write-SimpleLogfile { [cmdletbinding()] Param ( [Parameter(Mandatory = $true)] [string]$String, [string]$Name = "MGLicenseManagement.log", [switch]$OutHost, [switch]$OpenLog ) Begin { # Get our log file path $LogFile = Join-Path $env:LOCALAPPDATA $Name if ($OpenLog) { Notepad.exe $LogFile Exit } } Process { # Get the current date [string]$date = Get-Date -Format G # Build output string [string]$logstring = ( "[" + $date + "] - " + $string) # Write everything to our log file and the screen $logstring | Out-File -FilePath $LogFile -Append -Confirm:$false if ($OutHost) { Write-Host $logstring } else { Write-Verbose $logstring } } } Function Test-MGServiceConnection { # Make sure that the MS Graph Module is installed if ($null -eq (Get-Module -ListAvailable Microsoft.Graph.Users)) { Write-Error "Microsoft Graph Module Not installed. Please install from https://docs.microsoft.com/en-us/powershell/microsoftgraph/overview?view=graph-powershell-beta" -ErrorAction Stop } # Log out some basic information since we run this at the begining of every cmdlet Write-SimpleLogfile ('Module version ' + [array](Get-Module -ListAvailable Microsoft.Graph.Users | sort-object -Property version -Descending)[0].version.tostring()) # Clear any existing errors $error.clear() # Try to get a user to test that we have a connection try { $null = Get-MgUser -top 1 -ErrorAction Stop } catch { Write-SimpleLogFile ("[Error]: " + $_) Write-Error "$_" -ErrorAction Stop } } # Determine if we have an array with UPNs or just a single UPN / UPN array unlabeled Function Test-MGUserObject { param ([array]$ToTest) # See if we can get the UserPrincipalName property off of the input object # If we can't get the property then test the input and see if we can generate an acceptable object array if ($null -eq $ToTest[0].UserPrincipalName) { # Very basic check to see if this is a UPN # This deals with the input user@company.com,user2@company.com .... if ($ToTest[0] -match '@') { [array]$Output = $ToTest | Select-Object -Property @{Name = "UserPrincipalName"; Expression = { $_ } } Return $Output } # If we couldn't find the UserPrincipalName and we didn't see an @ sign then we need to abort else { Write-SimpleLogfile "[ERROR] - Unable to determine if input is a UserPrincipalName" -OutHost Write-SimpleLogfile "Please provide a UPN or array of objects with the property UserPrincipalName populated" -OutHost Write-Error "Unable to determine if input is a User Principal Name" -ErrorAction Stop } } # If we can pull the value of UserPrincipalName then just return the same object back else { Return $ToTest } } Function Get-MGLicenseAssignmentMethod { param ( [array]$UserAssignementArray, [string]$SkuToResolve ) [array]$Assignement = $UserAssignementArray | where-object { $_.skuid -eq $SkuToResolve } # If we didn't get a match then we don't know how this license has been assigned If ($Assignement.count -eq 0) { $Return = "Unknown" } # We shouldn't end up here since we should not have multiple ways to assign a license elseif ($Assignement.count -gt 1) { $Return = "Multiple" } # process if we got a value back else { # If assign by group is null then we are a direct assignment if ($null -eq $Assignement[0].assignedByGroup) { $Return = "Explicit" } # Else we need to return the display name else { $Return = Get-MGAssignmentGroup -GroupID $Assignement[0].assignedByGroup } } return $Return } Function Get-MGAssignmentGroup { param ( [string]$GroupID ) # If the group ID is in the global variable cache return that if ($cache_assignmentgroup -contains $GroupID) { return ($cache_assignmentgroup | Where-Object { $_.id -eq $GroupID }).DisplayName } # otherwise pull the group from graph and add it to the cache else { [array]$group = Get-MGGroup -GroupID $GroupID Set-Variable -Name cache_assignmentgroup -scope global -value ([array]$cache_assignmentgroup + [array]$group) return $group.DisplayName } } # Create and update a progress bar as part of a loop # Updated for PS 7 Function Update-MGProgress { Param ( [Parameter(Mandatory = $true)] [int]$CurrentCount, [Parameter(Mandatory = $true)] [int]$MaxCount, [Parameter(Mandatory = $true)] [string]$Message ) # If our counts match then close out the bar if ($CurrentCount -eq $MaxCount) { Write-Progress -Completed -Activity $Message } # Update the progress bar with the current % else { [int]$Percent = ($CurrentCount / $MaxCount) * 100 Write-Progress -Activity $Message -Status "$Percent% Complete:" -PercentComplete $Percent } } # Validate we have provided a valid SKU or collect one if we have provided none Function Select-MGSKU { param ( [string]$SKUToCheck, [string]$Message ) # If we don't have a value for the SKU then we need to ask for one. if ([string]::IsNullOrEmpty($SKUToCheck)) { Write-SimpleLogfile ("No SKU value provided. Please select from the availible account SKUs") -OutHost # Setup a counter $i = 1 # Write out the provided message Write-Host "`n$Message`n" # Get all of the SKUs and display them with a "selection number" $TenantSKU = Get-MSOLAccountSKU ForEach ($sku in $TenantSKU) { Write-Host ([string]$i + " - " + $sku.SKUPartNumber) $i++ } # Collect the selected item from the user [int]$Selected = 0 While (($Selected -ge $i) -or ($Selected -le 0) -or ($null -eq $Selected)) { [int]$Selected = Read-Host ("`nSelect the Number for the SKU to use.") } Return ($TenantSKU[$Selected - 1].AccountSkuID) } # We need to verify that the submitted SKU is valid else { Write-SimpleLogfile ("Verifying SKU " + $SKUToCheck) # If we can't find it then throw and error and abort if ($null -eq (Get-MSOLAccountSKU | Where-Object { $_.AccountSKUID -eq $SKUToCheck })) { Write-SimpleLogfile ("[ERROR] - Did not find SKU with ID: " + $SKUToCheck) -OutHost Write-Error ("Unable to locate SKU " + $SKUToCheck) -ErrorAction Stop } # If we found it log it else { Write-SimpleLogfile ("Found SKU") -OutHost Return $SKUToCheck.ToUpper() } } } |