Requirements

In this article I am going to be sharing a script to get the Entra ID PIM Role eligibility and active assignments but there are a few things we will need in order to run the script successfully. Let us list out what’s needed now.

• Graph PowerShell SDK v1.0 and beta module
• Entra ID P2 License
• Graph API Scopes:
• Directory.Read.All

–OR–

• RoleEligibilitySchedule.Read.Directory
• RoleAssignmentSchedule.Read.Directory
• RoleManagement.Read.Directory

Get Entra ID PIM Role Assignment Using Graph API

As mentioned above, we will need at least 1 Entra ID P2 license since that is what allows us to use PIM in our tenant. We should also confirm we have the Graph PowerShell SDK v1.0 and beta modules.
 

Finally, I like to use PowerShell 7+ since that is better optimized for PowerShell as opposed to the default Windows PowerShell that comes pre-installed with Windows. This is not a requirement but more of a personal preference.
 

PowerShell Script

Now let’s get to the reason why you checked this article. Below is the PowerShell script to get PIM Role assignment using Graph API.

Function Get-MgPimRoleAssignment {
<#
.SYNOPSIS
    This will check if a user is added to PIM or standing access.

.LINK
    https://thesysadminchannel.com/get-entra-id-pim-role-assignment-using-graph-api -

.NOTES
    Name: Get-MgPimRoleAssignment
    Author: Paul Contreras
    Version: 2.4
    DateCreated: 2023-Jun-15
#>

    [CmdletBinding()]
    param(
        [Parameter(
            Mandatory = $true,
            ValueFromPipeline = $true,
            ValueFromPipelineByPropertyName = $true,
            ParameterSetName = 'User',
            Position  = 0
        )]
        [Alias('UserPrincipalName')]
        [string[]]  $UserId,


        [Parameter(
            Mandatory = $false,
            ValueFromPipeline = $true,
            ValueFromPipelineByPropertyName = $true,
            ParameterSetName = 'Role',
            Position  = 1
        )]
        [Alias('DisplayName')]
        [ValidateSet(
            'Application administrator',
            'Application developer',
            'Attack payload author',
            'Attack simulation administrator',
            'Attribute assignment administrator',
            'Attribute assignment reader',
            'Attribute definition administrator',
            'Attribute definition reader',
            'Authentication administrator',
            'Authentication policy administrator',
            'Azure AD joined device local administrator',
            'Azure DevOps administrator',
            'Azure Information Protection administrator',
            'B2C IEF Keyset administrator',
            'B2C IEF Policy administrator',
            'Billing administrator',
            'Cloud App Security Administrator',
            'Cloud application administrator',
            'Cloud device administrator',
            'Compliance administrator',
            'Compliance data administrator',
            'Conditional Access administrator',
            'Customer LockBox access approver',
            'Desktop Analytics administrator',
            'Directory readers',
            'Directory writers',
            'Domain name administrator',
            'Dynamics 365 administrator',
            'Edge administrator',
            'Exchange administrator',
            'Exchange recipient administrator',
            'External ID user flow administrator',
            'External ID user flow attribute administrator',
            'External Identity Provider administrator',
            'Global administrator',
            'Global reader',
            'Groups administrator',
            'Guest inviter',
            'Helpdesk administrator',
            'Hybrid identity administrator',
            'Identity Governance Administrator',
            'Insights administrator',
            'Insights Analyst',
            'Insights business leader',
            'Intune administrator',
            'Kaizala administrator',
            'Knowledge administrator',
            'Knowledge manager',
            'License administrator',
            'Lifecycle Workflows Administrator',
            'Message center privacy reader',
            'Message center reader',
            'Network administrator',
            'Office apps administrator',
            'Password administrator',
            'Permissions Management Administrator',
            'Power BI administrator',
            'Power platform administrator',
            'Printer administrator',
            'Printer technician',
            'Privileged authentication administrator',
            'Privileged role administrator',
            'Reports reader',
            'Search administrator',
            'Search editor',
            'Security administrator',
            'Security operator',
            'Security reader',
            'Service support administrator',
            'SharePoint administrator',
            'Skype for Business administrator',
            'Teams administrator',
            'Teams communications administrator',
            'Teams Communications Support Engineer',
            'Teams Communications Support Specialist',
            'Teams devices administrator',
            'Tenant Creator',
            'Usage summary reports reader',
            'User administrator',
            'Virtual Visits Administrator',
            'Windows 365 Administrator',
            'Windows update deployment administrator',
            'Yammer Administrator'
        )]
        [string]    $RoleName,


        [Parameter(
            Mandatory = $false
        )]
        [ValidateSet(
            'Eligibile',
            'Active'
        )]
        [string]    $PimAssignment,


        [Parameter(
            Mandatory = $false
        )]
        [string]    $TenantId,


        [Parameter(
            Mandatory = $false
        )]
        [switch]    $HideActivatedRoles
    )

    BEGIN {
        $ConnectionGraph = Get-MgContext
        $ConnectionGraph.Scopes = $ConnectionGraph.Scopes -replace "write","" | select -Unique
        'RoleEligibilitySchedule.Read.Directory', 'RoleAssignmentSchedule.Read.Directory', 'RoleManagement.Read.Directory' | ForEach-Object {
            if ($ConnectionGraph.Scopes -notcontains $_) {
                Connect-Graph -Scopes RoleEligibilitySchedule.Read.Directory, RoleAssignmentSchedule.Read.Directory, RoleManagement.Read.Directory -ErrorAction Stop
                continue
            }
        }

        if (-not ($PSBoundParameters.ContainsKey('TenantId'))) {
            $TenantId = $ConnectionGraph.TenantId
        }
    }

    PROCESS {
        $RoleDefinitions = Invoke-GraphRequest -Uri 'https://graph.microsoft.com/beta/roleManagement/directory/roleDefinitions' | select -ExpandProperty value

        $RoleHash   = @{}
        $RoleDefinitions | select id, displayname | ForEach-Object {$RoleHash.Add($_.DisplayName, $_.Id) | Out-Null}
        $RoleDefinitions | select id, displayname | ForEach-Object {$RoleHash.Add($_.Id, $_.DisplayName) | Out-Null}

        if ($PSBoundParameters.ContainsKey('UserId')) {
            foreach ($User in $UserId) {
                try {
                    [System.Collections.Generic.List[Object]]$RoleMemberList = @()
                    $PropertyList = 'DisplayName', 'UserPrincipalName', 'Id', 'AccountEnabled'
                    $AzUser = Get-MgUser -UserId $User -Property $PropertyList | select $PropertyList

                    if ($PSBoundParameters.ContainsKey('PimAssignment')) { #if active or eligible is selected, no need to get other option
                        if ($PSBoundParameters.ContainsValue('Active')) {
                            $AssignmentList = Get-MgBetaRoleManagementDirectoryRoleAssignmentSchedule -Filter "PrincipalId eq '$($AzUser.id)'" -ExpandProperty Principal,DirectoryScope -All
                            $AssignmentList | Add-Member -MemberType NoteProperty -Name AssignmentScope -Value "Active" -Force -PassThru | Out-Null
                            $AssignmentList | Add-Member -MemberType ScriptProperty -Name AccountType -Value {$this.Principal.AdditionalProperties."@odata.type".split('.')[2] } -Force -PassThru | Out-Null
                            $AssignmentList | ForEach-Object {$RoleMemberList.Add($_) | Out-Null}
                        }

                        if ($PSBoundParameters.ContainsValue('Eligibile')) {
                            $EligibleList = Get-MgBetaRoleManagementDirectoryRoleEligibilitySchedule -Filter "PrincipalId eq '$($AzUser.id)'" -ExpandProperty Principal,DirectoryScope -All
                            $EligibleList | Add-Member -MemberType NoteProperty -Name AssignmentScope -Value "Eligibile" -Force -PassThru | Out-Null
                            $EligibleList | Add-Member -MemberType ScriptProperty -Name AccountType -Value {$this.Principal.AdditionalProperties."@odata.type".split('.')[2] } -Force -PassThru | Out-Null
                            $EligibleList | ForEach-Object {$RoleMemberList.Add($_) | Out-Null}
                        }
                    } else {
                        $AssignmentList = Get-MgBetaRoleManagementDirectoryRoleAssignmentSchedule -Filter "PrincipalId eq '$($AzUser.id)'" -ExpandProperty Principal,DirectoryScope -All
                        $AssignmentList | Add-Member -MemberType NoteProperty -Name AssignmentScope -Value "Active" -Force -PassThru | Out-Null
                        $AssignmentList | Add-Member -MemberType ScriptProperty -Name AccountType -Value {$this.Principal.AdditionalProperties."@odata.type".split('.')[2] } -Force -PassThru | Out-Null

                        $EligibleList = Get-MgBetaRoleManagementDirectoryRoleEligibilitySchedule -Filter "PrincipalId eq '$($AzUser.id)'" -ExpandProperty Principal,DirectoryScope -All
                        $EligibleList | Add-Member -MemberType NoteProperty -Name AssignmentScope -Value "Eligibile" -Force -PassThru | Out-Null
                        $EligibleList | Add-Member -MemberType ScriptProperty -Name AccountType -Value {$this.Principal.AdditionalProperties."@odata.type".split('.')[2] } -Force -PassThru | Out-Null

                        $AssignmentList | ForEach-Object {$RoleMemberList.Add($_) | Out-Null}
                        $EligibleList   | ForEach-Object {$RoleMemberList.Add($_) | Out-Null}
                    }

                    if ($RoleMemberList) {
                        $Output = foreach ($RoleMember in $RoleMemberList) {
                            if ($RoleMember.DirectoryScopeId -eq '/') {
                                $DirectoryScope = 'Global'
                            }
                            elseif ($RoleMember.DirectoryScopeId -match 'administrativeUnits') {
                                $DirectoryScope = $RoleMember.DirectoryScope.AdditionalProperties.displayName
                            }
                            else {
                                $DirectoryScope = 'Unknown'
                            }

                            if ($RoleMember.ScheduleInfo.Expiration.Type -eq 'noExpiration') {
                                $DurationInMonths = 'Permanent'
                                $EndDate = 'Permanent'
                            } else {
                                $Days = ($RoleMember.ScheduleInfo.Expiration.EndDateTime) - ($RoleMember.ScheduleInfo.StartDateTime) | select -ExpandProperty TotalDays
                                $DurationInMonths = $Days / 30.4167 -as [int]
                                $EndDate = (Get-Date $RoleMember.ScheduleInfo.Expiration.EndDateTime).ToLocalTime()
                            }

                            if ($RoleMember.AssignmentScope -eq 'Active' -and $RoleMember.AssignmentType -eq 'Activated') {
                                $AssignmentScope = 'PimActivated'
                            } else {
                                $AssignmentScope = $RoleMember.AssignmentScope
                            }

                            if ($RoleMember.ScheduleInfo.StartDateTime -and $RoleMember.CreatedDateTime) {
                                $StartDateTime = (Get-Date $RoleMember.ScheduleInfo.StartDateTime).ToLocalTime()
                            } else {
                                $StartDateTime = (Get-Date 1/1/1999 -Hour 0 -Minute 0 -Millisecond 0)
                            }

                            [PSCustomObject]@{
                                UserPrincipalName   = $AzUser.UserPrincipalName
                                AzureADRole         = $RoleHash[$RoleMember.RoleDefinitionId]
                                PimAssignment       = $AssignmentScope
                                EndDateTime         = $EndDate
                                AccountEnabled      = $AzUser.AccountEnabled
                                DirectoryScope      = $DirectoryScope
                                DurationInMonths    = $DurationInMonths
                                MemberType          = $RoleMember.MemberType
                                AccountType         = $RoleMember.AccountType
                                StartDateTime       = $StartDateTime
                            }
                        }

                        if ($PSBoundParameters.ContainsKey('HideActivatedRoles')) {
                            $Output | Sort-Object PimAssignment, AzureADRole | Where-Object {$_.PimAssignment -ne 'PimActivated'}
                        } else {
                            $Output | Sort-Object PimAssignment, AzureADRole
                        }
                    }

                } catch {
                    Write-Error $_.Exception.Message
                }
            }
        } #end userid parameter set

        if ($PSBoundParameters.ContainsKey('RoleName')) {
            try {
                [System.Collections.Generic.List[Object]]$RoleMemberList = @()

                if ($PSBoundParameters.ContainsKey('PimAssignment')) {
                    if ($PSBoundParameters.ContainsValue('Active')) {
                        $AssignmentList = Get-MgBetaRoleManagementDirectoryRoleAssignmentSchedule -Filter "RoleDefinitionId eq '$($RoleHash[$RoleName])'" -ExpandProperty Principal,DirectoryScope -All
                        $AssignmentList | Add-Member -MemberType NoteProperty -Name AssignmentScope -Value "Active" -Force -PassThru | Out-Null
                        $AssignmentList | Add-Member -MemberType ScriptProperty -Name AccountType -Value {$this.Principal.AdditionalProperties."@odata.type".split('.')[2] } -Force -PassThru | Out-Null
                        $AssignmentList | ForEach-Object {$RoleMemberList.Add($_) | Out-Null}
                    }

                    if ($PSBoundParameters.ContainsValue('Eligibile')) {
                        $EligibleList = Get-MgBetaRoleManagementDirectoryRoleEligibilitySchedule -Filter "RoleDefinitionId eq '$($RoleHash[$RoleName])'" -ExpandProperty Principal,DirectoryScope -All
                        $EligibleList | Add-Member -MemberType NoteProperty -Name AssignmentScope -Value "Eligibile" -Force -PassThru | Out-Null
                        $EligibleList | Add-Member -MemberType ScriptProperty -Name AccountType -Value {$this.Principal.AdditionalProperties."@odata.type".split('.')[2] } -Force -PassThru | Out-Null
                        $EligibleList | ForEach-Object {$RoleMemberList.Add($_) | Out-Null}
                    }
                  } else {
                    $AssignmentList = Get-MgBetaRoleManagementDirectoryRoleAssignmentSchedule -Filter "RoleDefinitionId eq '$($RoleHash[$RoleName])'" -ExpandProperty Principal,DirectoryScope -All
                    $AssignmentList | Add-Member -MemberType NoteProperty -Name AssignmentScope -Value "Active" -Force -PassThru | Out-Null
                    $AssignmentList | Add-Member -MemberType ScriptProperty -Name AccountType -Value {$this.Principal.AdditionalProperties."@odata.type".split('.')[2] } -Force -PassThru | Out-Null

                    $EligibleList = Get-MgBetaRoleManagementDirectoryRoleEligibilitySchedule -Filter "RoleDefinitionId eq '$($RoleHash[$RoleName])'" -ExpandProperty Principal,DirectoryScope -All
                    $EligibleList | Add-Member -MemberType NoteProperty -Name AssignmentScope -Value "Eligibile" -Force -PassThru | Out-Null
                    $EligibleList | Add-Member -MemberType ScriptProperty -Name AccountType -Value {$this.Principal.AdditionalProperties."@odata.type".split('.')[2] } -Force -PassThru | Out-Null

                    $AssignmentList | ForEach-Object {$RoleMemberList.Add($_) | Out-Null}
                    $EligibleList   | ForEach-Object {$RoleMemberList.Add($_) | Out-Null}
                }

                if ($RoleMemberList) {
                    $Output = foreach ($RoleMember in $RoleMemberList) {
                        if ($RoleMember.DirectoryScopeId -eq '/') {
                            $DirectoryScope = 'Global'
                        }
                        elseif ($RoleMember.DirectoryScopeId -match 'administrativeUnits') {
                            $DirectoryScope = $RoleMember.DirectoryScope.AdditionalProperties.displayName
                        }
                        else {
                            $DirectoryScope = 'Unknown'
                        }

                        if ($RoleMember.ScheduleInfo.Expiration.Type -eq 'noExpiration') {
                            $DurationInMonths = 'Permanent'
                            $EndDate = 'Permanent'
                        } else {
                            $Days = ($RoleMember.ScheduleInfo.Expiration.EndDateTime) - ($RoleMember.ScheduleInfo.StartDateTime) | select -ExpandProperty TotalDays
                            $DurationInMonths = $Days / 30.4167 -as [int]
                            $EndDate = (Get-Date $RoleMember.ScheduleInfo.Expiration.EndDateTime)#.ToString('yyyy-MM-dd')
                        }

                        if ($RoleMember.AssignmentScope -eq 'Active' -and $RoleMember.AssignmentType -eq 'Activated') {
                            $AssignmentScope = 'PimActivated'
                        } else {
                            $AssignmentScope = $RoleMember.AssignmentScope
                        }

                        if ($RoleMember.ScheduleInfo.StartDateTime -and $RoleMember.CreatedDateTime) {
                            $StartDateTime = (Get-Date $RoleMember.ScheduleInfo.StartDateTime).ToLocalTime()
                        } else {
                            $StartDateTime = (Get-Date 1/1/1999 -Hour 0 -Minute 0 -Millisecond 0)
                        }

                        switch ($RoleMember.AccountType) {

                            'User' {
                                [PSCustomObject]@{
                                    UserPrincipalName   = $RoleMember.Principal.AdditionalProperties.userPrincipalName
                                    AzureADRole         = $RoleHash[$RoleMember.RoleDefinitionId]
                                    PimAssignment       = $AssignmentScope
                                    EndDateTime         = $EndDate
                                    AccountEnabled      = $RoleMember.Principal.AdditionalProperties.accountEnabled
                                    DirectoryScope      = $DirectoryScope
                                    DurationInMonths    = $DurationInMonths
                                    MemberType          = $RoleMember.MemberType
                                    AccountType         = $RoleMember.AccountType
                                    StartDateTime       = $StartDateTime
                                }
                            }

                            'Group' {
                                $GroupMemberList = Get-MgGroupTransitiveMember -GroupId $RoleMember.PrincipalId
                                foreach ($GroupMember in $GroupMemberList) {
                                    [PSCustomObject]@{
                                        UserPrincipalName   = $GroupMember.AdditionalProperties.userPrincipalName
                                        AzureADRole         = $RoleHash[$RoleMember.RoleDefinitionId]
                                        PimAssignment       = $AssignmentScope
                                        EndDateTime         = $EndDate
                                        AccountEnabled      = $GroupMember.AdditionalProperties.accountEnabled
                                        DirectoryScope      = $DirectoryScope
                                        DurationInMonths    = $DurationInMonths
                                        MemberType          = $RoleMember.MemberType
                                        AccountType         = $GroupMember.AdditionalProperties.'@odata.type'.Split('.')[2]
                                        StartDateTime       = $StartDateTime
                                    }
                                }
                            }

                            'servicePrincipal' {
                                [PSCustomObject]@{
                                    UserPrincipalName   = $RoleMember.Principal.additionalproperties.displayName
                                    AzureADRole         = $RoleHash[$RoleMember.RoleDefinitionId]
                                    PimAssignment       = $AssignmentScope
                                    EndDateTime         = $EndDate
                                    AccountEnabled      = $RoleMember.Principal.AdditionalProperties.accountEnabled
                                    DirectoryScope      = $DirectoryScope
                                    DurationInMonths    = $DurationInMonths
                                    MemberType          = $RoleMember.MemberType
                                    AccountType         = $RoleMember.AccountType
                                    StartDateTime       = $StartDateTime
                                }
                            }
                        }
                    }

                    if ($PSBoundParameters.ContainsKey('HideActivatedRoles')) {
                        $Output | Sort-Object PimAssignment, AzureADRole | Where-Object {$_.PimAssignment -ne 'PimActivated'}
                    } else {
                        $Output | Sort-Object PimAssignment, AzureADRole
                    }
                }

            } catch {
                Write-Error $_.Exception.Message
            }
        } #end rolename parameter set
    }

    END {}

}

