TeamsFunctions

22.11

Public/Licensing/Get-TeamsUserLicense.ps1

# Module: TeamsFunctions
# Function: Licensing
# Author: David Eberhardt
# Updated: 01-APR-2020
# Status: Live




function Get-TeamsUserLicense {
  <#
  .SYNOPSIS
    Returns Teams License information for an Object in AzureAD
  .DESCRIPTION
    Returns an Object containing all Teams related Licenses found for a specific Object
    Licenses and ServicePlans are nested in the respective parameters for further investigation
  .PARAMETER UserPrincipalName
    The UserPrincipalName, ObjectId or Identity of the Object.
  .PARAMETER DisplayAll
    Displays all Licenses, not only identified or relevant Teams Licenses
  .EXAMPLE
    Get-TeamsUserLicense [-UserPrincipalName] John@domain.com
 
    Displays all licenses assigned to User John@domain.com
  .EXAMPLE
    Get-TeamsUserLicense -UserPrincipalName John@domain.com,Jane@domain.com
 
    Displays all licenses assigned to Users John@domain.com and Jane@domain.com
  .EXAMPLE
    Import-Csv User.csv | Get-TeamsUserLicense
 
    Displays all licenses assigned to Users from User.csv, Column UserPrincipalName.
    The input file must have a single column heading of "UserPrincipalName" with properly formatted UPNs.
  .INPUTS
    System.String
  .OUTPUTS
    System.Object
  .NOTES
    Requires a connection to Azure Active Directory
  .COMPONENT
    Licensing
  .FUNCTIONALITY
    Returns a list of Licenses assigned to a specific User depending on input
  .LINK
    https://github.com/DEberhardt/TeamsFunctions/tree/main/docs/Get-TeamsUserLicense.md
  .LINK
    https://github.com/DEberhardt/TeamsFunctions/tree/main/docs/about_Licensing.md
  .LINK
    https://github.com/DEberhardt/TeamsFunctions/tree/main/docs/about_UserManagement.md
  .LINK
    https://github.com/DEberhardt/TeamsFunctions/tree/main/docs/
  #>

  [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidGlobalVars', '', Justification = 'Required for performance. Removed with Disconnect-Me')]
  [CmdletBinding()]
  [OutputType([PSCustomObject])]
  param(
    [Parameter(Mandatory, ValueFromPipeline, ValueFromPipelineByPropertyName, HelpMessage = 'Enter the UPN or login name of the user account, typically <user>@<domain>.')]
    [Alias('ObjectId', 'Identity')]
    [ValidateScript( {
        If ($_ -match '@' -or $_ -match $script:TFMatchGuid) { $True } else {
          throw [System.Management.Automation.ValidationMetadataException] 'Value must be a valid UPN or ObjectId'
        } })]
    [string[]]$UserPrincipalName,

    [Parameter(HelpMessage = 'Displays all Licenses, not only Teams relevant')]
    [switch]$DisplayAll
  ) #param

  begin {
    Show-FunctionStatus -Level Live
    Write-Verbose -Message "[BEGIN ] $($MyInvocation.MyCommand)"

    # Asserting AzureAD Connection
    if ( -not $script:TFPSSA) { $script:TFPSSA = Assert-AzureADConnection; if ( -not $script:TFPSSA ) { break } }

    # Setting Preference Variables according to Upstream settings
    if (-not $PSBoundParameters.ContainsKey('Verbose')) { $VerbosePreference = $PSCmdlet.SessionState.PSVariable.GetValue('VerbosePreference') }
    if (-not $PSBoundParameters.ContainsKey('Confirm')) { $ConfirmPreference = $PSCmdlet.SessionState.PSVariable.GetValue('ConfirmPreference') }
    if (-not $PSBoundParameters.ContainsKey('WhatIf')) { $WhatIfPreference = $PSCmdlet.SessionState.PSVariable.GetValue('WhatIfPreference') }
    if (-not $PSBoundParameters.ContainsKey('Debug')) { $DebugPreference = $PSCmdlet.SessionState.PSVariable.GetValue('DebugPreference') } else { $DebugPreference = 'Continue' }
    if ( $PSBoundParameters.ContainsKey('InformationAction')) { $InformationPreference = $PSCmdlet.SessionState.PSVariable.GetValue('InformationAction') } else { $InformationPreference = 'Continue' }

    # preparing Output Field Separator
    $OFS = ', ' # do not remove - Automatic variable, used to separate elements!

    if ($PSBoundParameters.ContainsKey('DisplayAll')) {
      $previousFEL = $global:FormatEnumerationLimit
      $global:FormatEnumerationLimit = -1
    }
  } #begin

  process {
    Write-Verbose -Message "[PROCESS] $($MyInvocation.MyCommand)"
    foreach ($User in $UserPrincipalName) {
      try {
        $UserObject = Get-AzureADUser -ObjectId "$User" -WarningAction SilentlyContinue -ErrorAction STOP
        $UserLicenseDetail = Get-AzureADUserLicenseDetail -ObjectId "$User" -WarningAction SilentlyContinue -ErrorAction STOP
      }
      catch {
        if ($_.Exception.Message.Contains('does not exist')) {
          Write-Error -Message "User '$User' - Account not valid" -Category ObjectNotFound -RecommendedAction 'Verify UserPrincipalName'
        }
        else {
          Write-Error "User '$User' - Exception Message: $($_.Exception.Message)"
        }
        continue
      }

      [string]$DisplayName = $UserObject.DisplayName

      if ( $UserLicenseDetail ) {
        # Querying Licenses
        $UserLicenses = Get-UserLicensesFromLicenseDetailObject -UserLicenseDetail $UserLicenseDetail @args

        # Querying Service Plans
        $UserServicePlans = Get-UserServicePlansFromLicenseDetailObject -UserLicenseDetail $UserLicenseDetail @args
      }

      # Filter
      if ( -not $DisplayAll.IsPresent ) {
        $UserLicenses = $UserLicenses | Where-Object { $_.IncludesTeams -or $_.IncludesPhoneSystem }
        $UserServicePlans = $UserServicePlans | Where-Object RelevantForTeams
      }

      # Determining Phone System Status
      $PhoneSystemLicense = ('MCOEV' -in $UserServicePlans.ServicePlanName)
      $PhoneSystemVirtual = ('MCOEV_VIRTUALUSER' -in $UserServicePlans.ServicePlanName)
      if ( $PhoneSystemLicense ) {
        $PhoneSystemProvisioningStatus = $UserServicePlans | Where-Object ServicePlanName -EQ 'MCOEV'
        if ( $PhoneSystemProvisioningStatus.Count -gt 1 ) {
          # PhoneSystem assigned more than once!
          Write-Warning -Message "User '$User' Multiple assignments found for PhoneSystem. Please verify License assignment."
          $PhoneSystemStatus = ($PhoneSystemProvisioningStatus | Select-Object -ExpandProperty ProvisioningStatus) -join ', '

        }
        else {
          $PhoneSystemStatus = $PhoneSystemProvisioningStatus.ProvisioningStatus
        }

      }
      elseif ( $PhoneSystemVirtual ) {
        $PhoneSystemStatus = ($UserServicePlans | Where-Object ServicePlanName -EQ 'MCOEV_VIRTUALUSER').ProvisioningStatus
      }
      else {
        $PhoneSystemStatus = 'Unassigned'
      }

      # Calling Plans
      $currentCallingPlan = ($UserLicenses | Where-Object LicenseType -EQ 'CallingPlan').ProductName

      $output = [PSCustomObject][ordered]@{
        PSTypeName               = 'PowerShell.TeamsFunctsions.AzureAdUserLicense'
        UserPrincipalName        = $User
        DisplayName              = $DisplayName
        ObjectId                 = $UserObject.ObjectId
        UsageLocation            = $UserObject.UsageLocation
        Licenses                 = $UserLicenses
        ServicePlans             = $UserServicePlans
        AudioConferencing        = $('MCOMEETADV' -in $UserServicePlans.ServicePlanName)
        CommonAreaPhoneLicense   = $('MCOCAP' -in $UserLicenses.SkuPartNumber)
        PhoneSystemVirtualUser   = $PhoneSystemVirtual
        PhoneSystem              = $PhoneSystemLicense
        PhoneSystemStatus        = $PhoneSystemStatus
        CallingPlanDomestic120   = $('MCOPSTN5' -in $UserServicePlans.ServicePlanName -or 'MCOPSTN_5' -in $UserServicePlans.ServicePlanName)
        CallingPlanDomestic      = $('MCOPSTN1' -in $UserServicePlans.ServicePlanName -or 'MCOPSTN_1' -in $UserServicePlans.ServicePlanName) # also covering MCOPSTN_1_GOV
        CallingPlanInternational = $('MCOPSTN2' -in $UserServicePlans.ServicePlanName -or 'MCOPSTNEAU2' -in $UserServicePlans.ServicePlanName)
        OtherCallingPlan         = $('MCOPSTNEAU2' -in $UserServicePlans.ServicePlanName -or 'BUSINESS_VOICE_MED2_TELCO' -in $UserServicePlans.ServicePlanName)
        CommunicationsCredits    = $('MCOPSTNC' -in $UserServicePlans.ServicePlanName)
        CallingPlan              = $currentCallingPlan
      }

      #Adding Script Method to Licenses and ServicePlans
      if ( $output.Licenses ) {
        $output.Licenses | Add-Member -MemberType ScriptMethod -Name ToString -Value { $this.ProductName } -Force
      }
      if ( $output.ServicePlans ) {
        $output.ServicePlans | Add-Member -MemberType ScriptMethod -Name ToString -Value { $this.ProductName } -Force
      }

      Write-Output $output
    }
  } #process

  end {
    if ($PSBoundParameters.ContainsKey('DisplayAll')) {
      $global:FormatEnumerationLimit = $previousFEL
    }

    Write-Verbose -Message "[END ] $($MyInvocation.MyCommand)"
  } #end
} #Get-TeamsUserLicense