diff --git a/module/Entra/AdditionalFunctions/Get-EntraDeletedUser.ps1 b/module/Entra/AdditionalFunctions/Get-EntraDeletedUser.ps1 new file mode 100644 index 000000000..f3f24e474 --- /dev/null +++ b/module/Entra/AdditionalFunctions/Get-EntraDeletedUser.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-EntraDeletedUser { + [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 deleted users.")] + [switch] $All, + + [Parameter(ParameterSetName = "GetVague", ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, HelpMessage = "Search string to use for vague queries.")] + [System.String] $SearchString, + + [Alias('Id')] + [Parameter(ParameterSetName = "GetById", Mandatory = $true, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, HelpMessage = "ID of the user to retrieve.")] + [System.String] $UserId, + + [Alias('Limit')] + [Parameter(ParameterSetName = "GetQuery", 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["PipelineVariable"]) { + $params["PipelineVariable"] = $PSBoundParameters["PipelineVariable"] + } + if ($null -ne $PSBoundParameters["ProgressAction"]) { + $params["ProgressAction"] = $PSBoundParameters["ProgressAction"] + } + if ($PSBoundParameters.ContainsKey("Debug")) { + $params["Debug"] = $PSBoundParameters["Debug"] + } + if ($null -ne $PSBoundParameters["WarningAction"]) { + $params["WarningAction"] = $PSBoundParameters["WarningAction"] + } + if ($null -ne $PSBoundParameters["ErrorVariable"]) { + $params["ErrorVariable"] = $PSBoundParameters["ErrorVariable"] + } + if ($null -ne $PSBoundParameters["Filter"]) { + $TmpValue = $PSBoundParameters["Filter"] + foreach ($i in $keysChanged.GetEnumerator()) { + $TmpValue = $TmpValue.Replace($i.Key, $i.Value) + } + $Value = $TmpValue + $params["Filter"] = $Value + } + if ($PSBoundParameters.ContainsKey("Verbose")) { + $params["Verbose"] = $PSBoundParameters["Verbose"] + } + if ($null -ne $PSBoundParameters["ErrorAction"]) { + $params["ErrorAction"] = $PSBoundParameters["ErrorAction"] + } + if ($null -ne $PSBoundParameters["InformationAction"]) { + $params["InformationAction"] = $PSBoundParameters["InformationAction"] + } + if ($null -ne $PSBoundParameters["All"]) { + if ($PSBoundParameters["All"]) { + $params["All"] = $PSBoundParameters["All"] + } + } + if ($null -ne $PSBoundParameters["WarningVariable"]) { + $params["WarningVariable"] = $PSBoundParameters["WarningVariable"] + } + if ($null -ne $PSBoundParameters["InformationVariable"]) { + $params["InformationVariable"] = $PSBoundParameters["InformationVariable"] + } + if ($null -ne $PSBoundParameters["SearchString"]) { + $TmpValue = $PSBoundParameters["SearchString"] + $Value = "mailNickName eq '$TmpValue' or (mail eq '$TmpValue' or (displayName eq '$TmpValue' or startswith(displayName,'$TmpValue')))" + $params["Filter"] = $Value + } + if ($null -ne $PSBoundParameters["UserId"]) { + $params["DirectoryObjectId"] = $PSBoundParameters["UserId"] + } + if ($null -ne $PSBoundParameters["OutBuffer"]) { + $params["OutBuffer"] = $PSBoundParameters["OutBuffer"] + } + if ($null -ne $PSBoundParameters["OutVariable"]) { + $params["OutVariable"] = $PSBoundParameters["OutVariable"] + } + if ($PSBoundParameters.ContainsKey("Top")) { + $params["Top"] = $PSBoundParameters["Top"] + } + if ($null -ne $PSBoundParameters["Property"]) { + $params["Property"] = $PSBoundParameters["Property"] + } + + Write-Debug("============================ TRANSFORMATIONS ============================") + $params.Keys | ForEach-Object { "$_ : $($params[$_])" } | Write-Debug + Write-Debug("=========================================================================`n") + + # Make the API call + try { + # Make the API call with -PageSize 999 if -All is used + if ($PSBoundParameters.ContainsKey("All") -and $All) { + $response = Get-MgDirectoryDeletedItemAsUser @params -PageSize 999 -Headers $customHeaders + } + else { + $response = Get-MgDirectoryDeletedItemAsUser @params -Headers $customHeaders + } + + return $response + } + catch { + # Handle any errors that occur during the API call + Write-Error "An error occurred while retrieving deleted users: $_" + } + } +} \ No newline at end of file diff --git a/module/EntraBeta/AdditionalFunctions/Get-EntraBetaDeletedUser.ps1 b/module/EntraBeta/AdditionalFunctions/Get-EntraBetaDeletedUser.ps1 new file mode 100644 index 000000000..b6ab0ffb3 --- /dev/null +++ b/module/EntraBeta/AdditionalFunctions/Get-EntraBetaDeletedUser.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-EntraBetaDeletedUser { + [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 deleted users.")] + [switch] $All, + + [Parameter(ParameterSetName = "GetVague", ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, HelpMessage = "Search string to use for vague queries.")] + [System.String] $SearchString, + + [Alias('Id')] + [Parameter(ParameterSetName = "GetById", Mandatory = $true, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, HelpMessage = "ID of the user to retrieve.")] + [System.String] $UserId, + + [Alias('Limit')] + [Parameter(ParameterSetName = "GetQuery", 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["PipelineVariable"]) { + $params["PipelineVariable"] = $PSBoundParameters["PipelineVariable"] + } + if ($null -ne $PSBoundParameters["ProgressAction"]) { + $params["ProgressAction"] = $PSBoundParameters["ProgressAction"] + } + if ($PSBoundParameters.ContainsKey("Debug")) { + $params["Debug"] = $PSBoundParameters["Debug"] + } + if ($null -ne $PSBoundParameters["WarningAction"]) { + $params["WarningAction"] = $PSBoundParameters["WarningAction"] + } + if ($null -ne $PSBoundParameters["ErrorVariable"]) { + $params["ErrorVariable"] = $PSBoundParameters["ErrorVariable"] + } + if ($null -ne $PSBoundParameters["Filter"]) { + $TmpValue = $PSBoundParameters["Filter"] + foreach ($i in $keysChanged.GetEnumerator()) { + $TmpValue = $TmpValue.Replace($i.Key, $i.Value) + } + $Value = $TmpValue + $params["Filter"] = $Value + } + if ($PSBoundParameters.ContainsKey("Verbose")) { + $params["Verbose"] = $PSBoundParameters["Verbose"] + } + if ($null -ne $PSBoundParameters["ErrorAction"]) { + $params["ErrorAction"] = $PSBoundParameters["ErrorAction"] + } + if ($null -ne $PSBoundParameters["InformationAction"]) { + $params["InformationAction"] = $PSBoundParameters["InformationAction"] + } + if ($null -ne $PSBoundParameters["All"]) { + if ($PSBoundParameters["All"]) { + $params["All"] = $PSBoundParameters["All"] + } + } + if ($null -ne $PSBoundParameters["WarningVariable"]) { + $params["WarningVariable"] = $PSBoundParameters["WarningVariable"] + } + if ($null -ne $PSBoundParameters["InformationVariable"]) { + $params["InformationVariable"] = $PSBoundParameters["InformationVariable"] + } + if ($null -ne $PSBoundParameters["SearchString"]) { + $TmpValue = $PSBoundParameters["SearchString"] + $Value = "mailNickName eq '$TmpValue' or (mail eq '$TmpValue' or (displayName eq '$TmpValue' or startswith(displayName,'$TmpValue')))" + $params["Filter"] = $Value + } + if ($null -ne $PSBoundParameters["UserId"]) { + $params["DirectoryObjectId"] = $PSBoundParameters["UserId"] + } + if ($null -ne $PSBoundParameters["OutBuffer"]) { + $params["OutBuffer"] = $PSBoundParameters["OutBuffer"] + } + if ($null -ne $PSBoundParameters["OutVariable"]) { + $params["OutVariable"] = $PSBoundParameters["OutVariable"] + } + if ($PSBoundParameters.ContainsKey("Top")) { + $params["Top"] = $PSBoundParameters["Top"] + } + if ($null -ne $PSBoundParameters["Property"]) { + $params["Property"] = $PSBoundParameters["Property"] + } + + Write-Debug("============================ TRANSFORMATIONS ============================") + $params.Keys | ForEach-Object { "$_ : $($params[$_])" } | Write-Debug + Write-Debug("=========================================================================`n") + + # Make the API call + try { + # Make the API call with -PageSize 999 if -All is used + if ($PSBoundParameters.ContainsKey("All") -and $All) { + $response = Get-MgBetaDirectoryDeletedItemAsUser @params -PageSize 999 -Headers $customHeaders + } + else { + $response = Get-MgBetaDirectoryDeletedItemAsUser @params -Headers $customHeaders + } + + return $response + } + catch { + # Handle any errors that occur during the API call + Write-Error "An error occurred while retrieving deleted users: $_" + } + } +} \ No newline at end of file diff --git a/module/docs/entra-powershell-beta/Microsoft.Graph.Entra.Beta/Get-EntraBetaDeletedUser.md b/module/docs/entra-powershell-beta/Microsoft.Graph.Entra.Beta/Get-EntraBetaDeletedUser.md new file mode 100644 index 000000000..0ea61bb94 --- /dev/null +++ b/module/docs/entra-powershell-beta/Microsoft.Graph.Entra.Beta/Get-EntraBetaDeletedUser.md @@ -0,0 +1,286 @@ +--- +title: Get-EntraBetaDeletedUser +description: This article provides details on the Get-EntraBetaDeletedUser command. + + +ms.topic: reference +ms.date: 11/11/2024 +ms.author: eunicewaweru +ms.reviewer: stevemutungi +manager: CelesteDG + +external help file: Microsoft.Graph.Entra.Beta-Help.xml +Module Name: Microsoft.Graph.Entra.Beta +online version: https://learn.microsoft.com/powershell/module/Microsoft.Graph.Entra.Beta/Get-EntraBetaDeletedUser + +schema: 2.0.0 +--- + +# Get-EntraBetaDeletedUser + +## Synopsis + +Retrieves soft-deleted (recently deleted) users in Microsoft Entra ID. + +## Syntax + +### GetQuery (Default) + +```powershell +Get-EntraBetaDeletedUser + [-Top ] + [-All] + [-Filter ] + [-Property ] + [] +``` + +### GetByValue + +```powershell +Get-EntraBetaDeletedUser + [-SearchString ] + [-All] + [-Property ] + [] +``` + +### GetById + +```powershell +Get-EntraBetaDeletedUser + -UserId + [-All] + [-Property ] + [] +``` + +### GetVague + +```powershell +Get-EntraBetaDeletedUser + [-All] + [-SearchString ] + [-Property ] + [] +``` + +## Description + +The `Get-EntraBetaDeletedUser` cmdlet retrieves soft-deleted (recently deleted) users from the directory. Deleted users can be recovered within 30 days, after which they're permanently deleted. + +## Examples + +### Example 1: Get deleted users in the directory + +```powershell +Connect-Entra -Scopes 'User.Read.All' +Get-EntraBetaDeletedUser +``` + +```Output +Id DisplayName UserPrincipalName UserType DeletedDateTime PermanentDeletionDate +-- ----------- ----------------- -------- --------------------- --------------------- +cccccccc-2222-3333-4444-dddddddddddd Angel Brown cccccccc222233334444ddddddddddddAngelB@contoso.com Member 11/6/2024 9:52:26 AM 12/6/2024 9:52:26 AM +dddddddd-3333-4444-5555-eeeeeeeeeeee Avery Smith dddddddd333344445555eeeeeeeeeeeeAveryS@contoso.com Member 11/13/2024 3:22:47 PM 12/13/2024 3:22:47 PM +eeeeeeee-4444-5555-6666-ffffffffffff Sawyer Miller eeeeeeee444455556666ffffffffffffSawyerM@contoso.com Member 11/13/2024 3:23:14 PM 12/13/2024 3:23:14 PM +``` + +This example shows how to retrieve all recoverable deleted users in the Microsoft Entra ID. + +### Example 2: Get deleted users in the directory using All parameter + +```powershell +Connect-Entra -Scopes 'User.Read.All' +Get-EntraBetaDeletedUser -All +``` + +```Output +Id DisplayName UserPrincipalName UserType DeletedDateTime PermanentDeletionDate +-- ----------- ----------------- -------- --------------------- --------------------- +cccccccc-2222-3333-4444-dddddddddddd Angel Brown cccccccc222233334444ddddddddddddAngelB@contoso.com Member 11/6/2024 9:52:26 AM 12/6/2024 9:52:26 AM +dddddddd-3333-4444-5555-eeeeeeeeeeee Avery Smith dddddddd333344445555eeeeeeeeeeeeAveryS@contoso.com Member 11/13/2024 3:22:47 PM 12/13/2024 3:22:47 PM +eeeeeeee-4444-5555-6666-ffffffffffff Sawyer Miller eeeeeeee444455556666ffffffffffffSawyerM@contoso.com Member 11/13/2024 3:23:14 PM 12/13/2024 3:23:14 PM +``` + +This example shows how to retrieve all recoverable deleted users, using All parameter. + +### Example 3: Get top two deleted users + +```powershell +Connect-Entra -Scopes 'User.Read.All' +Get-EntraBetaDeletedUser -Top 2 #alias: Limit e.g. -Limit 2 +``` + +```Output +Id DisplayName UserPrincipalName UserType DeletedDateTime PermanentDeletionDate +-- ----------- ----------------- -------- --------------------- --------------------- +cccccccc-2222-3333-4444-dddddddddddd Angel Brown cccccccc222233334444ddddddddddddAngelB@contoso.com Member 11/6/2024 9:52:26 AM 12/6/2024 9:52:26 AM +dddddddd-3333-4444-5555-eeeeeeeeeeee Avery Smith dddddddd333344445555eeeeeeeeeeeeAveryS@contoso.com Member 11/13/2024 3:22:47 PM 12/13/2024 3:22:47 PM +``` + +This example shows how to retrieve the top two recoverable deleted users in the directory. You can also use the alias `Limit`. + +### Example 4: Get deleted users containing string 'Avery Smith' + +```powershell +Connect-Entra -Scopes 'User.Read.All' +Get-EntraBetaDeletedUser -SearchString 'Avery Smith' +``` + +```Output +Id DisplayName UserPrincipalName UserType DeletedDateTime PermanentDeletionDate +-- ----------- ----------------- -------- --------------- --------------------- +dddddddd-3333-4444-5555-eeeeeeeeeeee Avery Smith dddddddd333344445555eeeeeeeeeeeeAveryS@contoso.com Member 11/13/2024 3:22:47 PM 12/13/2024 3:22:47 PM +``` + +This example shows how to retrieve deleted users in the directory, containing the specified string. + +### Example 5: Get deleted users filter by display name + +```powershell +Connect-Entra -Scopes 'User.Read.All' +Get-EntraBetaDeletedUser -Filter "displayName eq 'Avery Smith'" +``` + +```Output +Id DisplayName UserPrincipalName UserType DeletedDateTime PermanentDeletionDate +-- ----------- ----------------- -------- --------------- --------------------- +dddddddd-3333-4444-5555-eeeeeeeeeeee Avery Smith dddddddd333344445555eeeeeeeeeeeeAveryS@contoso.com Member 11/13/2024 3:22:47 PM 12/13/2024 3:22:47 PM +``` + +This example shows how to retrieve deleted users in the directory, having the specified display name. + +### Example 6: Get deleted user by UserId + +```powershell +Connect-Entra -Scopes 'User.Read.All' +Get-EntraBetaDeletedUser -UserId 'dddddddd-3333-4444-5555-eeeeeeeeeeee' +``` + +```Output +Id DisplayName UserPrincipalName UserType DeletedDateTime PermanentDeletionDate +-- ----------- ----------------- -------- --------------- --------------------- +dddddddd-3333-4444-5555-eeeeeeeeeeee Avery Smith dddddddd333344445555eeeeeeeeeeeeAveryS@contoso.com Member 11/13/2024 3:22:47 PM 12/13/2024 3:22:47 PM +``` + +This example shows how to retrieve the deleted user specified by UserId. + +- `-UserId` parameter specifies the deleted user UserId. + +## 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 +``` + +### -Filter + +Specifies an OData v4.0 filter statement. +This parameter controls which objects are returned. + +```yaml +Type: System.String +Parameter Sets: GetQuery +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName, ByValue) +Accept wildcard characters: False +``` + +### -UserId + +The ObjectId or User Principal Name of the deleted user to be retrieved. + +```yaml +Type: System.String +Parameter Sets: GetById +Aliases: Id + +Required: True +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName, ByValue) +Accept wildcard characters: False +``` + +### -SearchString + +Specifies a search string. + +```yaml +Type: System.String +Parameter Sets: GetVague +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName, ByValue) +Accept wildcard characters: False +``` + +### -Top + +Specifies the maximum number of records to return. + +```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 +``` + +### 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 + +### System.String + +System.Nullable\`1\[\[System.Boolean, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089\]\] System.Nullable\`1\[\[System.Int32, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089\]\] + +## Outputs + +### System.Object + +## Notes + +## Related Links diff --git a/module/docs/entra-powershell-v1.0/Microsoft.Graph.Entra/Get-EntraDeletedUser.md b/module/docs/entra-powershell-v1.0/Microsoft.Graph.Entra/Get-EntraDeletedUser.md new file mode 100644 index 000000000..0ff9541fe --- /dev/null +++ b/module/docs/entra-powershell-v1.0/Microsoft.Graph.Entra/Get-EntraDeletedUser.md @@ -0,0 +1,288 @@ +--- +title: Get-EntraDeletedUser +description: This article provides details on the Get-EntraDeletedUser command. + + +ms.topic: reference +ms.date: 11/11/2024 +ms.author: eunicewaweru +ms.reviewer: stevemutungi +manager: CelesteDG + +external help file: Microsoft.Graph.Entra-Help.xml +Module Name: Microsoft.Graph.Entra +online version: https://learn.microsoft.com/powershell/module/Microsoft.Graph.Entra/Get-EntraDeletedUser + +schema: 2.0.0 +--- + +# Get-EntraDeletedUser + +## Synopsis + +Retrieves soft-deleted (recently deleted) users in Microsoft Entra ID. + +## Syntax + +### GetQuery (Default) + +```powershell +Get-EntraDeletedUser + [-Top ] + [-All] + [-Filter ] + [-Property ] + [] +``` + +### GetByValue + +```powershell +Get-EntraDeletedUser + [-SearchString ] + [-All] + [-Property ] + [] +``` + +### GetById + +```powershell +Get-EntraDeletedUser + -UserId + [-All] + [-Property ] + [] +``` + +### GetVague + +```powershell +Get-EntraDeletedUser + [-All] + [-SearchString ] + [-Property ] + [] +``` + +## Description + +The `Get-EntraDeletedUser` cmdlet retrieves soft-deleted (recently deleted) users from the directory. Deleted users can be recovered within 30 days, after which they're permanently deleted. + +## Examples + +### Example 1: Get deleted users in the directory + +```powershell +Connect-Entra -Scopes 'User.Read.All' +Get-EntraDeletedUser +``` + +```Output +Id DisplayName UserPrincipalName UserType DeletedDateTime PermanentDeletionDate +-- ----------- ----------------- -------- --------------- --------------------- +cccccccc-2222-3333-4444-dddddddddddd Angel Brown cccccccc222233334444ddddddddddddAngelB@contoso.com +dddddddd-3333-4444-5555-eeeeeeeeeeee Avery Smith dddddddd333344445555eeeeeeeeeeeeAveryS@contoso.com +eeeeeeee-4444-5555-6666-ffffffffffff Sawyer Miller eeeeeeee444455556666ffffffffffffSawyerM@contoso.com +aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb Alain Davignon aaaaaaaa000011112222bbbbbbbbbbbbAlainD@contoso.com +``` + +This example shows how to retrieve all recoverable deleted users in the Microsoft Entra ID. + +### Example 2: Get deleted users in the directory using All parameter + +```powershell +Connect-Entra -Scopes 'User.Read.All' +Get-EntraDeletedUser -All +``` + +```Output +Id DisplayName UserPrincipalName UserType DeletedDateTime PermanentDeletionDate +-- ----------- ----------------- -------- --------------- --------------------- +cccccccc-2222-3333-4444-dddddddddddd Angel Brown cccccccc222233334444ddddddddddddAngelB@contoso.com +dddddddd-3333-4444-5555-eeeeeeeeeeee Avery Smith dddddddd333344445555eeeeeeeeeeeeAveryS@contoso.com +eeeeeeee-4444-5555-6666-ffffffffffff Sawyer Miller eeeeeeee444455556666ffffffffffffSawyerM@contoso.com +aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb Alain Davignon aaaaaaaa000011112222bbbbbbbbbbbbAlainD@contoso.com +``` + +This example shows how to retrieve all recoverable deleted users, using All parameter. + +### Example 3: Get top two deleted users + +```powershell +Connect-Entra -Scopes 'User.Read.All' +Get-EntraDeletedUser -Top 2 #alias: Limit e.g. -Limit 2 +``` + +```Output +Id DisplayName UserPrincipalName UserType DeletedDateTime PermanentDeletionDate +-- ----------- ----------------- -------- --------------- --------------------- +cccccccc-2222-3333-4444-dddddddddddd Angel Brown cccccccc222233334444ddddddddddddAngelB@contoso.com +dddddddd-3333-4444-5555-eeeeeeeeeeee Avery Smith dddddddd333344445555eeeeeeeeeeeeAveryS@contoso.com +``` + +This example shows how to retrieve the top two recoverable deleted users in the directory. You can also use the alias `Limit`. + +### Example 4: Get deleted users containing string 'Avery Smith' + +```powershell +Connect-Entra -Scopes 'User.Read.All' +Get-EntraDeletedUser -SearchString 'Avery Smith' +``` + +```Output +Id DisplayName UserPrincipalName UserType DeletedDateTime PermanentDeletionDate +-- ----------- ----------------- -------- --------------- --------------------- +dddddddd-3333-4444-5555-eeeeeeeeeeee Avery Smith dddddddd333344445555eeeeeeeeeeeeAveryS@contoso.com +``` + +This example shows how to retrieve deleted users in the directory, containing the specified string. + +### Example 5: Get deleted users filter by display name + +```powershell +Connect-Entra -Scopes 'User.Read.All' +Get-EntraDeletedUser -Filter "displayName eq 'Avery Smith'" +``` + +```Output +Id DisplayName UserPrincipalName UserType DeletedDateTime PermanentDeletionDate +-- ----------- ----------------- -------- --------------- --------------------- +dddddddd-3333-4444-5555-eeeeeeeeeeee Avery Smith dddddddd333344445555eeeeeeeeeeeeAveryS@contoso.com +``` + +This example shows how to retrieve deleted users in the directory, having the specified display name. + +### Example 6: Get deleted user by UserId + +```powershell +Connect-Entra -Scopes 'User.Read.All' +Get-EntraDeletedUser -UserId 'dddddddd-3333-4444-5555-eeeeeeeeeeee' +``` + +```Output +Id DisplayName UserPrincipalName UserType DeletedDateTime PermanentDeletionDate +-- ----------- ----------------- -------- --------------- --------------------- +dddddddd-3333-4444-5555-eeeeeeeeeeee Avery Smith dddddddd333344445555eeeeeeeeeeeeAveryS@contoso.com +``` + +This example shows how to retrieve the deleted user specified by UserId. + +- `-UserId` parameter specifies the deleted user UserId. + +## 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 +``` + +### -Filter + +Specifies an OData v4.0 filter statement. +This parameter controls which objects are returned. + +```yaml +Type: System.String +Parameter Sets: GetQuery +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName, ByValue) +Accept wildcard characters: False +``` + +### -UserId + +The ObjectId or User Principal Name of the deleted user to be retrieved. + +```yaml +Type: System.String +Parameter Sets: GetById +Aliases: Id + +Required: True +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName, ByValue) +Accept wildcard characters: False +``` + +### -SearchString + +Specifies a search string. + +```yaml +Type: System.String +Parameter Sets: GetVague +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName, ByValue) +Accept wildcard characters: False +``` + +### -Top + +Specifies the maximum number of records to return. + +```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 +``` + +### 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 + +### System.String + +System.Nullable\`1\[\[System.Boolean, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089\]\] System.Nullable\`1\[\[System.Int32, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089\]\] + +## Outputs + +### System.Object + +## Notes + +## Related Links diff --git a/test/module/Entra/Get-EntraDeletedUser.Tests.ps1 b/test/module/Entra/Get-EntraDeletedUser.Tests.ps1 new file mode 100644 index 000000000..e67fdfd6e --- /dev/null +++ b/test/module/Entra/Get-EntraDeletedUser.Tests.ps1 @@ -0,0 +1,118 @@ +# ------------------------------------------------------------------------------ +# 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.Graph.Entra) -eq $null) { + Import-Module Microsoft.Graph.Entra + } + Import-Module (Join-Path $psscriptroot "..\Common-Functions.ps1") -Force + + $scriptblock = { + return @( + [PSCustomObject]@{ + "Id" = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb" + "DeletedDateTime" = "10-05-2024 04:27:17" + "CreatedDateTime" = "07-07-2023 14:31:41" + "DisplayName" = "Raul Razo" + } + ) + } + + Mock -CommandName Get-MgDirectoryDeletedItemAsUser -MockWith $scriptblock -ModuleName Microsoft.Graph.Entra +} + +Describe "Get-EntraDeletedUser" { + Context "Test for Get-EntraDeletedUser" { + It "Should return specific Deleted User" { + $result = Get-EntraDeletedUser -UserId "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb" + $result | Should -Not -BeNullOrEmpty + + Should -Invoke -CommandName Get-MgDirectoryDeletedItemAsUser -ModuleName Microsoft.Graph.Entra -Times 1 + } + It "Should return specific Deleted user with alias" { + $result = Get-EntraDeletedUser -Id "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb" + $result | Should -Not -BeNullOrEmpty + + Should -Invoke -CommandName Get-MgDirectoryDeletedItemAsUser -ModuleName Microsoft.Graph.Entra -Times 1 + } + It "Should fail when UserId is empty" { + { Get-EntraDeletedUser -UserId } | Should -Throw "Missing an argument for parameter 'UserId'*" + } + It "Should fail when UserId is invalid" { + { Get-EntraDeletedUser -UserId "" } | Should -Throw "Cannot bind argument to parameter 'UserId' because it is an empty string." + } + It "Should return All deleted users" { + $result = Get-EntraDeletedUser -All + $result | Should -Not -BeNullOrEmpty + + Should -Invoke -CommandName Get-MgDirectoryDeletedItemAsUser -ModuleName Microsoft.Graph.Entra -Times 1 + } + It "Should fail when All is invalid" { + { Get-EntraDeletedUser -UserId "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb" -All xyz } | Should -Throw "A positional parameter cannot be found that accepts argument 'xyz'.*" + } + It "Should return top 1 deleted user" { + $result = Get-EntraDeletedUser -Top 1 + $result | Should -Not -BeNullOrEmpty + + Should -Invoke -CommandName Get-MgDirectoryDeletedItemAsUser -ModuleName Microsoft.Graph.Entra -Times 1 + } + It "Should fail when Top is empty" { + { Get-EntraDeletedUser -UserId "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb" -Top } | Should -Throw "Missing an argument for parameter 'Top'*" + } + It "Should fail when Top is invalid" { + { Get-EntraDeletedUser -UserId "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb" -Top xyz } | Should -Throw "Cannot process argument transformation on parameter 'Top'*" + } + It "Should return specific deleted user by filter" { + $result = Get-EntraDeletedUser -Filter "DisplayName eq 'Raul Razo'" + $result | Should -Not -BeNullOrEmpty + + Should -Invoke -CommandName Get-MgDirectoryDeletedItemAsUser -ModuleName Microsoft.Graph.Entra -Times 1 + } + It "Should fail when filter is empty" { + { Get-EntraDeletedUser -Filter } | Should -Throw "Missing an argument for parameter 'Filter'*" + } + It "Should return specific deleted users by SearchString" { + $result = Get-EntraDeletedUser -SearchString "Raul Razo" + $result | Should -Not -BeNullOrEmpty + + Should -Invoke -CommandName Get-MgDirectoryDeletedItemAsUser -ModuleName Microsoft.Graph.Entra -Times 1 + } + It "Should fail when searchstring is empty" { + { Get-EntraDeletedUser -SearchString } | Should -Throw "Missing an argument for parameter 'SearchString'*" + } + It "Property parameter should work" { + $result = Get-EntraDeletedUser -UserId "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb" -Property DisplayName + $result | Should -Not -BeNullOrEmpty + + Should -Invoke -CommandName Get-MgDirectoryDeletedItemAsUser -ModuleName Microsoft.Graph.Entra -Times 1 + } + It "Should fail when Property is empty" { + { Get-EntraDeletedUser -UserId "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb" -Property } | Should -Throw "Missing an argument for parameter 'Property'*" + } + + It "Should contain 'User-Agent' header" { + $userAgentHeaderValue = "PowerShell/$psVersion EntraPowershell/$entraVersion Get-EntraDeletedUser" + $result = Get-EntraDeletedUser -UserId "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb" + $result | Should -Not -BeNullOrEmpty + $userAgentHeaderValue = "PowerShell/$psVersion EntraPowershell/$entraVersion Get-EntraDeletedUser" + Should -Invoke -CommandName Get-MgDirectoryDeletedItemAsUser -ModuleName Microsoft.Graph.Entra -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-EntraDeletedUser -UserId "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb" -Debug } | Should -Not -Throw + } + finally { + # Restore original confirmation preference + $DebugPreference = $originalDebugPreference + } + } + } +} \ No newline at end of file diff --git a/test/module/EntraBeta/Get-EntraBetaDeletedUser.Tests.ps1 b/test/module/EntraBeta/Get-EntraBetaDeletedUser.Tests.ps1 new file mode 100644 index 000000000..7aba5ac88 --- /dev/null +++ b/test/module/EntraBeta/Get-EntraBetaDeletedUser.Tests.ps1 @@ -0,0 +1,118 @@ +# ------------------------------------------------------------------------------ +# 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.Graph.Entra.Beta) -eq $null) { + Import-Module Microsoft.Graph.Entra.Beta + } + Import-Module (Join-Path $psscriptroot "..\Common-Functions.ps1") -Force + + $scriptblock = { + return @( + [PSCustomObject]@{ + "Id" = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb" + "DeletedDateTime" = "10-05-2024 04:27:17" + "CreatedDateTime" = "07-07-2023 14:31:41" + "DisplayName" = "Raul Razo" + } + ) + } + + Mock -CommandName Get-MgBetaDirectoryDeletedItemAsUser -MockWith $scriptblock -ModuleName Microsoft.Graph.Entra.Beta +} + +Describe "Get-EntraBetaDeletedUser" { + Context "Test for Get-EntraBetaDeletedUser" { + It "Should return specific Deleted User" { + $result = Get-EntraBetaDeletedUser -UserId "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb" + $result | Should -Not -BeNullOrEmpty + + Should -Invoke -CommandName Get-MgBetaDirectoryDeletedItemAsUser -ModuleName Microsoft.Graph.Entra.Beta -Times 1 + } + It "Should return specific Deleted user with alias" { + $result = Get-EntraBetaDeletedUser -Id "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb" + $result | Should -Not -BeNullOrEmpty + + Should -Invoke -CommandName Get-MgBetaDirectoryDeletedItemAsUser -ModuleName Microsoft.Graph.Entra.Beta -Times 1 + } + It "Should fail when UserId is empty" { + { Get-EntraBetaDeletedUser -UserId } | Should -Throw "Missing an argument for parameter 'UserId'*" + } + It "Should fail when UserId is invalid" { + { Get-EntraBetaDeletedUser -UserId "" } | Should -Throw "Cannot bind argument to parameter 'UserId' because it is an empty string." + } + It "Should return All deleted users" { + $result = Get-EntraBetaDeletedUser -All + $result | Should -Not -BeNullOrEmpty + + Should -Invoke -CommandName Get-MgBetaDirectoryDeletedItemAsUser -ModuleName Microsoft.Graph.Entra.Beta -Times 1 + } + It "Should fail when All is invalid" { + { Get-EntraBetaDeletedUser -UserId "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb" -All xyz } | Should -Throw "A positional parameter cannot be found that accepts argument 'xyz'.*" + } + It "Should return top 1 deleted user" { + $result = Get-EntraBetaDeletedUser -Top 1 + $result | Should -Not -BeNullOrEmpty + + Should -Invoke -CommandName Get-MgBetaDirectoryDeletedItemAsUser -ModuleName Microsoft.Graph.Entra.Beta -Times 1 + } + It "Should fail when Top is empty" { + { Get-EntraBetaDeletedUser -UserId "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb" -Top } | Should -Throw "Missing an argument for parameter 'Top'*" + } + It "Should fail when Top is invalid" { + { Get-EntraBetaDeletedUser -UserId "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb" -Top xyz } | Should -Throw "Cannot process argument transformation on parameter 'Top'*" + } + It "Should return specific deleted user by filter" { + $result = Get-EntraBetaDeletedUser -Filter "DisplayName eq 'Raul Razo'" + $result | Should -Not -BeNullOrEmpty + + Should -Invoke -CommandName Get-MgBetaDirectoryDeletedItemAsUser -ModuleName Microsoft.Graph.Entra.Beta -Times 1 + } + It "Should fail when filter is empty" { + { Get-EntraBetaDeletedUser -Filter } | Should -Throw "Missing an argument for parameter 'Filter'*" + } + It "Should return specific deleted users by SearchString" { + $result = Get-EntraBetaDeletedUser -SearchString "Raul Razo" + $result | Should -Not -BeNullOrEmpty + + Should -Invoke -CommandName Get-MgBetaDirectoryDeletedItemAsUser -ModuleName Microsoft.Graph.Entra.Beta -Times 1 + } + It "Should fail when searchstring is empty" { + { Get-EntraBetaDeletedUser -SearchString } | Should -Throw "Missing an argument for parameter 'SearchString'*" + } + It "Property parameter should work" { + $result = Get-EntraBetaDeletedUser -UserId "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb" -Property DisplayName + $result | Should -Not -BeNullOrEmpty + + Should -Invoke -CommandName Get-MgBetaDirectoryDeletedItemAsUser -ModuleName Microsoft.Graph.Entra.Beta -Times 1 + } + It "Should fail when Property is empty" { + { Get-EntraBetaDeletedUser -UserId "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb" -Property } | Should -Throw "Missing an argument for parameter 'Property'*" + } + + It "Should contain 'User-Agent' header" { + $userAgentHeaderValue = "PowerShell/$psVersion EntraPowershell/$entraVersion Get-EntraBetaDeletedUser" + $result = Get-EntraBetaDeletedUser -UserId "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb" + $result | Should -Not -BeNullOrEmpty + $userAgentHeaderValue = "PowerShell/$psVersion EntraPowershell/$entraVersion Get-EntraBetaDeletedUser" + Should -Invoke -CommandName Get-MgBetaDirectoryDeletedItemAsUser -ModuleName Microsoft.Graph.Entra.Beta -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-EntraBetaDeletedUser -UserId "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb" -Debug } | Should -Not -Throw + } + finally { + # Restore original confirmation preference + $DebugPreference = $originalDebugPreference + } + } + } +} \ No newline at end of file