Script Parameters

When using this script, you can use the following parameters to customize the output. Let’s go over those now.
 

    -UserId

DataType: string
Description: Specify the UserId or UserPrincipalName of the principal you want to find active or eligible roles.
 

    -RoleName

DataType: string
Description: Specify the Entra ID Role name to get all principals that are assigned that role.
 

    -PimAssignment

DataType: string
Description: Specify either Active or Eligible to display those results..
 

    -TenantId

DataType: string
Description: Specify the tenant Id to query that specific tenant. You must be authenticated to that tenant.
 

    -HideActivatedRoles

DataType: switch
Description: When used, the results will hide all PIM activated roles.
 

Example 1: Specifying the UserId parameter

Get-MgPimRoleAssignment -UserId homer@thesysadminchannel.com

UserPrincipalName : homer@thesysadminchannel.com
AzureADRole       : Helpdesk Administrator
PimAssignment     : Eligibile
EndDateTime       : Permanent
AccountEnabled    : True
DirectoryScope    : Admin Unit
DurationInMonths  : Permanent
MemberType        : Direct
AccountType       : user
StartDateTime     : 2/19/2024 3:34:32 PM

Example 2: Specifying the RoleName parameter that are eligible

Get-MgPimRoleAssignment -RoleName 'Helpdesk administrator' -PimAssignment Eligibile

UserPrincipalName : luke@thesysadminchannel.com
AzureADRole       : Helpdesk Administrator
PimAssignment     : Eligibile
EndDateTime       : Permanent
AccountEnabled    : True
DirectoryScope    : Global
DurationInMonths  : Permanent
MemberType        : Direct
AccountType       : user
StartDateTime     : 2/19/2024 3:43:16 PM

