From 3c2b14e76d686b1b9113048eef494f7cf059e7d2 Mon Sep 17 00:00:00 2001 From: stevemutungi Date: Mon, 13 Jan 2025 00:03:14 +0300 Subject: [PATCH] Adding Get User Role command --- .../Users/Get-EntraUserRole.ps1 | 119 +++++++++++ .../Users/Get-EntraBetaUserRole.ps1 | 119 +++++++++++ .../Users/Get-EntraBetaUserRole.md | 195 ++++++++++++++++++ .../Users/Get-EntraUserRole.md | 195 ++++++++++++++++++ test/Entra/Users/Get-EntraUserRole.Tests.ps1 | 79 +++++++ .../Users/Get-EntraBetaUserRole.Tests.ps1 | 79 +++++++ 6 files changed, 786 insertions(+) create mode 100644 module/Entra/Microsoft.Entra/Users/Get-EntraUserRole.ps1 create mode 100644 module/EntraBeta/Microsoft.Entra.Beta/Users/Get-EntraBetaUserRole.ps1 create mode 100644 module/docs/entra-powershell-beta/Users/Get-EntraBetaUserRole.md create mode 100644 module/docs/entra-powershell-v1.0/Users/Get-EntraUserRole.md create mode 100644 test/Entra/Users/Get-EntraUserRole.Tests.ps1 create mode 100644 test/EntraBeta/Users/Get-EntraBetaUserRole.Tests.ps1 diff --git a/module/Entra/Microsoft.Entra/Users/Get-EntraUserRole.ps1 b/module/Entra/Microsoft.Entra/Users/Get-EntraUserRole.ps1 new file mode 100644 index 0000000000..1f054edb5f --- /dev/null +++ b/module/Entra/Microsoft.Entra/Users/Get-EntraUserRole.ps1 @@ -0,0 +1,119 @@ +# ------------------------------------------------------------------------------ +# Copyright (c) Microsoft Corporation. All Rights Reserved. +# Licensed under the MIT License. See License in the project root for license information. +# ------------------------------------------------------------------------------ +function Get-EntraUserRole { + [CmdletBinding(DefaultParameterSetName = 'GetQuery')] + param ( + [Parameter(ParameterSetName = "GetQuery", ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, HelpMessage = "Filter to apply to the query.")] + [System.String] $Filter, + + [Parameter(ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, HelpMessage = "Retrieve all user roles.")] + [switch] $All, + + [Parameter(ParameterSetName = "GetVague", ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, HelpMessage = "Search for user roles.")] + [System.String] $SearchString, + + [Alias('ObjectId')] + [Parameter(Mandatory = $true, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, HelpMessage = "User object ID to retrieve.")] + [System.String] $UserId, + + [Alias('DirectoryRoleObjectId')] + [Parameter(Mandatory = $false, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, HelpMessage = "Directory Role ID to retrieve.")] + [System.String] $DirectoryRoleId, + + [Alias('Limit')] + [Parameter(ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, HelpMessage = "Maximum number of results to return.")] + [System.Nullable`1[System.Int32]] $Top, + + [Alias('Select')] + [Parameter(Mandatory = $false, ValueFromPipeline = $false, ValueFromPipelineByPropertyName = $true, HelpMessage = "Properties to include in the results.")] + [System.String[]] $Property + ) + + PROCESS { + $params = @{} + $customHeaders = New-EntraCustomHeaders -Command $MyInvocation.MyCommand + $keysChanged = @{ SearchString = "Filter" } + + if ($null -ne $PSBoundParameters["ErrorAction"]) { + $params["ErrorAction"] = $PSBoundParameters["ErrorAction"] + } + if ($null -ne $PSBoundParameters["DirectoryRoleId"]) { + $params["DirectoryObjectId"] = $PSBoundParameters["DirectoryRoleId"] + } + if ($null -ne $PSBoundParameters["UserId"]) { + $params["UserId"] = $PSBoundParameters["UserId"] + } + if ($PSBoundParameters.ContainsKey("Verbose")) { + $params["Verbose"] = $PSBoundParameters["Verbose"] + } + if ($null -ne $PSBoundParameters["OutVariable"]) { + $params["OutVariable"] = $PSBoundParameters["OutVariable"] + } + if ($null -ne $PSBoundParameters["InformationAction"]) { + $params["InformationAction"] = $PSBoundParameters["InformationAction"] + } + if ($null -ne $PSBoundParameters["WarningVariable"]) { + $params["WarningVariable"] = $PSBoundParameters["WarningVariable"] + } + if ($PSBoundParameters.ContainsKey("Debug")) { + $params["Debug"] = $PSBoundParameters["Debug"] + } + if ($null -ne $PSBoundParameters["PipelineVariable"]) { + $params["PipelineVariable"] = $PSBoundParameters["PipelineVariable"] + } + if ($null -ne $PSBoundParameters["SearchString"]) { + $TmpValue = $PSBoundParameters["SearchString"] + $Value = "displayName eq '$TmpValue' or startsWith(displayName,'$TmpValue')" + $params["Filter"] = $Value + } + if ($null -ne $PSBoundParameters["ErrorVariable"]) { + $params["ErrorVariable"] = $PSBoundParameters["ErrorVariable"] + } + if ($null -ne $PSBoundParameters["Top"]) { + $params["Top"] = $PSBoundParameters["Top"] + } + if ($null -ne $PSBoundParameters["OutBuffer"]) { + $params["OutBuffer"] = $PSBoundParameters["OutBuffer"] + } + if ($null -ne $PSBoundParameters["All"]) { + if ($PSBoundParameters["All"]) { + $params["All"] = $PSBoundParameters["All"] + } + } + if ($null -ne $PSBoundParameters["WarningAction"]) { + $params["WarningAction"] = $PSBoundParameters["WarningAction"] + } + if ($null -ne $PSBoundParameters["ErrorVariable"]) { + $params["ErrorVariable"] = $PSBoundParameters["ErrorVariable"] + } + if ($null -ne $PSBoundParameters["InformationVariable"]) { + $params["InformationVariable"] = $PSBoundParameters["InformationVariable"] + } + if ($null -ne $PSBoundParameters["Property"]) { + $params["Property"] = $PSBoundParameters["Property"] + } + + # Debug logging for transformations + Write-Debug "============================ TRANSFORMATIONS ============================" + $params.Keys | ForEach-Object { "$_ : $($params[$_])" } | Write-Debug + Write-Debug "=========================================================================`n" + + try { + # Make the API call with -PageSize 999 if -All is used + if ($PSBoundParameters.ContainsKey("All") -and $All) { + $response = Get-MgUserMemberOfAsDirectoryRole @params -PageSize 999 -Headers $customHeaders + } + else { + $response = Get-MgUserMemberOfAsDirectoryRole @params -Headers $customHeaders + } + + return $response + } + catch { + # Handle any errors that occur during the API call + Write-Error "An error occurred while retrieving the user roles: $_" + } + } +} \ No newline at end of file diff --git a/module/EntraBeta/Microsoft.Entra.Beta/Users/Get-EntraBetaUserRole.ps1 b/module/EntraBeta/Microsoft.Entra.Beta/Users/Get-EntraBetaUserRole.ps1 new file mode 100644 index 0000000000..027f587111 --- /dev/null +++ b/module/EntraBeta/Microsoft.Entra.Beta/Users/Get-EntraBetaUserRole.ps1 @@ -0,0 +1,119 @@ +# ------------------------------------------------------------------------------ +# Copyright (c) Microsoft Corporation. All Rights Reserved. +# Licensed under the MIT License. See License in the project root for license information. +# ------------------------------------------------------------------------------ +function Get-EntraBetaUserRole { + [CmdletBinding(DefaultParameterSetName = 'GetQuery')] + param ( + [Parameter(ParameterSetName = "GetQuery", ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, HelpMessage = "Filter to apply to the query.")] + [System.String] $Filter, + + [Parameter(ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, HelpMessage = "Retrieve all user roles.")] + [switch] $All, + + [Parameter(ParameterSetName = "GetVague", ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, HelpMessage = "Search for user roles.")] + [System.String] $SearchString, + + [Alias('ObjectId')] + [Parameter(Mandatory = $true, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, HelpMessage = "User object ID to retrieve.")] + [System.String] $UserId, + + [Alias('DirectoryObjectId')] + [Parameter(Mandatory = $false, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, HelpMessage = "Directory Role ID to retrieve.")] + [System.String] $DirectoryRoleId, + + [Alias('Limit')] + [Parameter(ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, HelpMessage = "Maximum number of results to return.")] + [System.Nullable`1[System.Int32]] $Top, + + [Alias('Select')] + [Parameter(Mandatory = $false, ValueFromPipeline = $false, ValueFromPipelineByPropertyName = $true, HelpMessage = "Properties to include in the results.")] + [System.String[]] $Property + ) + + PROCESS { + $params = @{} + $customHeaders = New-EntraBetaCustomHeaders -Command $MyInvocation.MyCommand + $keysChanged = @{ SearchString = "Filter" } + + if ($null -ne $PSBoundParameters["ErrorAction"]) { + $params["ErrorAction"] = $PSBoundParameters["ErrorAction"] + } + if ($null -ne $PSBoundParameters["DirectoryRoleId"]) { + $params["DirectoryObjectId"] = $PSBoundParameters["DirectoryRoleId"] + } + if ($null -ne $PSBoundParameters["UserId"]) { + $params["UserId"] = $PSBoundParameters["UserId"] + } + if ($PSBoundParameters.ContainsKey("Verbose")) { + $params["Verbose"] = $PSBoundParameters["Verbose"] + } + if ($null -ne $PSBoundParameters["OutVariable"]) { + $params["OutVariable"] = $PSBoundParameters["OutVariable"] + } + if ($null -ne $PSBoundParameters["InformationAction"]) { + $params["InformationAction"] = $PSBoundParameters["InformationAction"] + } + if ($null -ne $PSBoundParameters["WarningVariable"]) { + $params["WarningVariable"] = $PSBoundParameters["WarningVariable"] + } + if ($PSBoundParameters.ContainsKey("Debug")) { + $params["Debug"] = $PSBoundParameters["Debug"] + } + if ($null -ne $PSBoundParameters["PipelineVariable"]) { + $params["PipelineVariable"] = $PSBoundParameters["PipelineVariable"] + } + if ($null -ne $PSBoundParameters["SearchString"]) { + $TmpValue = $PSBoundParameters["SearchString"] + $Value = "displayName eq '$TmpValue' or startsWith(displayName,'$TmpValue')" + $params["Filter"] = $Value + } + if ($null -ne $PSBoundParameters["ErrorVariable"]) { + $params["ErrorVariable"] = $PSBoundParameters["ErrorVariable"] + } + if ($null -ne $PSBoundParameters["Top"]) { + $params["Top"] = $PSBoundParameters["Top"] + } + if ($null -ne $PSBoundParameters["OutBuffer"]) { + $params["OutBuffer"] = $PSBoundParameters["OutBuffer"] + } + if ($null -ne $PSBoundParameters["All"]) { + if ($PSBoundParameters["All"]) { + $params["All"] = $PSBoundParameters["All"] + } + } + if ($null -ne $PSBoundParameters["WarningAction"]) { + $params["WarningAction"] = $PSBoundParameters["WarningAction"] + } + if ($null -ne $PSBoundParameters["ErrorVariable"]) { + $params["ErrorVariable"] = $PSBoundParameters["ErrorVariable"] + } + if ($null -ne $PSBoundParameters["InformationVariable"]) { + $params["InformationVariable"] = $PSBoundParameters["InformationVariable"] + } + if ($null -ne $PSBoundParameters["Property"]) { + $params["Property"] = $PSBoundParameters["Property"] + } + + # Debug logging for transformations + Write-Debug "============================ TRANSFORMATIONS ============================" + $params.Keys | ForEach-Object { "$_ : $($params[$_])" } | Write-Debug + Write-Debug "=========================================================================`n" + + try { + # Make the API call with -PageSize 999 if -All is used + if ($PSBoundParameters.ContainsKey("All") -and $All) { + $response = Get-MgBetaUserMemberOfAsDirectoryRole @params -PageSize 999 -Headers $customHeaders + } + else { + $response = Get-MgBetaUserMemberOfAsDirectoryRole @params -Headers $customHeaders + } + + return $response + } + catch { + # Handle any errors that occur during the API call + Write-Error "An error occurred while retrieving the user roles: $_" + } + } +} \ No newline at end of file diff --git a/module/docs/entra-powershell-beta/Users/Get-EntraBetaUserRole.md b/module/docs/entra-powershell-beta/Users/Get-EntraBetaUserRole.md new file mode 100644 index 0000000000..c770d391f6 --- /dev/null +++ b/module/docs/entra-powershell-beta/Users/Get-EntraBetaUserRole.md @@ -0,0 +1,195 @@ +--- +title: Get-EntraBetaUserRole +description: This article provides details on the Get-EntraBetaUserRole command. + + +ms.topic: reference +ms.date: 12/02/2024 +ms.author: eunicewaweru +ms.reviewer: stevemutungi +manager: CelesteDG + +external help file: Microsoft.Entra.Beta.Users-Help.xml +Module Name: Microsoft.Entra.Beta +online version: https://learn.microsoft.com/powershell/module/Microsoft.Entra.Beta/Get-EntraBetaUserRole + +schema: 2.0.0 +--- + +# Get-EntraBetaUserRole + +## Synopsis + +Retrieves the list of directory roles assigned to a user. + +## Syntax + +### GetQuery (Default) + +```powershell +Get-EntraBetaUserRole + -UserId + [-DirectoryRoleId ] + [-All] + [-Top ] + [-Property ] + [] +``` + +## Description + +The `Get-EntraBetaUserRole` cmdlet Retrieves the list of directory roles assigned to a specific user. + +## Examples + +### Example 1: Get list of directory roles assigned to a specific user + +```powershell +Connect-Entra -Scopes 'Directory.Read.All' +Get-EntraBetaUserRole -UserId 'SawyerM@contoso.com' +``` + +```Output +DeletedDateTime Id DisplayName RoleTemplateId +--------------- -- ----------- -------------- + bbbbbbbb-1111-2222-3333-ccccccccccc Helpdesk Administrator 729827e3-9c14-49f7-bb1b-9608f156bbb8 + dddddddd-3333-4444-5555-eeeeeeeeeeee Directory Readers 88d8e3e3-8f55-4a1e-953a-9b9898b8876b + cccccccc-2222-3333-4444-dddddddddddd Application Administrator 9b895d92-2cd3-44c7-9d02-a6ac2d5ea5c3 + aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb Guest Inviter 95e79109-95c0-4d8e-aee3-d01accf2d47b +``` + +This cmdlet retrieves the list of directory roles for a specific user. + +### Example 2: Get directory roles for a specific user using All parameter + +```powershell +Connect-Entra -Scopes 'Directory.Read.All' +Get-EntraBetaUserRole -UserId 'SawyerM@contoso.com' -All +``` + +```Output +DeletedDateTime Id DisplayName RoleTemplateId +--------------- -- ----------- -------------- + bbbbbbbb-1111-2222-3333-ccccccccccc Helpdesk Administrator 729827e3-9c14-49f7-bb1b-9608f156bbb8 + dddddddd-3333-4444-5555-eeeeeeeeeeee Directory Readers 88d8e3e3-8f55-4a1e-953a-9b9898b8876b + cccccccc-2222-3333-4444-dddddddddddd Application Administrator 9b895d92-2cd3-44c7-9d02-a6ac2d5ea5c3 + aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb Guest Inviter 95e79109-95c0-4d8e-aee3-d01accf2d47b +``` + +This cmdlet retrieves the directory roles for a specific user using All parameter. + +### Example 3: Get top two directory roles for a specific user + +```powershell +Connect-Entra -Scopes 'Directory.Read.All' +Get-EntraBetaUserRole -UserId 'SawyerM@contoso.com' -Top 2 +``` + +```Output +DeletedDateTime Id DisplayName RoleTemplateId +--------------- -- ----------- -------------- + bbbbbbbb-1111-2222-3333-ccccccccccc Helpdesk Administrator 729827e3-9c14-49f7-bb1b-9608f156bbb8 + dddddddd-3333-4444-5555-eeeeeeeeeeee Directory Readers 88d8e3e3-8f55-4a1e-953a-9b9898b8876b +``` + +This cmdlet retrieves top two directory roles for a specific user. + +### Example 4: Get assigned directory roles for a specific user by DirectoryRoleId + +```powershell +Connect-Entra -Scopes 'Directory.Read.All' +$role = Get-EntraBetaDirectoryRole -Filter "displayName eq 'Helpdesk Administrator'" +Get-EntraBetaUserRole -UserId 'SawyerM@contoso.com' -DirectoryRoleId $role.Id +``` + +```Output +DeletedDateTime Id DisplayName RoleTemplateId +--------------- -- ----------- -------------- + bbbbbbbb-1111-2222-3333-ccccccccccc Helpdesk Administrator 729827e3-9c14-49f7-bb1b-9608f156bbb8 +``` + +This cmdlet retrieves the directory roles for a specific user by DirectoryRoleId parameter. + +- `-DirectoryRoleId` parameter specifies the Directory role ID. + +## Parameters + +### -All + +List all pages. + +```yaml +Type: System.Management.Automation.SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Top + +The maximum number of the directory roles assigned to a specific user. + +```yaml +Type: System.Int32 +Parameter Sets: GetQuery +Aliases: Limit + +Required: False +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName, ByValue) +Accept wildcard characters: False +``` + +### -Property + +Specifies properties to be returned + +```yaml +Type: System.String[] +Parameter Sets: (All) +Aliases: Select + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -DirectoryRoleId + +The unique ID of the directory role. + +```yaml +Type: System.String +Parameter Sets: GetQuery +Aliases: DirectoryRoleObjectId + +Required: True +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName, ByValue) +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: `-Debug`, `-ErrorAction`, `-ErrorVariable`, `-InformationAction`, `-InformationVariable`, `-OutVariable`, `-OutBuffer`, `-PipelineVariable`, `-Verbose`, `-WarningAction`, and `-WarningVariable`. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). + +## Inputs + +## Outputs + +### System.Object + +## Notes + +## Related Links + +[Get-EntraBetaUserMembership](Get-EntraBetaUserMembership.md) diff --git a/module/docs/entra-powershell-v1.0/Users/Get-EntraUserRole.md b/module/docs/entra-powershell-v1.0/Users/Get-EntraUserRole.md new file mode 100644 index 0000000000..59fac4a71c --- /dev/null +++ b/module/docs/entra-powershell-v1.0/Users/Get-EntraUserRole.md @@ -0,0 +1,195 @@ +--- +title: Get-EntraUserRole +description: This article provides details on the Get-EntraUserRole command. + + +ms.topic: reference +ms.date: 12/02/2024 +ms.author: eunicewaweru +ms.reviewer: stevemutungi +manager: CelesteDG + +external help file: Microsoft.Entra.Users-Help.xml +Module Name: Microsoft.Entra +online version: https://learn.microsoft.com/powershell/module/Microsoft.Entra/Get-EntraUserRole + +schema: 2.0.0 +--- + +# Get-EntraUserRole + +## Synopsis + +Retrieves the list of directory roles assigned to a user. + +## Syntax + +### GetQuery (Default) + +```powershell +Get-EntraUserRole + -UserId + [-DirectoryRoleId ] + [-All] + [-Top ] + [-Property ] + [] +``` + +## Description + +The `Get-EntraUserRole` cmdlet Retrieves the list of directory roles assigned to a specific user. + +## Examples + +### Example 1: Get list of directory roles assigned to a specific user + +```powershell +Connect-Entra -Scopes 'Directory.Read.All' +Get-EntraUserRole -UserId 'SawyerM@contoso.com' +``` + +```Output +DeletedDateTime Id DisplayName RoleTemplateId +--------------- -- ----------- -------------- + bbbbbbbb-1111-2222-3333-ccccccccccc Helpdesk Administrator 729827e3-9c14-49f7-bb1b-9608f156bbb8 + dddddddd-3333-4444-5555-eeeeeeeeeeee Directory Readers 88d8e3e3-8f55-4a1e-953a-9b9898b8876b + cccccccc-2222-3333-4444-dddddddddddd Application Administrator 9b895d92-2cd3-44c7-9d02-a6ac2d5ea5c3 + aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb Guest Inviter 95e79109-95c0-4d8e-aee3-d01accf2d47b +``` + +This cmdlet retrieves the list of directory roles for a specific user. + +### Example 2: Get directory roles for a specific user using All parameter + +```powershell +Connect-Entra -Scopes 'Directory.Read.All' +Get-EntraUserRole -UserId 'SawyerM@contoso.com' -All +``` + +```Output +DeletedDateTime Id DisplayName RoleTemplateId +--------------- -- ----------- -------------- + bbbbbbbb-1111-2222-3333-ccccccccccc Helpdesk Administrator 729827e3-9c14-49f7-bb1b-9608f156bbb8 + dddddddd-3333-4444-5555-eeeeeeeeeeee Directory Readers 88d8e3e3-8f55-4a1e-953a-9b9898b8876b + cccccccc-2222-3333-4444-dddddddddddd Application Administrator 9b895d92-2cd3-44c7-9d02-a6ac2d5ea5c3 + aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb Guest Inviter 95e79109-95c0-4d8e-aee3-d01accf2d47b +``` + +This cmdlet retrieves the directory roles for a specific user using All parameter. + +### Example 3: Get top two directory roles for a specific user + +```powershell +Connect-Entra -Scopes 'Directory.Read.All' +Get-EntraUserRole -UserId 'SawyerM@contoso.com' -Top 2 +``` + +```Output +DeletedDateTime Id DisplayName RoleTemplateId +--------------- -- ----------- -------------- + bbbbbbbb-1111-2222-3333-ccccccccccc Helpdesk Administrator 729827e3-9c14-49f7-bb1b-9608f156bbb8 + dddddddd-3333-4444-5555-eeeeeeeeeeee Directory Readers 88d8e3e3-8f55-4a1e-953a-9b9898b8876b +``` + +This cmdlet retrieves top two directory roles for a specific user. + +### Example 4: Get assigned directory roles for a specific user by DirectoryRoleId + +```powershell +Connect-Entra -Scopes 'Directory.Read.All' +$role = Get-EntraDirectoryRole -Filter "displayName eq 'Helpdesk Administrator'" +Get-EntraUserRole -UserId 'SawyerM@contoso.com' -DirectoryRoleId $role.Id +``` + +```Output +DeletedDateTime Id DisplayName RoleTemplateId +--------------- -- ----------- -------------- + bbbbbbbb-1111-2222-3333-ccccccccccc Helpdesk Administrator 729827e3-9c14-49f7-bb1b-9608f156bbb8 +``` + +This cmdlet retrieves the directory roles for a specific user by DirectoryRoleId parameter. + +- `-DirectoryRoleId` parameter specifies the Directory role ID. + +## Parameters + +### -All + +List all pages. + +```yaml +Type: System.Management.Automation.SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Top + +The maximum number of the directory roles assigned to a specific user. + +```yaml +Type: System.Int32 +Parameter Sets: GetQuery +Aliases: Limit + +Required: False +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName, ByValue) +Accept wildcard characters: False +``` + +### -Property + +Specifies properties to be returned + +```yaml +Type: System.String[] +Parameter Sets: (All) +Aliases: Select + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -DirectoryRoleId + +The unique ID of the directory role. + +```yaml +Type: System.String +Parameter Sets: GetQuery +Aliases: DirectoryRoleObjectId + +Required: True +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName, ByValue) +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: `-Debug`, `-ErrorAction`, `-ErrorVariable`, `-InformationAction`, `-InformationVariable`, `-OutVariable`, `-OutBuffer`, `-PipelineVariable`, `-Verbose`, `-WarningAction`, and `-WarningVariable`. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). + +## Inputs + +## Outputs + +### System.Object + +## Notes + +## Related Links + +[Get-EntraUserMembership](Get-EntraUserMembership.md) diff --git a/test/Entra/Users/Get-EntraUserRole.Tests.ps1 b/test/Entra/Users/Get-EntraUserRole.Tests.ps1 new file mode 100644 index 0000000000..a41cdcbbf3 --- /dev/null +++ b/test/Entra/Users/Get-EntraUserRole.Tests.ps1 @@ -0,0 +1,79 @@ +# ------------------------------------------------------------------------------ +# Copyright (c) Microsoft Corporation. All Rights Reserved. +# Licensed under the MIT License. See License in the project root for license information. +# ------------------------------------------------------------------------------ + +BeforeAll { + if ((Get-Module -Name Microsoft.Entra.Users) -eq $null) { + Import-Module Microsoft.Entra.Users + } + Import-Module (Join-Path $PSScriptRoot "..\..\Common-Functions.ps1") -Force + + $scriptblock = { + return @( + [PSCustomObject]@{ + "DisplayName" = "Helpdesk Administrator" + "Id" = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb" + "Description" = "Can reset passwords for non-administrators and Helpdesk Administrators." + "Members" = "null" + "DeletedDateTime" = "10/28/2024 4:16:02 PM" + "RoleTemplateId" = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb" + } + ) + } + + Mock -CommandName Get-MgUserMemberOfAsDirectoryRole -MockWith $scriptblock -ModuleName Microsoft.Entra.Users +} + +Describe "Get-EntraUserRole" { + Context "Test for Get-EntraUserRole" { + It "Should return all user roles" { + $result = Get-EntraUserRole -UserId 'SawyerM@contoso.com' + $result | Should -Not -BeNullOrEmpty + Should -Invoke -CommandName Get-MgUserMemberOfAsDirectoryRole -ModuleName Microsoft.Entra.Users -Times 1 + } + + It "Should return top user role" { + $result = Get-EntraUserRole -UserId 'SawyerM@contoso.com' -Top 1 + $result | Should -Not -BeNullOrEmpty + Should -Invoke -CommandName Get-MgUserMemberOfAsDirectoryRole -ModuleName Microsoft.Entra.Users -Times 1 + } + + It "Property parameter should work" { + $result = Get-EntraUserRole -UserId 'SawyerM@contoso.com' -Property "DisplayName" + $result | Should -Not -BeNullOrEmpty + $result.DisplayName | Should -Be "Helpdesk Administrator" + Should -Invoke -CommandName Get-MgUserMemberOfAsDirectoryRole -ModuleName Microsoft.Entra.Users -Times 1 + } + + It "Should fail when Property is empty" { + { Get-EntraUserRole -UserId 'SawyerM@contoso.com' -Property } | Should -Throw "Missing an argument for parameter 'Property'*" + } + + It "Should contain 'User-Agent' header" { + $userAgentHeaderValue = "PowerShell/$psVersion EntraPowershell/$entraVersion Get-EntraUserRole" + $result = Get-EntraUserRole -UserId 'SawyerM@contoso.com' + $result | Should -Not -BeNullOrEmpty + $userAgentHeaderValue = "PowerShell/$psVersion EntraPowershell/$entraVersion Get-EntraUserRole" + Should -Invoke -CommandName Get-MgUserMemberOfAsDirectoryRole -ModuleName Microsoft.Entra.Users -Times 1 -ParameterFilter { + $Headers.'User-Agent' | Should -Be $userAgentHeaderValue + $true + } + } + + It "Should execute successfully without throwing an error" { + # Disable confirmation prompts + $originalDebugPreference = $DebugPreference + $DebugPreference = 'Continue' + + try { + # Act & Assert: Ensure the function doesn't throw an exception + { Get-EntraUserRole -UserId 'SawyerM@contoso.com' -Debug } | Should -Not -Throw + } + finally { + # Restore original confirmation preference + $DebugPreference = $originalDebugPreference + } + } + } +} \ No newline at end of file diff --git a/test/EntraBeta/Users/Get-EntraBetaUserRole.Tests.ps1 b/test/EntraBeta/Users/Get-EntraBetaUserRole.Tests.ps1 new file mode 100644 index 0000000000..be6c6afb23 --- /dev/null +++ b/test/EntraBeta/Users/Get-EntraBetaUserRole.Tests.ps1 @@ -0,0 +1,79 @@ +# ------------------------------------------------------------------------------ +# Copyright (c) Microsoft Corporation. All Rights Reserved. +# Licensed under the MIT License. See License in the project root for license information. +# ------------------------------------------------------------------------------ + +BeforeAll { + if ((Get-Module -Name Microsoft.Entra.Beta.Users) -eq $null) { + Import-Module Microsoft.Entra.Beta.Users + } + Import-Module (Join-Path $PSScriptRoot "..\..\Common-Functions.ps1") -Force + + $scriptblock = { + return @( + [PSCustomObject]@{ + "DisplayName" = "Helpdesk Administrator" + "Id" = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb" + "Description" = "Can reset passwords for non-administrators and Helpdesk Administrators." + "Members" = "null" + "DeletedDateTime" = "10/28/2024 4:16:02 PM" + "RoleTemplateId" = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb" + } + ) + } + + Mock -CommandName Get-MgBetaUserMemberOfAsDirectoryRole -MockWith $scriptblock -ModuleName Microsoft.Entra.Beta.Users +} + +Describe "Get-EntraBetaUserRole" { + Context "Test for Get-EntraBetaUserRole" { + It "Should return all user roles" { + $result = Get-EntraBetaUserRole -UserId 'SawyerM@contoso.com' + $result | Should -Not -BeNullOrEmpty + Should -Invoke -CommandName Get-MgBetaUserMemberOfAsDirectoryRole -ModuleName Microsoft.Entra.Beta.Users -Times 1 + } + + It "Should return top user role" { + $result = Get-EntraBetaUserRole -UserId 'SawyerM@contoso.com' -Top 1 + $result | Should -Not -BeNullOrEmpty + Should -Invoke -CommandName Get-MgBetaUserMemberOfAsDirectoryRole -ModuleName Microsoft.Entra.Beta.Users -Times 1 + } + + It "Property parameter should work" { + $result = Get-EntraBetaUserRole -UserId 'SawyerM@contoso.com' -Property "DisplayName" + $result | Should -Not -BeNullOrEmpty + $result.DisplayName | Should -Be "Helpdesk Administrator" + Should -Invoke -CommandName Get-MgBetaUserMemberOfAsDirectoryRole -ModuleName Microsoft.Entra.Beta.Users -Times 1 + } + + It "Should fail when Property is empty" { + { Get-EntraBetaUserRole -UserId 'SawyerM@contoso.com' -Property } | Should -Throw "Missing an argument for parameter 'Property'*" + } + + It "Should contain 'User-Agent' header" { + $userAgentHeaderValue = "PowerShell/$psVersion EntraPowershell/$entraVersion Get-EntraBetaUserRole" + $result = Get-EntraBetaUserRole -UserId 'SawyerM@contoso.com' + $result | Should -Not -BeNullOrEmpty + $userAgentHeaderValue = "PowerShell/$psVersion EntraPowershell/$entraVersion Get-EntraBetaUserRole" + Should -Invoke -CommandName Get-MgBetaUserMemberOfAsDirectoryRole -ModuleName Microsoft.Entra.Beta.Users -Times 1 -ParameterFilter { + $Headers.'User-Agent' | Should -Be $userAgentHeaderValue + $true + } + } + + It "Should execute successfully without throwing an error" { + # Disable confirmation prompts + $originalDebugPreference = $DebugPreference + $DebugPreference = 'Continue' + + try { + # Act & Assert: Ensure the function doesn't throw an exception + { Get-EntraBetaUserRole -UserId 'SawyerM@contoso.com' -Debug } | Should -Not -Throw + } + finally { + # Restore original confirmation preference + $DebugPreference = $originalDebugPreference + } + } + } +} \ No newline at end of file