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.

I previously wrote a post about using the ActiveDirectory module with Get-ADUser. The idea was to find AD users using PowerShell and went over several advanced topics. Feel free to check that to get familiar with the overall commands since Get-ADGroup is going to use something similar.
 

Here, the Get-ADGroup cmdlet is going to be used to filter all groups that have no members and move them to a separate OU for further processing. Since we are a little cautious when it comes to making bulk changes like this, I would suggest moving them to a staging OU where they can be left there for 30-60 days. Since these groups are empty, chances are no one is going to be missing them but it’s a good idea to separate them first, then move forward with deleting.
 

Before we delete anything, I would strongly recommend you enable the AD recycle bin so you can recover objects without hesitation.
 

Find Empty Groups in Active Directory using PowerShell

#Get All empty groups in the entire domain. Be careful with Exchange and other built-in groups.
$AllEmptyGroupList = Get-ADGroup -Filter {Members -notlike "*" } -Properties Members, WhenChanged, WhenCreated

#Get all empty groups that have not been touched in longer than 6 months. Be careful with Exchange and other built-in groups.
$CutOffDate = (Get-Date).AddMonths(-6)
$SixMonthEmptyGroupList = Get-ADGroup -Filter {Members -notlike "*" -and WhenChanged -lt $CutOffDate} -Properties Members, WhenChanged, WhenCreated

#Get all stale groups from a specific OU (Preferred)
$EmptyGroupList = Get-ADGroup -Filter {Members -notlike "*" -and WhenChanged -lt $CutOffDate} -Properties Members, WhenChanged, WhenCreated -SearchBase 'OU=My Groups,DC=contoso,DC=com'

Hopefully, you were able to understand how to find empty groups in Active Directory using PowerShell to better manage your group lifecycle. If a group is empty and hasn’t been modified in over 6 months, it’s a pretty good sign that it is no longer needed and can be purged.
 

Again, I would highly recommend you enable the recycle bin but with this you should be able to start off slowly and decommissioning in whatever approach you feel necessary.

The post Find Empty Groups in Active Directory using PowerShell appeared first on the Sysadmin Channel.

Requirements

In order for you to get all of the synced organizational units as well as the synced attributes, there are a few things you must have in place. First things first, you need to have a supported version of Azure AD Connect installed. Since AAD Connect should be in a tier 0 security configuration, you may need to run this locally on the machine itself.

Get Synced OU Configuration in Azure AD Connect using PowerShell

If you have an Active Directory OU structure that’s pretty dense it may be challenging to figure out what exactly is being synced and what is not. My lab is pretty simple and straight forward but here are the organizational units that are synced and what’s shown from the GUI.

 
Let’s get this same information from PowerShell. Remember you will need to be logged in to the active AAD Connect server since that’s what is actually being synced to Azure AD.

#Get Connect information for your on-premises domain.
$SyncConnector = Get-ADSyncConnector | Where-Object {$_.Name -notmatch ' - aad'}

#Get OU inclusion list
$SyncConnector.Partitions.ConnectorPartitionScope.ContainerInclusionList

#Get OU exclusion list
$SyncConnector.Partitions.ConnectorPartitionScope.ContainerExclusionList

As you can see from the images above, the only OU I am syncing to Azure AD is the “Home” OU. I do have a few sub organizational units that are excluded from sync and that’s also shown in the PowerShell image. Hopefully this will paint a pretty picture when you need to see which OUs are synced.

Get Synced Attributes using PowerShell

If you need to get what attributes are syncing, there’s a way to get that information using PowerShell as well. Not all attributes will show with an Azure AD attribute, but this is a good start to see what’s there and what’s not.
 

It is important to note that attributes syncing from your on-premises Active Directory will not show up exactly the same in Azure AD. Therefore, we will show the on-premises sync connector as well as the Azure AD sync connector. This is key if you have custom mappings or have enabled directory extension attributes to use for custom claims.

#Get attributes syncing from on-premises Active Directory
$SyncConnector = Get-ADSyncConnector | Where-Object {$_.Name -notmatch ' - aad'}
$SyncConnector.AttributeInclusionList


#Get attributes syncing to Azure Active Directory
$SyncConnector = Get-ADSyncConnector | Where-Object {$_.Name -match ' - aad'}
$SyncConnector.AttributeInclusionList

Conclusion

Hopefully this article was able to show you how to get synced OU configuration in Azure AD Connect PowerShell as well as the attributes that are currently synced. This is pretty handy because when you open up the Azure AD Connect application, sync is temporarily disabled until the wizard is closed.
 

Being able to gather this information using PowerShell helps solve that problem so you can run it at anytime. If you would like to see more sysadmin content, be sure to check out our YouTube Channel

The post Get Synced OU Configuration in Azure AD Connect 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

In order to set this up without failure, there are a few things needed to get you on your way to using Exchange Online certificate based authentication. Let’s cover what’s needed right now.
 

• A certificate, either self signed or one issued by PKI
• Azure Application Administrator or Global Administrator
• Privilege Role Administrator or Global Administrator
• Exchange Online Management PowerShell module