UserPrincipalName : homer@thesysadminchannel.com
AzureADRole       : Helpdesk Administrator
PimAssignment     : Eligibile
EndDateTime       : Permanent
AccountEnabled    : True
DirectoryScope    : Admin Unit
DurationInMonths  : Permanent
MemberType        : Direct
AccountType       : user
StartDateTime     : 2/19/2024 3:34:32 PM

Conclusion

Hopefully this article was able to help you get Entra ID PIM Role Assignment Using Graph API. With this script, you should be able to get all active, eligible AND eligible assignments that have been activated.
 

The post Get Entra ID PIM Role Assignment Using Graph API appeared first on the Sysadmin Channel.

Requirements

In order to query license information for your tenant, you will need the following API Scopes permitted.

• Microsoft.Graph or Microsoft.Graph.Beta PowerShell modules
• Directory.Read.All or Organization.Read.All

Get Microsoft 365 License Usage Count Using PowerShell

Before we get into the PowerShell script, I wanted to point out that the Microsoft API’s don’t show the friendly display names for these licenses. Instead, they use a SkuPartNumber to give you an idea of what the licenses is regarding. The problem here is that you also won’t find the SkuPartNumber anywhere in the portal so it’s kind of a pain to make sure the license you’re targeting in the API is in fact the license in the Azure portal.
 

Luckily, there is a Microsoft Doc that has this information but it’s not always up to date. The link to that doc is https://learn.microsoft.com/en-us/entra/identity/users/licensing-service-plan-reference. There’s about 400+ Sku’s that are shown so it’s also nice that they have provided a csv file that we can use PowerShell to be able to pull these names into our Script.

$LicenseFile = 'C:\temp\m365license.csv'
$CutoffDate = (Get-Date).AddDays(-7)

if (Test-Path $LicenseFile) {
    $LastWriteTime = Get-ChildItem -Path $LicenseFile | select -ExpandProperty LastWriteTime

    if ($CutoffDate -gt $LastWriteTime) {
        #csv file is older than a week old.  Let us get a newer version
        Invoke-WebRequest -Uri 'https://download.microsoft.com/download/e/3/e/e3e9faf2-f28b-490a-9ada-c6089a1fc5b0/Product%20names%20and%20service%20plan%20identifiers%20for%20licensing.csv' -OutFile C:\temp\m365license.csv
    }
} else {
    #csv file was not found so let us download it now
    Invoke-WebRequest -Uri 'https://download.microsoft.com/download/e/3/e/e3e9faf2-f28b-490a-9ada-c6089a1fc5b0/Product%20names%20and%20service%20plan%20identifiers%20for%20licensing.csv' -OutFile C:\temp\m365license.csv
}

$csvList = Import-Csv C:\temp\m365license.csv
$LicenseHash = @{}

$csvList | ForEach-Object {
    if (-not $LicenseHash[$_.Guid]) {
        $LicenseHash.Add($_.GUID, $_.Product_Display_Name)
    }
}

$LicenseList = Get-MgSubscribedSku

#Uncomment if you only want to display licenses that are maxed out
foreach ($License in $LicenseList) {
    if ($License.PrepaidUnits.Enabled -ge 1) {
        #if ($License.ConsumedUnits -ge $License.PrepaidUnits.Enabled) {
            [PSCustomObject]@{
                LicenseName   = $LicenseHash[$License.SkuId]
                SkuPartNumber = $License.SkuPartNumber
                SkuId         = $License.SkuId
                Remaining     = $License.PrepaidUnits.Enabled - $License.ConsumedUnits
                Enabled       = $License.PrepaidUnits.Enabled
                Used          = $License.ConsumedUnits
            }
        #}
    }
}

As you can see from above, the Identity Governance P2 Step Up license has not been updated in the downloadable csv file so the license name shows up blank.

Conclusion

Hopefully this article was able to help you get Microsoft 365 License usage count using PowerShell and Graph API. Sometimes we’re too busy to manually keep an eye on it so having this script along with an email alert would be helpful for preventing your licenses being maxed out.

The post Get Microsoft 365 License Usage Count Using PowerShell appeared first on the Sysadmin Channel.

Requirements

In order to run this, there are a few things that need to be in place to ensure we don’t run into any errors. Let’s touch on those item now.
 

• Directory.Read.All Permissions
• Application.Read.All Permissions
• Microsoft.Graph PowerShell SDK Module

Check an App Registration for Expired Keys in Azure Portal

Before we get into the PowerShell script, let’s take a look at how to check this manually so we know exactly what to expect when looking at the results of the script.
 

Within Azure AD:

• Navigate to App Registrations
• Select an App that has a certificate or secret added

• Go to Certificates & secrets blade

Here we can see the status of the certificate for this specific application. Specifically, we’re interested in the expiration date, certificate thumbprint and Key ID (certificate ID).
 

While the portal does give you a visual of when keys are expiring, it still requires you to take time out of your day to manually check. Let’s take a look at how we can accomplish the same thing automatically using the PowerShell script I wrote.

Get Application Certificate and Secret Expiration with Graph API PowerShell

Now that we’ve gone over the manual method, let’s use PowerShell and Graph API to our advantage and show the same information in an automated fashion. Since we know how to automate Powershell Scripts With Task Scheduler, we can schedule this on a daily basis and let it alert you without any additional effort on your end.
 

Now for the PowerShell script:

Function Get-MgApplicationCertificateAndSecretExpiration {
<#
.SYNOPSIS
    This will display all Applications that have certificates or secrets expiring within a certain timeframe


.NOTES
    Name: Get-MgApplicationCertificateAndSecretExpiration
    Author: Paul Contreras
    Version: 1.3
    DateCreated: 2022-Feb-8

.LINK
    https://thesysadminchannel.com/get-application-certificate-and-secret-expiration-with-graph-api-powershell -

.EXAMPLE
    Get-MgApplicationCertificateAndSecretExpiration

.EXAMPLE
    Get-MgApplicationCertificateAndSecretExpiration -ShowExpiredKeys
#>

    [CmdletBinding(DefaultParameterSetName='Default')]
    param(
        [Parameter(
            Mandatory = $false,
            ParameterSetName = 'CertOnly'
        )]
        [switch]    $ShowOnlyCertificates,

        [Parameter(
            Mandatory = $false,
            ParameterSetName = 'SecretOnly'
        )]
        [switch]    $ShowOnlySecrets,


        [Parameter(
            Mandatory = $false
        )]
        [switch]    $ShowExpiredKeys,


        [Parameter(
            Mandatory = $false
        )]
        [ValidateRange(1,720)]
        [int]    $DaysWithinExpiration = 30,


        [Parameter(
            Mandatory = $false,
            ValueFromPipeline = $true,
            ValueFromPipelineByPropertyName = $true
        )]
        [Alias('ApplicationId', 'ClientId')]
        [string]    $AppId
    )

    BEGIN {
        $ConnectionGraph = Get-MgContext
        if (-not $ConnectionGraph) {
            Write-Error "Please connect to Microsoft Graph" -ErrorAction Stop
        }
        #Adding an extra day to account for hour differences and offsets.
        $DaysWithinExpiration++
    }

    PROCESS {
        try {
            if ($PSBoundParameters.ContainsKey('AppId')) {
                $ApplicationList = Get-MgApplication -Filter "AppId eq '$AppId'" -ErrorAction Stop
                $AppFilter = $true
            } else {
                $ApplicationList = Get-MgApplication -All -Property AppId, DisplayName, PasswordCredentials, KeyCredentials, Id -PageSize 999 -ErrorAction Stop
            }

            #If certs are selected, show certs
            if ($PSBoundParameters.ContainsKey('ShowOnlyCertificates') -or

                #If neither Certs or Secrets are selected show both.
               (-not $PSBoundParameters.ContainsKey('ShowOnlyCertificates') -and
                -not $PSBoundParameters.ContainsKey('ShowOnlySecrets'))) {

                    $CertificateApps  = $ApplicationList | Where-Object {$_.keyCredentials}

                    $CertApp = foreach ($App in $CertificateApps) {
                        foreach ($Cert in $App.keyCredentials) {
                            if ( $Cert.endDateTime -le (Get-Date).AddDays($DaysWithinExpiration) -or ($AppFilter) ) {
                                [PSCustomObject]@{
                                    AppDisplayName      = $App.DisplayName
                                    AppId               = $App.AppId
                                    KeyType             = 'Certificate'
                                    ExpirationDate      = $Cert.EndDateTime
                                    DaysUntilExpiration = (($Cert.EndDateTime) - (Get-Date) | select -ExpandProperty TotalDays) -as [int]
                                    ThumbPrint          = [System.Convert]::ToBase64String($Cert.CustomKeyIdentifier)
                                    Id                  = $App.Id
                                    KeyId               = $Cert.KeyId
                                    Description         = $Cert.DisplayName
                                }
                            }
                        }
                    }

                    if ($PSBoundParameters.ContainsKey('ShowExpiredKeys')) {
                        $CertApp | Sort-Object DaysUntilExpiration
                    } else {
                        $CertApp | Sort-Object DaysUntilExpiration | Where-Object {$_.DaysUntilExpiration -ge 0}
                    }
            }

            #If secrets are selected, show secrets
            if ($PSBoundParameters.ContainsKey('ShowOnlySecrets') -or

                #If neither Certs or Secrets are selected show both.
               (-not $PSBoundParameters.ContainsKey('ShowOnlySecrets') -and
                -not $PSBoundParameters.ContainsKey('ShowOnlyCertificates'))) {

                    $ClientSecretApps = $ApplicationList | Where-Object {$_.passwordCredentials}

                    $SecretApp = foreach ($App in $ClientSecretApps){
                        foreach ($Secret in $App.PasswordCredentials) {
                            if ( $Secret.EndDateTime -le (Get-Date).AddDays($DaysWithinExpiration) -or ($AppFilter) ) {
                                [PSCustomObject]@{
                                    AppDisplayName      = $App.DisplayName
                                    AppId               = $App.AppId
                                    KeyType             = 'ClientSecret'
                                    ExpirationDate      = $Secret.EndDateTime
                                    DaysUntilExpiration = (($Secret.EndDateTime) - (Get-Date) | select -ExpandProperty TotalDays) -as [int]
                                    ThumbPrint          = 'N/A'
                                    Id                  = $App.Id
                                    KeyId               = $Secret.KeyId
                                    Description         = $Secret.DisplayName
                                }
                            }
                        }
                    }

                    if ($PSBoundParameters.ContainsKey('ShowExpiredKeys')) {
                        $SecretApp | Sort-Object DaysUntilExpiration
                    } else {
                        $SecretApp | Sort-Object DaysUntilExpiration | Where-Object {$_.DaysUntilExpiration -ge 0}
                    }
            }
        } catch {
            Write-Error $_.Exception.Message
        }
    }

    END {}
}

Script Parameters

    No Parameters

DataType: N/A
Description: Gather all apps and display the ones that have a secret or certificate expiring within 30 days.
 

    -ShowOnlyCertificates

DataType: switch
Description: Only display certificates in the output. Expired keys and secrets will not be shown.
 

    -ShowOnlySecrets

DataType: switch
Description: Only display secrets in the output. Expired keys and certificates will not be shown.
 

    -ShowExpiredKeys

DataType: switch
Description: Display certificates or secrets are near expiration or have already expired.
 

    -DaysWithinExpiration

DataType: integer
Description: Set the time frame to include expiring keys. This is defaulted to 30 days.
 

    -AppId

DataType: string
Description: Specify an AppId (client Id) to see that specific applications keys.
 

Example 1 – Calling the script with no parameters

Since this is a function, you’ll need to dot source it to load it into memory. Assuming the file is your desktop you can run.

. $Home\Desktop\Get-MgApplicationCertificateAndSecretExpiration.ps1
Get-MgApplicationCertificateAndSecretExpiration

Using the default output, take a look at the KeyType, ExpirationDate, DaysUntilExpiration and ThumbPrint. Certificates will display a thumbprint while secrets will not.
 

Example 2 – Display Only Certificates that are expired or nearing expiration

Get-MgApplicationCertificateAndSecretExpiration -ShowOnlyCertificates -ShowExpiredKeys `
| Select-Object AppDisplayName, KeyType, ExpirationDate, DaysUntilExpiration, KeyId, ThumbPrint

If you recall Portal screenshot above, our “App Automation 1” application had an expired cert with the thumbprint starting in “2E8972E” and the Key ID (certificate ID) started with “6f395fd4”. This is the same information we can pull in PowerShell
 

Example 3 – Display Only secrets that are expiring within 5 days

Get-MgApplicationCertificateAndSecretExpiration -ShowOnlySecrets -DaysWithinExpiration 5
| Select-Object AppDisplayName, KeyType, ExpirationDate, DaysUntilExpiration

Conclusion

Hopefully this article was able to show you get an application certificate and secret expiration with Graph API. This is super useful to keep in your automation toolkit since the Azure world is now moving everything to Microsoft Graph.

The post Get Application Certificate and Secret Expiration with Graph API appeared first on the Sysadmin Channel.

Requirements

Before I get to the script, there are a few things that need to be in place before we’re able to successfully install the module. Let’s cover that now:

• Az PowerShell Module
• Permissions to install any module

Install Microsoft Graph Module for Azure Automation using PowerShell

Here is the script I wrote to be able to install and update the Microsoft.Graph module for an Automation account. You can always manually check for the latest version on the PowerShell gallery.

#Before running the script, be sure you're on the right subscription
Set-AzContext -SubscriptionId $SubscriptionId
$ResourceGroup = 'rg-resourcegroupname'
$AutomationAccount = 'automationaccountname'
[System.Collections.Generic.List[Object]]$InstalledModules = @()

#Get top level graph module
$GraphModule = Find-Module Microsoft.Graph
$DependencyList = $GraphModule | select -ExpandProperty Dependencies | ConvertTo-Json | ConvertFrom-Json
$ModuleVersion = $GraphModule.Version

#Since we know the authentication module is a dependency, let us get that one first
$ModuleName = 'Microsoft.Graph.Authentication'
$ContentLink = "https://www.powershellgallery.com/api/v2/package/$ModuleName/$ModuleVersion"
New-AzAutomationModule -ResourceGroupName $ResourceGroup -AutomationAccountName $AutomationAccount -Name $ModuleName -ContentLinkUri $ContentLink -ErrorAction Stop | Out-Null
do {
    Start-Sleep 20
    $Status = Get-AzAutomationModule -ResourceGroupName $ResourceGroup -AutomationAccountName $AutomationAccount -Name $ModuleName | select -ExpandProperty ProvisioningState
} until ($Status -in ('Failed','Succeeded'))

if ($Status -eq 'Succeeded') {
    $InstalledModules.Add($ModuleName)

    foreach ($Dependency in $DependencyList) {
        $ModuleName = $Dependency.Name
        if ($ModuleName -notin $InstalledModules) {
            $ContentLink = "https://www.powershellgallery.com/api/v2/package/$ModuleName/$ModuleVersion"
            New-AzAutomationModule -ResourceGroupName $ResourceGroup -AutomationAccountName $AutomationAccount -ContentLinkUri $ContentLink -Name $ModuleName -ErrorAction Stop | Out-Null
            sleep 3
        }
    }

    $LoopIndex = 0
    do {
        foreach ($Dependency in $DependencyList) {
            $ModuleName = $Dependency.Name
            if ($ModuleName -notin $InstalledModules) {
                $Status = Get-AzAutomationModule -ResourceGroupName $ResourceGroup -AutomationAccountName $AutomationAccount -Name $ModuleName -ErrorAction SilentlyContinue | select -ExpandProperty ProvisioningState
                sleep 3
                if ($Status -in ('Failed','Succeeded')) {
                    if ($Status -eq 'Succeeded') {
                        $InstalledModules.Add($ModuleName)
                    }

                    [PSCustomObject]@{
                        Status           = $Status
                        ModuleName       = $ModuleName
                        ModulesInstalled = $InstalledModules.Count
                    }
                }
            }
        }
        $LoopIndex++
    } until (($InstalledModules.Count -ge $GraphModule.Dependencies.count) -or ($LoopIndex -ge 10))
}

Conclusion

And just like that, we were able to install the Microsoft Graph Module for Azure Automation. One thing to note, This method only supports PowerShell version 5.1 at the moment so if you want to install the module for PowerShell 7 and later, you will still need to do that the manual way.
 

Since you’re now using Graph API with Azure Automation, here is a great article to use Managed Identities in your Automation Runbooks so you no longer have to worry about secrets or certificates in your code.

The post Install Microsoft Graph Module for Azure Automation using PowerShell appeared first on the Sysadmin Channel.

What is a Managed Identity?

An Azure managed identity is a feature of Azure Active Directory that enables Azure services to authenticate to cloud resources securely. It eliminates the need for you to store and manage the credentials for your applications and services, and helps you to follow the principle of least privilege by providing just-in-time access to resources.
 

There are two types of managed identities:

These identities are created when you enable the managed identity feature for an Azure resource and are tied to the lifecycle of that resource. When the resource is deleted, the managed identity is also deleted.

These identities are created independently of an Azure resource and can be assigned to multiple resources. This allows you to manage the identity in a central location and reuse it across multiple resources.

Using a managed identity can help you secure your application and make it easier to manage the authentication process since you no longer have to manage secrets or credentials in your code. For this article, we’re going to focus on using a system-assigned managed identity that’s created in the Azure Automation account.
 

Check out the Microsoft docs to learn more about managed identities

Requirements

In order to use an Azure managed identity, you need to ensure you meet the following requirements.

• An Azure subscription
• A Resource Group with Owner or user access administrator roles
• An Azure Automation Account
• The managed identity must be in the same region as the Automation Runbook
• This also applies to other Azure resources as well

Enable a Managed Identity for Azure Automation

Now that we have the requirements in place, let’s go ahead and start the process to enable a managed identity for Azure Automation. We’re going to assume you have already created an Automation account in your subscription.

Within your automation account:

• Click on Identity on the left pane
• Ensure the System assigned tab is selected
• Toggle the status from “Off” to “On”
• Copy the object (principal) Id to a notepad. We’ll need it later
• Click save

Grant Permissions to a Managed Identity

When a managed identity is created, it starts off with a clean slate and no permissions. This means that you will need to grant permissions to the resources that it needs to interact with.
 

In our example, we need to grant the managed identity from our Automation account access to read as well as run jobs from the Azure Automation Runbook. We can do this from the “Azure role assignments” button on the Identity blade, but I like to use PowerShell because it’s a lot faster.
 

  $ServicePrincipalId = '900d23ex-xxxx-xxxx-xxxx-xxxxxxxxxxxx' #Copied from the Identity blade above
  $ResourceGroupName = 'rg-azure-automation'
  New-AzRoleAssignment -ObjectId $ServicePrincipalId -ResourceGroupName $ResourceGroupName -RoleDefinitionName Reader
  New-AzRoleAssignment -ObjectId $ServicePrincipalId -ResourceGroupName $ResourceGroupName -RoleDefinitionName 'Automation Job Operator'
  New-AzRoleAssignment -ObjectId $ServicePrincipalId -ResourceGroupName $ResourceGroupName -RoleDefinitionName 'Automation Runbook Operator'

More importantly, we need to know how to grant the managed identity permissions to Graph API (most common) or other app role resources that you may need. Since Azure Automation Runbooks don’t require a secret or certificate to connect to Graph API, this is ideal and the most secured way since we’re letting Azure handle all the authentication process in the cloud.
 

#New Service Principal Permissions using Azure AD module
$ServicePrincipalId = '900d23ex-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
$GraphResource = Get-AzureADServicePrincipal -Filter "AppId eq '00000003-0000-0000-c000-000000000000'"
$Permission = $GraphResource.AppRoles | Where-Object {$_.value -eq 'User.Read.All'}
New-AzureADServiceAppRoleAssignment -ObjectId $ServicePrincipalId -PrincipalId $ServicePrincipalId -Id $Permission.Id -ResourceId $GraphResource.ObjectId


#New Service Principal Permissions using Graph API
$ServicePrincipalId = '900d23ex-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
$GraphResource = Get-MgServicePrincipal -Filter "AppId eq '00000003-0000-0000-c000-000000000000'"
$Permission = $GraphResource.AppRoles | Where-Object {$_.value -eq 'User.Read.All'}
New-MgServicePrincipalAppRoleAssignment -ServicePrincipalId $ServicePrincipalId -PrincipalId $ServicePrincipalId -AppRoleId $Permission.Id -ResourceId $GraphResource.Id

To view the permissions that are currently granted for a Service Principal, you can go to

• Azure AD
• Enterprise Applications
• Application Type == Managed Identity
• select the Service Principal
• select Permissions on the left scroll panel

Connect to Graph API using a Managed Identity in an Automation Runbook

Alright folks! We’ve added permissions to the managed identity to access resources in our resource group as well as added permissions to access/modify objects in Graph API. All that’s left is actually connecting to Graph API.
 

To make this happen, we’ll first need to have the Microsoft.Graph PowerShell module added under the modules for your automation account. If you’re using a Hybrid worker account and running the script on-premises, you’ll need to install the module on the on-premises machine that’s running the script.
 

In your Automation Runbook, edit the page and add these few lines. If you’re using parameters, be sure to add it after the param block. When you’re ready to publish, hit the publish button so it saves and publishes the script.

try {
    #Get the token using a managed identity and connect to graph using that token
    Connect-AzAccount -Identity -ErrorAction Stop | Out-Null
    $AccessToken = Get-AzAccessToken -ResourceTypeName MSGraph -ErrorAction Stop | select -ExpandProperty Token
    Connect-Graph -AccessToken $AccessToken -ErrorAction Stop | Out-Null

    Select-MgProfile -Name Beta
    Get-MgUser -UserId buzz@thesysadminchannel.com | select DisplayName, UserPrincipalName, UserType, AccountEnabled
} catch {
    Write-Error $_.Exception.Message -ErrorAction Stop
}     

We’ve published the script so let’s trigger it. You can trigger this by using the Start button in the Runbook, or trigger it from a Logic App. Either way, once it has completed running, it should display the output in the job details.
 

If you don’t see the output, be sure to check the Errors or Exception tabs to see where it failed.

Conclusion

Hopefully this article was able to help you connect to Graph API using a Managed Identity in an Automation Runbook. This method works great if you’re running the Runbook from Azure as well as a Hybrid Worker machine (on-premises machine).

The post Graph API using a Managed Identity in an Automation Runbook appeared first on the Sysadmin Channel.

Requirements

In order to successfully create groups in Graph API, we’ll need to ensure we have the right permissions needed. Let’s touch a bit on what those might be.

• User Administrator, Groups Administrator or Global Administrator Azure AD Role(s)
• Microsoft.Graph PowerShell SDK Module (if not using the REST API)
• Graph API Scopes:
• Delegated: Group.ReadWrite.All, Directory.ReadWrite.All
• Application: Group.Create, Group.ReadWrite.All, Directory.ReadWrite.All

Create A Group in Graph API with New-MgGroup

When creating groups in Azure AD, 99% of the time I create security enabled groups because I use them for providing access to specific resources. When I need to create groups with an email address, I use Distribution Lists (or Mail-enabled Security groups) in Exchange. Personally, I am not a fan of M365 (unified groups) but that’s a topic for another day.
 

Let’s dig into the code for creating a security group in Azure AD using Graph API.

$GroupParam = @{
     DisplayName = "SG-SecurityNoOwnerNoMember"
     GroupTypes = @(
     )
     SecurityEnabled     = $true
     IsAssignableToRole  = $false
     MailEnabled         = $false
     MailNickname        = (New-Guid).Guid.Substring(0,10)
}

New-MgGroup -BodyParameter $GroupParam

Create A Security Group with an Owner

We got the basics of creating a security group by using the PowerShell SDK and Graph API, but let’s add on to this by adding an owner to the group. You can add a Service Principal or a user account as an owner.
 

If you want to add a Service Principal, you’ll need to know the Service Principal Id so we can bind it to the parameters. If you’re looking to add a user, you can use the UserPrincipalName, or UserId. Let’s do this now.

$GroupParam = @{
     DisplayName = "SG-SecurityGroupWithOwner"
     GroupTypes = @(
     )
     SecurityEnabled     = $true
     IsAssignableToRole  = $false
     MailEnabled         = $false
     MailNickname        = (New-Guid).Guid.Substring(0,10)
     "Owners@odata.bind" = @(
         "https://graph.microsoft.com/v1.0/me",
         "https://graph.microsoft.com/v1.0/users/luke@thesysadminchannel.com",
         "https://graph.microsoft.com/v1.0/users/647e9c5e-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
         "https://graph.microsoft.com/v1.0/servicePrincipals/50ded543-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
     )
}
PS C:\> New-MgGroup -BodyParameter $GroupParam

Create A Group with an Owner and Members

Next up, let’s create a group with owners and a couple of members.

$GroupParam = @{
     DisplayName = "SG-SecurityGroupWithOwnerAndMembers"
     GroupTypes = @(
     )
     SecurityEnabled     = $true
     IsAssignableToRole  = $false
     MailEnabled         = $false
     MailNickname        = (New-Guid).Guid.Substring(0,10)
     "Owners@odata.bind" = @(
         "https://graph.microsoft.com/v1.0/me",
         "https://graph.microsoft.com/v1.0/users/luke@thesysadminchannel.com"
     )
     "Members@odata.bind" = @(
         "https://graph.microsoft.com/v1.0/me",
         "https://graph.microsoft.com/v1.0/users/buzz@thesysadminchannel.com"
     )
 }
New-MgGroup -BodyParameter $GroupParam

Create A Dynamic Security Group with Membership Rules

Last and certainly not least, let’s get started with creating dynamic groups to add members with specific criteria. In my case, I am just going to add a statement where the account is enabled and the UPN is mine.

$GroupParam = @{
     DisplayName = "SG-DynamicSecurityGroup"
     GroupTypes = @(
         'DynamicMembership'
     )
     SecurityEnabled     = $true
     IsAssignableToRole  = $false
     MailEnabled         = $false
     membershipRuleProcessingState = 'On'
     MembershipRule = '(user.accountEnabled -eq true) and (user.userPrincipalName -eq "paul@thesysadminchannel.com")'
     MailNickname        = (New-Guid).Guid.Substring(0,10)
     "Owners@odata.bind" = @(
         "https://graph.microsoft.com/v1.0/me"
     )
 }

New-MgGroup -BodyParameter $GroupParam

Conclusion

Hopefully this article was able to show you how to create a group in Graph API using the New-MgGroup cmdlet that comes with the Microsoft.Graph PowerShell SDK.

The post New-MgGroup: Create A Group in Graph API appeared first on the Sysadmin Channel.

Requirements

The use case may vary, sometimes you might want to check how many people read a recent communication that was sent by the organization. Other times you may need statistics for general read status. Whatever the case may be, it can be helpful to get this kind of data.
 

In order to set this up and check to see if a specific email was read or not, there are certain requirements that need to be put in place in order to successfully query a mailbox. Let’s cover those now.
 

• Microsoft.Graph PowerShell Module
• EXACT subject line of the email you’re searching for
• An Azure App Registration setup with following API permissions
• Directory.Read.All
• Mail.ReadBasic.All

How To Check If An Email Was Read using Graph API PowerShell SDK

Now that we have the Azure App Registration and Service Principal created with the above permissions, let’s look at how we can start getting message read status for our mail items.
 

Get-MSGraphMailReadStatus PowerShell Script

To give you some insight, this script uses Get-MgUserMessage graph cmdlet under the hood to get the actual message. There is also a parameter to see which folder the mail item is currently located. This helps if a user says they’ve lost an email, when in reality they’ve accidently dragged it into another folder without realizing it.
 

Function Get-MgMailReadStatus {
<#
.SYNOPSIS
    Get Email read status for users using Graph Api. A session using Connect-Graph must be open as a requirement.

.NOTES
    Name: Get-MgMailReadStatus
    Author: Paul Contreras
    Version: 1.3

.EXAMPLE
    Get-MgMailReadStatus -UserId user1@domain.com, user2@domain.com -Subject 'Exact Subject Line'

.EXAMPLE
    Get-MgMailReadStatus -UserId user1@domain.com -Subject 'Exact Subject Line' -SenderAddress user3@domain.com -StartDate 5/25/2020 -EndDate 10/28/2022 -ShowMailFolder

.PARAMETER UserId
    Checks against this persons mailbox.

.PARAMETER Subject
    Queries the mailbox using the exact text specified

.PARAMETER SenderAddress
    Specify the 'From' Address in your search.  Format should be user@domain.com

.PARAMETER StartDate
    Specify the date when the query should start filtering for.  Format should be MM/DD/YYYY

.PARAMETER EndDate
    Specify the date when the query should end the filter.  Format should be MM/DD/YYYY

.PARAMETER ShowMailFolder
    When this switch is used, it will display what folder the email is currently located in. This makes the overall query slower so use only when needed.

.PARAMETER Top
    Defaulted to 1.  This is the limit of emails per mailbox that you would like to find
#>

    [CmdletBinding()]
    param(
        [Parameter(
            Mandatory = $true,
            ValueFromPipeline = $true,
            ValueFromPipelineByPropertyName = $true,
            Position = 0
        )]
        [Alias('UserPrincipalName')]
        [string[]]  $UserId,


        [Parameter(
            Mandatory = $false,
            ValueFromPipeline = $false,
            ValueFromPipelineByPropertyName = $false
        )]
        [string]  $Subject,


        [Parameter(
            Mandatory = $false,
            ValueFromPipeline = $false,
            ValueFromPipelineByPropertyName = $false
        )]
        [string]  $SenderAddress,


        [Parameter(
            Mandatory = $false,
            ValueFromPipeline = $false,
            ValueFromPipelineByPropertyName = $false
        )]
        [string]  $StartDate,


        [Parameter(
            Mandatory = $false,
            ValueFromPipeline = $false,
            ValueFromPipelineByPropertyName = $false
        )]
        [string]  $EndDate,


        [Parameter(
            Mandatory = $false,
            ValueFromPipeline = $false,
            ValueFromPipelineByPropertyName = $false
        )]
        [switch]  $ShowMailFolder,


        [Parameter(
            Mandatory = $false,
            ValueFromPipeline = $false,
            ValueFromPipelineByPropertyName = $false
        )]
        [int]  $Top = 1,


        [Parameter(
            Mandatory = $false,
            ValueFromPipeline = $false,
            ValueFromPipelineByPropertyName = $false
        )]
        [switch]    $IncludeRepliesandForwards
    )

    BEGIN {
        $ConnectionGraph = Get-MgContext
        if (-not $ConnectionGraph) {
            Write-Error "Please connect to Microsoft Graph" -ErrorAction Stop
        }

        if ($PSBoundParameters.ContainsKey('StartDate') -and -not $PSBoundParameters.ContainsKey('EndDate')) {
            Write-Error "EndDate is required when a StartDate is entered" -ErrorAction Stop
        }


        if ($PSBoundParameters.ContainsKey('EndDate') -and -not $PSBoundParameters.ContainsKey('StartDate')) {
            Write-Error "StartDate is required when an EndDate is entered" -ErrorAction Stop
        }

        if ($PSBoundParameters.ContainsKey('IncludeRepliesandForwards') -and -not $PSBoundParameters.ContainsKey('Subject')) {
            Write-Error "A Subject is required to use IncludeRepliesandForwards" -ErrorAction Stop
        }

        $Date = Get-Date -Format g
    }

    PROCESS {
        foreach ($User in $UserId) {
            try {
                $GraphUser = Get-MgUser -UserId $User -ErrorAction Stop | select Id, DisplayName, UserPrincipalName
                Write-Verbose "Checking Status for $($GraphUser.DisplayName)"

                #Building the filter query
                if ($PSBoundParameters.ContainsKey('Subject')) {
                    if ($Subject -match "'") {
                        $Subject = $Subject -replace "'","''"
                    }

                    if (-not $PSBoundParameters.ContainsKey('IncludeRepliesandForwards')) {
                        $FilterQuery = "Subject eq '$Subject'"
                    }
                }


                if ($PSBoundParameters.ContainsKey('SenderAddress')) {
                    if ($FilterQuery) {
                        $FilterQuery = $FilterQuery + " AND from/emailAddress/address eq '$SenderAddress'"
                    } else {
                        $FilterQuery = "from/emailAddress/address eq '$SenderAddress'"
                    }
                }


                if ($PSBoundParameters.ContainsKey('StartDate') -and $PSBoundParameters.ContainsKey('EndDate')) {
                    $BeginDateFilter = (Get-Date $StartDate).AddDays(-1).ToString('yyyy-MM-dd') #Adding a day to either side to account for UTC time and MS operators.
                    $EndDateFilter = (Get-Date $EndDate).AddDays(1).ToString('yyyy-MM-dd')

                    if ($FilterQuery) {
                        $FilterQuery = $FilterQuery + " AND ReceivedDateTime ge $BeginDateFilter AND ReceivedDateTime le $EndDateFilter"
                    } else {
                        $FilterQuery = "ReceivedDateTime ge $BeginDateFilter AND ReceivedDateTime le $EndDateFilter"
                    }
                }


                if ($FilterQuery) {
                    if ($Top -gt 10) {
                        $Message = Get-MgUserMessage -UserId $User -Filter $FilterQuery -Top $Top -ErrorAction Stop | Sort-Object ReceivedDateTime -Descending
                      } else {
                        $Message = Get-MgUserMessage -UserId $User -Filter $FilterQuery           -ErrorAction Stop | Sort-Object ReceivedDateTime -Descending | select -First $Top
                    }

                    if ($PSBoundParameters.ContainsKey('IncludeRepliesandForwards')) {
                        $Message = $Message | Where-Object {$_.Subject -like "* $Subject"}
                    }
                } else {
                    $Message = Get-MgUserMessage -UserId $User -ErrorAction Stop | Sort-Object ReceivedDateTime -Descending | select -First $Top
                }


                #Building output object
                $Object = [Ordered]@{
                    RunDate            = $Date
                    MailboxDisplayName = $GraphUser.DisplayName
                    Mailbox            = $GraphUser.UserPrincipalName
                    UserId             = $GraphUser.Id
                    SenderAddress      = $null
                    SenderName         = $null
                    RecipientAddress   = $null
                    RecipientName      = $null
                    Subject            = $null
                    IsRead             = $null
                    HasAttachment      = $null
                    ReceivedDate       = $null
                    MessageId          = $null
                }

                if ($PSBoundParameters.ContainsKey('ShowMailFolder')) {
                    $Object.Add( 'MailFolder', $null )
                    $Object.Add( 'PSTypeName', 'GraphMailReadStatus.MailFolder')
                  } else {
                    $Object.Add( 'PSTypeName', 'GraphMailReadStatus')
                }

                if (-not $Message) {
                    Write-Verbose "0 Messages with the subject: '$Subject' were found on Mailbox: '$($GraphUser.DisplayName)'"

                    #Output object
                    [PSCustomObject]$Object

                } else {
                    Write-Verbose "$($Message.Count) Message(s) with the subject: '$Subject' were returned on Mailbox: '$($GraphUser.DisplayName)'"
                    foreach ($MailItem in $Message) {
                        $Object.SenderAddress      = $MailItem.sender.emailaddress | select -ExpandProperty Address
                        $Object.SenderName         = $MailItem.sender.emailaddress | select -ExpandProperty Name
                        $Object.RecipientAddress   = $MailItem.toRecipients.emailaddress | select -ExpandProperty Address
                        $Object.RecipientName      = $MailItem.toRecipients.emailaddress | select -ExpandProperty Name
                        $Object.Subject            = $MailItem.Subject
                        $Object.IsRead             = $MailItem.IsRead
                        $Object.HasAttachment      = $MailItem.HasAttachments
                        $Object.ReceivedDate       = $MailItem.ReceivedDateTime.ToLocalTime()
                        $Object.MessageId          = $MailItem.Id

                        if ($PSBoundParameters.ContainsKey('ShowMailFolder')) {
                            $MailFolder = Get-MgUserMailFolder -MailFolderId $MailItem.ParentFolderId -UserId $GraphUser.UserPrincipalName | select -ExpandProperty DisplayName

                            $Object.MailFolder = $MailFolder
                            $Object.PSTypeName = 'GraphMailReadStatus.MailFolder'

                          } else {
                            $Object.PSTypeName = 'GraphMailReadStatus'

                        }

                        [PSCustomObject]$Object

                        $Message    = $null
                        $MailItem   = $null
                        $MailFolder = $null
                    }
                }

            } catch {
                Write-Error $_.Exception.Message

            }

            #end foreach block
            $Object = $null
        }
    }

    END {}
}

Script Parameters

    -UserId

DataType: string/array
Description: Checks against this persons mailbox. Multiple UPNs/ObjectIds separated by a comma are acceptable.
 

    -Subject

DataType: string
Description: Queries the mailbox using the EXACT text specified
 

    -SenderAddress

DataType: string
Description: Specify the ‘From’ Address in your search. Format should be user@domain.com
 

    -StartDate

DataType: string
Description: Specify the date when the query should start filtering for. Format should be MM/DD/YYYY
 

    -EndDate

DataType: string
Description: Specify the date when the query should end the filter. Format should be MM/DD/YYYY
 

    -ShowMailFolder

DataType: switch
Description: When this switch is used, it will display what folder the email is currently located in. This makes the overall query slower so use only when needed
 

    -Top

DataType: int
Description: Defaulted to 1. This is the limit of emails per mailbox that you would like to find
 

Example 1 – Specifying a user, a subject and the parent folder

PS C:\> Get-MSGraphMailReadStatus -UserId paul@thesysadminchannel.com `
-Subject "You’ve renewed your Office 365 E1 subscription" -ShowMailFolder