Above are the requirements to allow you to connect to Exchange Online using certificates. I manage Exchange Online using PowerShell so I added that as well. If you’re looking for instructions on how to get that installed, check out this article to install the Exchange Online Management module for PowerShell.

Create a Self-Signed Certificate

First things first, I thought it would be best to start off by creating the self-signed certificate to get the ball rolling. If possible, I would recommend using a certificate issued by a public key infrastructure (PKI). The reason for that is because we know we can trust it, it is inherently more secure, and we can also revoke the cert should the situation call for it. The problem is not every environment has a PKI setup (my lab included).
 

As mentioned, we don’t have a PKI in our environment so we’ll make due with a self signed certificate. Luckily, Azure does support self signed certs so let’s get that created within PowerShell.
With PowerShell open, enter in the following:
 

#splatting for human readability
$CertParam = @{
    'KeyAlgorithm'      = 'RSA'
    'KeyLength'         = 2048
    'KeyExportPolicy'   = 'NonExportable'
    'DnsName'           = 'server.thesysadminchannel.com'
    'FriendlyName'      = 'Exchange Online Automation App'
    'CertStoreLocation' = 'Cert:\CurrentUser\My\'
    'NotAfter'          = (Get-Date).AddYears(1)
}
 
#Creating self signed cert with parameters from above.
$Cert = New-SelfSignedCertificate @CertParam

The above parameters do not allow you to export the certificate to another machine. I should also note that this is saving the certificate under the user context. If you want to store the certificate under the local machine context, you will need to run PowerShell as an administrator anytime you to connect. Allowing it under the local machine certificate store means other administrators on the machine would also be able to connect. So just be aware.
 

Now that we have the cert created, let’s export it so we can upload it to Azure when we create our application.

#Since we captured the output to the $Cert variable in our previous step.
#We will use that to specify the cert parameter. 
#The .cer file will exported to the user's desktop.
 
Export-Certificate -Cert $Cert -FilePath $Home\Desktop\ExchangeOnlineAutomation.cer

Create an Azure App Registration and Service Principal

To get started, we need to make sure we have the proper rights to get the application created. This is where you will need an Azure AD Application administrator (or Global administrator).
 

Within Azure AD:

• Navigate to App registrations → New registration

• Name your application accordingly. I’ve named mine Exchange Online Automation
• Select Accounts in this organizational directory only (Single tenant)
• Leave the Redirect URI empty
• Click Register to create the app

With your app now created:

• 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

Next we need to add the Exchange.ManageAsApp API permissions within the app so the application object can access the resource. To do this we need to add it through the manifest because we won’t be able to find it via the typical API permissions blade.
 

Within the app, navigate to the manifest blade and replace the requiredResourceAccess block with this code. Be sure to click save when it’s added.

"requiredResourceAccess": [
   {
      "resourceAppId": "00000002-0000-0ff1-ce00-000000000000",
      "resourceAccess": [
         {
            "id": "dc50a0fb-09a3-484d-be87-e023b12c6440",
            "type": "Role"
         }
      ]
   }
],

Once that is saved, we can verify it was added correctly by going back to API permissions. We will now see that Exchange.ManageAsApp is the only entry there.

 

However, we will notice that the app requires admin consent in order for it to be effective. Go ahead and consent to it now. Once complete, it should look like the image below.

Add Exchange Administrator Role

With our app now created and configured properly, we’ll need to grant the Exchange Administrator role to that app.
 

Within Azure AD:

• Navigate to Roles and administrators
• Search for Exchange and click on Exchange administrator

• You should be taken to the active assignments for the Exchange admin role
• Click on Add assignments

• Click no members selected link
• Search for the app name (Our is Exchange Online Automation)
• Click on the app to add it to the selection
• Click select
• Complete the prompts to add the role

We should now see our Service Principal listed as an active assignment.

Connect to Exchange Online using the Azure Application

Finally, we’re in a spot where we can put all of the pieces together and connect to Exchange Online using our Azure AD application (Service Principal). Again, since I use PowerShell to manage EXO, we’re going to connect using the Exchange Online Management module. Be sure to use the latest version.
 

Before we connect, let’s get the AppId. We’ll also need to know the tenant’s default onmicrosoft name. To get the AppId, go back to the overview page of the Application we created earlier.

 

$AppId = '9e46ef5x-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
$Certificate = Get-ChildItem Cert:\CurrentUser\My\A94FFE108DCxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
$TenantName = 'thesysadminchannel.onmicrosoft.com'

Connect-ExchangeOnline -AppId $AppId -Certificate $Certificate -Organization $TenantName -ShowBanner: $false

As you can see, we were able to successfully connect to Exchange Online and run the Get-Mailbox command against my account. As a side note, I’ve also chosen to not display the banner by using the ShowBanner: $false parameter in the command.

Conclusion

Hopefully this article on how to use Exchange Online certificate based authentication was insightful and you were able to implement it in your own organization. This is used pretty much daily to automate tasks in Exchange and it’s great that we don’t have to worry about usernames and passwords.
 

If you want more information on creating Azure apps and using Graph API, check out my in-depth article on how to Connect To Microsoft Graph API Using PowerShell.

The post Exchange Online Certificate Based Authentication 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.