Conclusion

Hopefully this article was able to show you how to check if an email was read using Graph API PowerShell. Since this utilizes Graph API, it supports PowerShell 7 and can be incredible fast when using Foreach-Object -Parallel. I’ve used this several times in my environment and its great addition to my tool belt.

The post Check If An Email Was Read using Graph API PowerShell SDK appeared first on the Sysadmin Channel.

Requirements

Since this will utilize Graph API to drive these requests, you’ll need the following rights on the Service Principal or account that’s making the modification.

• User.ReadWrite.All and Directory.ReadWrite.All Permissions
• Azure AD P1/P2 is needed for Group Based Licensing

Reprocess Users at the Group Level

Before we get started, I should preface this by saying that I am well aware that there is a way to reprocess the licenses at the group level. However, if you work in a large organization with tens of thousands of users in a group, this may take more time than what’s needed.
 

Also, in the event that you only need to reprocess a handful of users instead of the masses that are in the group, this would tend to make more sense.

Reprocessing done at the group level

Reprocess User License Assignments using Graph API and PowerShell

Now that we know how to connect to Graph API and opted to reprocess at the user level instead of the group level, let’s learn how to use Powershell so you can programmatically reprocess licenses on the user level.
 

This can be done using the Microsoft.Graph Powershell SDK module or calling the REST API directly.

Use the Microsoft.Graph Powershell SDK module

When using the Microsoft.Graph Powershell SDK you only need to use a single cmdlet.

Import-Module Microsoft.Graph.Users.Actions

Invoke-MgLicenseUser -UserId $userId

Use the REST API directly

If you want to call the REST API directly, you can simply do this.

Invoke-MgGraphRequest -Uri "https://graph.microsoft.com/v1.0/users/$userid/reprocessLicenseAssignment" -Method POST -ContentType application/json -Body "$null"

Since I’m a Powershell enthusiast and I love making scripts, I also wrote a wrapper before I knew the SDK command was available. So, in the spirit of sharing, I’ll post that code here.

Function Invoke-MsGraphReprocessLicenseAssignment {
<#
.SYNOPSIS
    Reprocess a user's license assignment using Graph Api


.NOTES
    Name: Invoke-MsGraphReprocessLicenseAssignment
    Author: Paul Contreras
    Version: 1.0
    DateCreated: 2021-Jan-20


.EXAMPLE
    Invoke-MsGraphReprocessLicenseAssignment -UserId username@domain.com

.LINK
    https://thesysadminchannel.com/reprocess-user-license-assignments-using-graph-api-and-powershell/ -

#>

    [CmdletBinding(
        SupportsShouldProcess,
        ConfirmImpact='Medium'
    )]
    param(
        [Parameter(
            Mandatory = $true,
            ValueFromPipeline = $true,
            ValueFromPipelineByPropertyName = $true
        )]
        [Alias('UserPrincipalName')]
        [string[]]  $UserId
    )

    BEGIN {}

    PROCESS {
        foreach ($User in $UserId) {
            try {
                $GraphUser = Get-MgUser -UserId $User | select -ExpandProperty Id

                if ($PSCmdlet.ShouldProcess("Reprocessing license assignments for: $User") ) {
                    $Reprocess = Invoke-MgGraphRequest -Uri "https://graph.microsoft.com/v1.0/users/$GraphUser/reprocessLicenseAssignment" -Method POST -ContentType application/json -Body "$null" -ErrorAction Stop

                    [PSCustomObject]@{
                        Id                = $Reprocess['id']
                        DisplayName       = $Reprocess['displayName']
                        UserPrincipalName = $Reprocess['userPrincipalName']
                        JobTitle          = $Reprocess['jobTitle']
                    }
                }

            } catch {
                Write-Error $_.Exception.Message

            }
        }
    }

    END {}
}

Conclusion

Hopefully this article was able to clearly show you how to reprocess user license assignments using Graph API and PowerShell. It’s been a great help to be able to reprocess users on a individual level without having to shake the bucket for thousands of users when it’s not needed.

The post Reprocess User License Assignments using Graph API and PowerShell appeared first on the Sysadmin Channel.

Previously, I had to get this information using the old MSOnline (MSOL) module, however, since that is also deprecated, I thought it would be a good opportunity to freshen up my MSGraph skills and get this going.

Requirements

In order for this to work, there are a couple of requirements that need to be put in place prior to running the script. While it is not a technical requirement, it would be ideal to have a basic understanding of Microsoft Graph API application and delegated permissions, scopes, apps, consent and maybe a sprinkle of Service Principals.
 

Now for the actual technical requirements:

• An App/Service Principal to connect to Graph API -or granted consent to connect to Graph API as yourself
• Microsoft.Graph PowerShell Module
• Graph API Scopes (Delegated or Application permissions)
• UserAuthenticationMethod.Read.All
• Directory.Read.All
• User.Read.All

Script Parameters

UserId

Specify the UserPrincipalName or Id for the user you want to check authentication methods for.

MethodType

Specify the method type you would like to filter for.

Get MFA Methods using MSGraph API

Now let’s get to the PowerShell script. As mentioned, this is a function that will gather all of the authentication methods a user has registered for their account. All Auth methods except for “Password Authentication” are strong authentication methods. Another note, this uses Get-MgUserAuthenticationMethod under the hood and formats everything in a way that’s human readable.

Function Get-MsGraphAuthenticationMethod {
<#
.SYNOPSIS
    List MFA Authentication Methods for users using Graph API. A session using Connect-Graph must be open as a requirement.


.NOTES
    Name: Get-MsGraphAuthenticationMethod
    Author: paul@thesysadminchannel.com
    Version: 1.1
    DateCreated: 2021-Jan-20


.EXAMPLE
    Get-MsGraphAuthenticationMethod -UserId user1@domain.com, user2@domain.com


.EXAMPLE
    Get-MsGraphAuthenticationMethod -UserId user1@domain.com, user2@domain.com -MethodType MicrosoftAuthenticatorApp, EmailAuthencation

.LINK
    https://thesysadminchannel.com/get-mfa-methods-using-msgraph-api-and-powershell-sdk/ -
#>

    [CmdletBinding()]
    param(
        [Parameter(
            Mandatory = $true,
            Position = 0
            )]
        [Alias('UserPrincipalName')]
        [string[]]  $UserId,


        [Parameter(
            Mandatory = $false
        )]
        [ValidateSet('AuthenticatorApp', 'PhoneAuthentication', 'Fido2', 'WindowsHelloForBusiness', 'EmailAuthentication', 'TemporaryAccessPass', 'Passwordless', 'SoftwareOath')]
        [string[]]   $MethodType
    )

    BEGIN {
        $ConnectionGraph = Get-MgContext
        if (-not $ConnectionGraph) {
            Write-Error "Please connect to Microsoft Graph" -ErrorAction Stop
        }

    }

    PROCESS {
        foreach ($User in $UserId) {
            try {
                $DeviceList = Get-MgUserAuthenticationMethod -UserId $User -ErrorAction Stop
                $DeviceOutput = foreach ($Device in $DeviceList) {

                    #Converting long method to short-hand human readable method type.
                    switch ($Device.AdditionalProperties["@odata.type"]) {
                        '#microsoft.graph.microsoftAuthenticatorAuthenticationMethod'  {
                            $MethodAuthType     = 'AuthenticatorApp'
                            $AdditionalProperties = $Device.AdditionalProperties["displayName"]
                        }

                        '#microsoft.graph.phoneAuthenticationMethod'                   {
                            $MethodAuthType     = 'PhoneAuthentication'
                            $AdditionalProperties = $Device.AdditionalProperties["phoneType", "phoneNumber"] -join ' '
                        }

                        '#microsoft.graph.passwordAuthenticationMethod'                {
                            $MethodAuthType     = 'PasswordAuthentication'
                            $AdditionalProperties = $Device.AdditionalProperties["displayName"]
                        }

                        '#microsoft.graph.fido2AuthenticationMethod'                   {
                            $MethodAuthType     = 'Fido2'
                            $AdditionalProperties = $Device.AdditionalProperties["model"]
                        }

                        '#microsoft.graph.windowsHelloForBusinessAuthenticationMethod' {
                            $MethodAuthType     = 'WindowsHelloForBusiness'
                            $AdditionalProperties = $Device.AdditionalProperties["displayName"]
                        }

                        '#microsoft.graph.emailAuthenticationMethod'                   {
                            $MethodAuthType     = 'EmailAuthentication'
                            $AdditionalProperties = $Device.AdditionalProperties["emailAddress"]
                        }

                        '#microsoft.graph.temporaryAccessPassAuthenticationMethod'        {
                            $MethodAuthType     = 'TemporaryAccessPass'
                            $AdditionalProperties = 'TapLifetime:' + $Device.AdditionalProperties["lifetimeInMinutes"] + 'm - Status:' + $Device.AdditionalProperties["methodUsabilityReason"]
                        }

                        '#microsoft.graph.passwordlessMicrosoftAuthenticatorAuthenticationMethod' {
                            $MethodAuthType     = 'Passwordless'
                            $AdditionalProperties = $Device.AdditionalProperties["displayName"]
                        }

                        '#microsoft.graph.softwareOathAuthenticationMethod' {
                            $MethodAuthType     = 'SoftwareOath'
                            $AdditionalProperties = $Device.AdditionalProperties["displayName"]
                        }
                    }

                    [PSCustomObject]@{
                        UserPrincipalName      = $User
                        AuthenticationMethodId = $Device.Id
                        MethodType             = $MethodAuthType
                        AdditionalProperties   = $AdditionalProperties
                    }
                }

                if ($PSBoundParameters.ContainsKey('MethodType')) {
                    $DeviceOutput | Where-Object {$_.MethodType -in $MethodType}
                  } else {
                    $DeviceOutput
                }

            } catch {
                Write-Error $_.Exception.Message

            } finally {
                $DeviceList           = $null
                $MethodAuthType       = $null
                $AdditionalProperties = $null

            }
        }
    }

    END {}

}

Script Examples

Get-MsGraphAuthenticationMethod -UserId pcontreras@thesysadminchannel.com, buzz@thesysadminchannel.com

Display all authentication methods for both Paul and Buzz

Get-MsGraphAuthenticationMethod -UserId pcontreras@thesysadminchannel.com, buzz@thesysadminchannel.com -MethodType AuthenticatorApp, TemporaryAccessPass

Display only AuthenticatorApp and Temporary Access Pass method types

Conclusion

Hopefully this script to Get MFA Methods using MSGraph API and PowerShell SDK would be useful to replace the legacy method of querying MSOnline to get the user’s strong auth methods. Since this utilizes Microsoft Graph and REST APIs in the backend, it can work extremely fast with PowerShell 7 and Foreach-Object -Parallel.
 

I use this on a regular basis to see if a user has MFA enabled on their account. The only downside so far is that it does not show the default method type, but I’m sure that’s somewhere down the pipeline.
 

If you liked this script and wanted to get more exposure to Graph API, I’ve just recently created the subreddit https://reddit.com/r/graphapi for folks to who want to learn and ask questions. I’m also going to be posting all my conversion scripts from the Azure AD module to GraphAPI so be sure check in time to time on our Graph API category posts

The post Get MFA Methods using MSGraph API and PowerShell SDK appeared first on the Sysadmin Channel.

If you’re interested in learning more about the decommission of Azure AD Graph, here’s a doc from Microsoft. Below is snippet from that article.

How To Connect To Microsoft Graph API Using PowerShell

This is going to be a pretty in-depth article on how to connect to Microsoft Graph API using PowerShell so hopefully it will give you a pretty good understanding of all the parts and pieces at play.

Feel free to use the table of contents to navigate through the individual topics.

Download Microsoft.Graph Powershell Module

In order to get started with Using Microsoft Graph API in your Powershell session, the first thing we want to do is install the Microsoft.Graph Module. This is more commonly known as the Microsoft Graph Powershell SDK and all the cmdlets in this module start with “Mg”. Another thing that I absolutely love about this module is that it works great with Powershell 7.

In this article I’m going to use PS7 but if you’re using PS5.1, everything is pretty much the same.

Install-Module Microsoft.Graph -Scope AllUsers -Force
Install-Module Microsoft.Graph.Beta -Scope AllUsers -Force

Note: -Scope AllUsers requires admin rights whereas -Scope CurrentUser does not.

Overview of Microsoft Graph API Scopes

One very important topic to understand when dipping your toes into using Microsoft Graph API are Scopes. Understanding Scopes will definitely ease the transition and flatten the learning curve. I’m not going to lie when I first started using it, I ran into many challenges. Especially with documentation! Since this is still relatively new there’s not a ton of articles or examples at the ready.
 

As with anything, the more you practice and learn, the easier it becomes. With that said, Microsoft Graph API as a whole encompasses all of the APIs that are available in your tenant. However under the hood, there’s an API for users, authentication methods, MS Teams, Azure Key Vault and many more but for simplicity sake it’s all referred to as Graph API.
 

Just because your account has permissions to a certain role, doesn’t mean it’s automatically granted that scope. Here’s a real world example for you.
 

Buzz Lightyear has the ‘User Administrator’ Azure AD Role which allows him to manage all aspects of users and groups, including resetting passwords for limited admins. However, if he only connects using the User.Read.All scope then it will not allow him to modify any properties on the account even though the underlying permissions are there.
 

A simple way to put it. Scopes are permissions for the session, whereas roles are permissions for the account. Hopefully that makes sense.

How To Get The Scope of a Cmdlet

It’s a good idea to only use the scopes that are applicable to the current session to ensure you’re not over-privileged at run-time. But how exactly do we know what scopes are needed for the cmdlets we want to use?
 

To answer this question, I always turn to Graph Explorer. It’s by far easier for me to quickly check here than read through the documentation. if you prefer the documentation, by all means go ahead but this has typically worked well for me.

Let’s take a look at Graph Explorer to give a better example of what I’m talking about.

Note: I am signed in as myself to allow queries from Graph Explorer to be ran under my tenant and my actual data. If you’re not signed in, sample data can be used.

In the screenshot above, I ran a sample query to list all of the items in my OneDrive. We can also see on the upper right pane under Permissions what scopes are needed. In this case, I should be good to go with ‘Files.Read.All’ if I plan on using it for reading files outside my own account.
 

However, one important thing to take note on is the Status column. All permissions require consent in order to run. An administrator can grant consent on behalf of the entire organization if needed, or grant consent to the individual identity. Once consent is granted, you will not need to reconsent on any future sessions since it stays tied to the identity. A lot of layers and restrictions are put in place so I see it as a security win!

How To Get The Scopes From The Current Session

Last but not least, if you’re connected and you want a reminder of what Scopes you’re currently using, you can always use the Get-MgContext cmdlet to display an output.

I am signed in under delegated permissions using Interactive Logon.

Connect to Microsoft Graph API Using Interactive Logon

The quickest and easiest way to connect to Microsoft Graph API using PowerShell is to use delegated permissions with interactive sign-in. The screenshot above shows the aftermath, however, let’s look at how we can get there.

• Open Powershell where the module was downloaded
• Type Connect-Graph
• Enter in the credentials in the browser that pops up
• You should see authentication complete

 
Something to note here is that simply calling Connect-Graph (Connect-MgGraph) is using the DEFAULT Graph PowerShell Application. Some folks aren’t comfortable with using that because it has all of the delegated permissions added, however, there is a way to use your own app for a specific purpose. This is useful so we’re not over-permissioning users. The way to do that is to use the AppId (ClientId) and omit the key credentials (certificate or secret)

Connect-Graph -AppId xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx -TenantId xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

There are some pros and cons with using interactive logon. The biggest drawback in my opinion is that this is in no way usable for automation, albeit, it’s also not intended for automation purposes.
 
If you’re looking to setup an account for automated use, creating an App Registration and Service Principal is definitely the route to go. Let’s continue along and go through the motions on how to set that up.

Creating an App Registration and Service Principal

As mentioned, using an App Registration along with a Service Principal is definitely the way to go when you want to use it for automation. This has really become my go-to because its quick, easy and removes a lot of the guess work. It’s also great for security but we’ll touch on that a little later.
 

That was kind of a lot to take in, so for now, let’s go through the steps to create an App Registration.

• In your Azure AD Tenant, navigate to AzureAD -> App registrations
• Direct Link: https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/RegisteredApps
• Click on New registration
• Enter in the preferred name. I’ll name mine ‘My Automation App‘
• Under supported account types: Choose Single tenant
• Under Redirect URI: choose web and set the URL address to http://localhost
• Click Register

Once that’s complete you should automatically be redirected back to App’s overview page. While you’re there, be sure to jot down the Application (client) Id and the Directory (tenant) ID. You’ll need this later when you’re making up your connection string but that’s it, You’ve made an app in your tenant.

Configure The App To Use Certificate Based Authentication

Now that we’ve talked a bit about Service Principals, it’s important to note that there are 2 methods to authenticating to your newly created application. Those methods are using a certificate or a client secret. We’ll cover both ways in this article, but we’ll start with certificates first.
 

Azure allows you to use a either a self-signed certificate or a certificate from your PKI infrastructure. The more secure route of these 2 options would definitely be your PKI infrastructure, but it’s also understandable that not every environment has one. I don’t have a PKI infrastructure in my lab so I’m going to share the steps with using a self-signed certificate. The end goal is have to a .pfx on the client machine and a .cer file that’s uploaded to Azure.

#splatting for human readability
$CertParam = @{
    'KeyAlgorithm'      = 'RSA'
    'KeyLength'         = 2048
    'KeyExportPolicy'   = 'NonExportable'
    'DnsName'           = 'server.thesysadminchannel.com'
    'FriendlyName'      = 'GraphApi - My Automation App'
    'CertStoreLocation' = 'Cert:\CurrentUser\My\'
    'NotAfter'          = (Get-Date).AddYears(1)
}

#Creating self signed cert with parameters from above.
$Cert = New-SelfSignedCertificate @CertParam

Note: The DnsName should be the Server’s Fully Qualified Domain Name (FQDN)

Import Self Signed Certificate to Azure AD

Once the self signed certificate is created from above, we’ll need to export it to a .cer and upload that to Azure AD. Since we’re already in Powershell, let’s export it using Powershell.

#Since we captured the output to the $Cert variable in our previous step.  We'll use that to specify the cert parameter. 
#The .cer file will exported to the user's desktop.

Export-Certificate -Cert $Cert -FilePath $Home\Desktop\MyAutomationApp.cer

Back in Azure AD:

• Navigate to Certificates & secrets
• Click the certificates tab
• Click Upload certificate
• Click the folder icon and browse to your desktop to select the exported cert
• Click Add

We can confirm that the certificate is now uploaded to the Azure application.

Configure The App To Use Client Secret Based Authentication

Our next option for authenticating to a Service Principal is being able to use a client secret. Not to throw shade at using secrets, but personally, I prefer using a certificate because I can get a bit more control over it and can prioritize security above all else.
 

What do you mean by that you may ask? Well, for one, a secret can be passed around and used anywhere just like a regular password can. Meaning a user/app owner can share this secret with other teammates and it’s up to the user to uphold the security measures.
 

Two, this introduces a chicken and egg scenario. Say this application was used for some kind of unattended automation, you’re going to need a way to automatically grab this secret to pass into the connection string. There are ways to programmatically retrieve this using Azure Key Vault or Secrets Management PowerShell Module but now you’ll need to store that password somewhere securely. Again, security will most likely be left to the user so your best case scenario is everything is encrypted and stored securely in a vault.

Or, worse case scenario the secret (along with the Appid and TenantId) are saved to that person’s personal github repo and has it open to the public. So before you go down this path, think about how your users would likely treat it.

Now that I got that off my chest, let’s move forward with generating a secret for your app.
 

Back in Azure AD:

• Navigate to Certificates & secrets
• Click the Client Secrets tab
• Click New client secret
• Enter a useful description. e.g TicketNumber and Person who’s primarily responsible for it
• Set the expiration date to the recommended 6 months
• Click Add

Important: Immediately copy the secret because once you leave the page it’s no longer accessible and you’ll have to generate a new one. Make sure it’s secured as well.

Configure API Permissions For The Application

Moving along to our next topic which will be to provide an overview of the API permissions that are going to be granted for the application. These permission sets can either be Application or Delegated. The scenario for which the application is used will most likely dictate which sets are used but let’s give a brief overview and how to set them.

Configure Application Permissions To Use For Unattended Automation

If you want your application to 100% automated, choosing Application permissions is going to be your best bet since it doesn’t require any user interaction whatsoever.

Going back into your application:

• Navigate to API permissions
• Choose Add a permission
• Choose Microsoft Graph (since this is what is most commonly used)
• Choose Application Permissions
• Select the permissions that are required for this app
• To get started, choose Dirctory.Read.All and User.Read.All
• Click Add
• Grant admin consent for your organization

Configure Delegated Permissions To Use For Interactive Sessions

As you can see, delegated permissions are located in the same place that application permissions are so you’ll just need to select that instead of the app box.
 

The key take away between the 2 permissions are this:

• Delegated Permissions: Used by apps that have a signed-in user present
• Application Permissions: Used by apps that run unattended automation. Application permissions can only be consented by an administrator

Depending on the permissions applied, admin consent will also be needed for the permissions. The Admin consent required column should notify you if consent is needed.

Connect Using A Service Principal and Certificate Based Authentication

We’re finally nearing the home stretch here and got our App registration and Service Principal created. Now we just need to bring it all together to connect to Microsoft Graph API using Powershell. In this case we’re going to start off by connecting using a certificate. Here’s how we do that.

$AppId = "90cb4cab-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
$TenantId = "95cb1f18-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
$Certificate = Get-ChildItem Cert:\CurrentUser\My\180CE345F9XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Connect-Graph -TenantId $TenantId -AppId $AppId -Certificate $Certificate

If all is successful, you should see “Welcome To Microsoft Graph!” Congrats, you’re now successfully connected to Microsoft Graph API using certificate based authentication!

Connect Using A Service Principal and Secret Based Authentication

If you decided going the secret route was the better option for your application, let’s take a second to show you how to connect using this method. To get started you will need to install the MSAL.PS Powershell module from the PSGallery.
 

This module allows you to create an access token which you will need to connect to MSGraph.

#Install MSAL.PS module for all users (requires admin rights)
Install-Module MSAL.PS -Scope AllUsers -Force

#Generate Access Token to use in the connection string to MSGraph
$AppId = '90cb4cab-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
$TenantId = '95cb1f18-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
$ClientSecret = 'app registration secret'

Import-Module MSAL.PS
$MsalToken = Get-MsalToken -TenantId $TenantId -ClientId $AppId -ClientSecret ($ClientSecret | ConvertTo-SecureString -AsPlainText -Force)

#Connect to Graph using access token
Connect-Graph -AccessToken $MsalToken.AccessToken

If all is successful, you should see “Welcome To Microsoft Graph!” Congrats, you’re now successfully connected to Microsoft Graph API using secret based authentication!

Set Microsoft Graph Profile to use v1.0 or Beta Versions

Microsoft has 2 versions of Graph API that we’re able to send requests to. v1.0 which is all generally available endpoints and beta, which is the prerelease version.

It’s important to note that some items will only work in the beta profile so you might want to give that a try if you see something online and want to try it for yourself. In any event, we can change profiles by using the Beta prefix on any cmdlet. Here is a simple example.

• Get-MgUser -UserId username@thesysadminchannel.com
• Get-MgBetaUser -UserId username@thesysadminchannel.com

Something to note when using the v1.0 and beta versions is that the beta returns more properties. The v1.0 cmdlet typically returns the skeleton properties so the query can run faster. Depending on what you’re querying, it is also a good idea to use the -Property parameter so you can get the attributes you need without having to call everything. This is essential for larger environments.

Powershell Graph API Examples

Finally we’re at a point where we’re able to connect To Microsoft Graph API using PowerShell to send some requests. I’ll get a user object and group object so you can see how quick and easy it is.

#Search user by UserPrincipalName
PS C:\> Get-MgUser -UserId buzz@thesysadminchannel.com | select UserPrincipalName, DisplayName

UserPrincipalName           DisplayName
-----------------           -----------
buzz@thesysadminchannel.com Buzz Lightyear

#Get Top 2 objects of Get-MgUser
PS C:\> Get-MgUser -Top 2 | select UserPrincipalName, DisplayName

UserPrincipalName               DisplayName
-----------------               -----------
aaduser3@thesysadminchannel.com aaduser3
aaduser4@thesysadminchannel.com aaduser4

#Get all the groups with fakegroup in the DisplayName
PS C:\> Get-MgGroup -Search "DisplayName:fakegroup" -ConsistencyLevel eventual | select DisplayName, Description

DisplayName    Description
-----------    -----------
SG - FakeGroup A group that's not real
FakeGroup

#Get group object by Id.
PS C:\> Get-MgGroup -GroupId 51fb0824-5318-448c-8de6-ffc06c192b0d

Id                                   DisplayName    Description             GroupTypes
--                                   -----------    -----------             ----------
51fb0824-5318-448c-8de6-ffc06c192b0d SG - FakeGroup A group that's not real {}

PS C:\>

Conclusion

I’m hoping this deep dive on how to connect to Microsoft Graph API using PowerShell was informative enough to get your started. As an IT Professional, this is something you can use to automate many of your Azure tasks. If you’re a developer, this can be useful to interact with other applications in your wheelhouse.
 

If you’re looking for more Powershell content, be sure to check out our category full of useful scripts. The same goes for Azure Active Directory. I’ll also be starting a new series of posts dedicated to Graph API so stay tuned.

The post How To Connect To Microsoft Graph API Using PowerShell appeared first on the Sysadmin Channel.