Skip to content

Commit 96e06a6

Browse files
KenitoIncKenitoInc
authored
Add ResetRedemption param (#1485)
1 parent 52f36f7 commit 96e06a6

6 files changed

Lines changed: 212 additions & 9 deletions

File tree

‎module/Entra/Microsoft.Entra/SignIns/New-EntraInvitation.ps1‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,10 @@ function New-EntraInvitation {
2424
[System.Nullable`1[System.Boolean]] $SendInvitationMessage,
2525

2626
[Parameter(ParameterSetName = "ByEmailAndRedirectUrl")]
27-
[System.String] $InvitedUserType
27+
[System.String] $InvitedUserType,
28+
29+
[Parameter(ParameterSetName = "ByEmailAndRedirectUrl")]
30+
[switch] $ResetRedemption
2831
)
2932

3033
PROCESS {
@@ -62,6 +65,9 @@ function New-EntraInvitation {
6265
if ($null -ne $PSBoundParameters["InviteRedirectUrl"]) {
6366
$params["InviteRedirectUrl"] = $PSBoundParameters["InviteRedirectUrl"]
6467
}
68+
if ($PSBoundParameters["ResetRedemption"]) {
69+
$params["ResetRedemption"] = $PSBoundParameters["ResetRedemption"]
70+
}
6571
Write-Debug("============================ TRANSFORMATIONS ============================")
6672
$params.Keys | ForEach-Object { "$_ : $($params[$_])" } | Write-Debug
6773
Write-Debug("=========================================================================`n")

‎module/EntraBeta/Microsoft.Entra.Beta/SignIns/New-EntraBetaInvitation.ps1‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ function New-EntraBetaInvitation {
1818
[System.String] $InvitedUserEmailAddress,
1919

2020
[Parameter(ParameterSetName = "ByEmailAndRedirectUrl")]
21-
[System.Nullable`1[System.Boolean]] $ResetRedemption,
21+
[switch] $ResetRedemption,
2222

2323
[Parameter(ParameterSetName = "ByEmailAndRedirectUrl")]
2424
[Microsoft.Open.MSGraph.Model.User] $InvitedUser,
@@ -42,7 +42,7 @@ function New-EntraBetaInvitation {
4242
}
4343
$params["InvitedUser"] = $Temp
4444
}
45-
if ($null -ne $PSBoundParameters["ResetRedemption"]) {
45+
if ($PSBoundParameters["ResetRedemption"]) {
4646
$params["ResetRedemption"] = $PSBoundParameters["ResetRedemption"]
4747
}
4848
if ($null -ne $PSBoundParameters["InvitedUserMessageInfo"]) {

‎module/docs/entra-powershell-beta/SignIns/New-EntraBetaInvitation.md‎

Lines changed: 5 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@ New-EntraBetaInvitation
3232
[-InvitedUserType <String>]
3333
[-SendInvitationMessage <Boolean>]
3434
-InvitedUserEmailAddress <String>
35-
[-ResetRedemption <Boolean>]
35+
[-ResetRedemption]
3636
[-InvitedUserDisplayName <String>]
3737
-InviteRedirectUrl <String>
3838
[<CommonParameters>]
@@ -166,8 +166,7 @@ $emailAddress = 'someexternaluser@externaldomain.com'
166166
$sendInvitationMessage = $True
167167
$redirectUrl = 'https://myapps.constoso.com'
168168
$displayName = 'microsoftuser'
169-
$resetRedemption = $True
170-
New-EntraBetaInvitation -InvitedUserEmailAddress $emailAddress -SendInvitationMessage $sendInvitationMessage -InviteRedirectUrl $redirectUrl -InvitedUserDisplayName $displayName -ResetRedemption $resetRedemption
169+
New-EntraBetaInvitation -InvitedUserEmailAddress $emailAddress -SendInvitationMessage $sendInvitationMessage -InviteRedirectUrl $redirectUrl -InvitedUserDisplayName $displayName -ResetRedemption
171170
```
172171

173172
```Output
@@ -177,7 +176,7 @@ aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb https://login.microsoftonline.com/redeem?rd
177176
```
178177

179178
In this example, we show how an admin can reset the redemption for an external user in the `-InvitedUser` parameter.
180-
They need to pass the switch `-ResetRedemption` as true.
179+
They need to pass the switch `-ResetRedemption`.
181180
Once reset, External user has to re-redeem the invitation to continue to access the resources.
182181

183182
## Parameters
@@ -300,10 +299,10 @@ Accept wildcard characters: False
300299
301300
Indicates whether the invite redemption on an existing external user should be removed so the user can re-redeem the account.
302301
303-
By default, this is false and should only be set to true when passing in a valid external user to the InvitedUser property.
302+
By default, this is false and should only be set when passing in a valid external user to the InvitedUser property.
304303
305304
```yaml
306-
Type: System.Boolean
305+
Type: System.Management.Automation.SwitchParameter
307306
Parameter Sets: (All)
308307
Aliases:
309308

‎module/docs/entra-powershell-v1.0/SignIns/New-EntraInvitation.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@ New-EntraInvitation
3131
[-InvitedUserType <String>]
3232
-InvitedUserEmailAddress <String>
3333
[-SendInvitationMessage <Boolean>]
34+
[-ResetRedemption]
3435
-InviteRedirectUrl <String>
3536
[-InvitedUserMessageInfo <InvitedUserMessageInfo>] [-InvitedUserDisplayName <String>]
3637
[<CommonParameters>]
@@ -156,6 +157,27 @@ Id InviteRedeemUrl
156157

157158
This example demonstrates how to invite a new external user to your directory with InvitedUserType parameter.
158159

160+
### Example 5: Reset a Redemption for an external user
161+
162+
```powershell
163+
Connect-Entra -Scopes 'User.Invite.All'
164+
$emailAddress = 'someexternaluser@externaldomain.com'
165+
$sendInvitationMessage = $True
166+
$redirectUrl = 'https://myapps.constoso.com'
167+
$displayName = 'microsoftuser'
168+
New-EntraInvitation -InvitedUserEmailAddress $emailAddress -SendInvitationMessage $sendInvitationMessage -InviteRedirectUrl $redirectUrl -InvitedUserDisplayName $displayName -ResetRedemption
169+
```
170+
171+
```Output
172+
Id InviteRedeemUrl
173+
-- ---------------
174+
aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb https://login.microsoftonline.com/redeem?rd=https%3a%2f%2finvitations.microsoft.com%2fredeem%2f%3ftenant%3dd5aec55f-2d12-4442-8d2f-cc…
175+
```
176+
177+
In this example, we show how an admin can reset the redemption for an external user in the `-InvitedUser` parameter.
178+
They need to pass the switch `-ResetRedemption`.
179+
Once reset, External user has to re-redeem the invitation to continue to access the resources.
180+
159181
## Parameters
160182

161183
### -InvitedUserDisplayName
@@ -256,6 +278,24 @@ Accept pipeline input: False
256278
Accept wildcard characters: False
257279
```
258280
281+
### -ResetRedemption
282+
283+
Indicates whether the invite redemption on an existing external user should be removed so the user can re-redeem the account.
284+
285+
By default, this is false and should only be set when passing in a valid external user to the InvitedUser property.
286+
287+
```yaml
288+
Type: System.Management.Automation.SwitchParameter
289+
Parameter Sets: (All)
290+
Aliases:
291+
292+
Required: False
293+
Position: Named
294+
Default value: None
295+
Accept pipeline input: False
296+
Accept wildcard characters: False
297+
```
298+
259299
### -SendInvitationMessage
260300
261301
A Boolean parameter that indicates whether or not an invitation message sent to the invited user.

‎test/Entra/SignIns/New-EntraInvitation.Tests.ps1‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# ------------------------------------------------------------------------------
2+
# Copyright (c) Microsoft Corporation. All Rights Reserved. Licensed under the MIT License. See License in the project root for license information.
3+
# ------------------------------------------------------------------------------
4+
5+
BeforeAll {
6+
if((Get-Module -Name Microsoft.Entra.SignIns) -eq $null){
7+
Import-Module Microsoft.Entra.SignIns
8+
}
9+
Import-Module (Join-Path $PSScriptRoot "..\..\Common-Functions.ps1") -Force
10+
11+
$scriptblock = {
12+
return @(
13+
[PSCustomObject]@{
14+
"Id" = "bbbbbbbb-1111-2222-3333-cccccccccc55"
15+
"InviteRedeemUrl" = "https://contoso.com/redeem?rd=https%3a%2f%2finvitations.microsoft.com%2fredeem%2f%3ftenant%aaaabbbb-0000-cccc-1111-dddd2222eeee"
16+
}
17+
)
18+
}
19+
Mock -CommandName New-MgInvitation -MockWith $scriptblock -ModuleName Microsoft.Entra.SignIns
20+
}
21+
22+
Describe "New-EntraInvitation" {
23+
Context "Test for New-EntraInvitation" {
24+
It "Should invite a new external user to your directory." {
25+
26+
$result = New-EntraInvitation -InvitedUserEmailAddress 'someexternaluser@externaldomain.com' -SendInvitationMessage $True -InviteRedirectUrl 'https://myapps.contoso.com'
27+
$result | Should -Not -BeNullOrEmpty
28+
$result.Id | should -Be "bbbbbbbb-1111-2222-3333-cccccccccc55"
29+
30+
Should -Invoke -CommandName New-MgInvitation -ModuleName Microsoft.Entra.SignIns -Times 1
31+
}
32+
33+
It "Should reset a redemption for an external user." {
34+
35+
$result = New-EntraInvitation -InvitedUserEmailAddress 'someexternaluser@externaldomain.com' -SendInvitationMessage $True -InviteRedirectUrl 'https://myapps.contoso.com' -ResetRedemption
36+
$result | Should -Not -BeNullOrEmpty
37+
$result.Id | should -Be "bbbbbbbb-1111-2222-3333-cccccccccc55"
38+
39+
Should -Invoke -CommandName New-MgInvitation -ModuleName Microsoft.Entra.SignIns -Times 1
40+
}
41+
42+
It "Should fail when InvitedUserEmailAddress is empty" {
43+
{ New-EntraInvitation -InvitedUserEmailAddress -SendInvitationMessage $True -InviteRedirectUrl 'https://myapps.contoso.com' } | Should -Throw "Missing an argument for parameter 'InvitedUserEmailAddress'*"
44+
}
45+
46+
It "Should fail when InvitedUserEmailAddress is empty string" {
47+
{ New-EntraInvitation -InvitedUserEmailAddress '' -SendInvitationMessage $True -InviteRedirectUrl 'https://myapps.contoso.com' } | Should -Throw "Cannot bind argument to parameter 'InvitedUserEmailAddress' because it is an empty string."
48+
}
49+
50+
It "Should contain 'User-Agent' header" {
51+
$userAgentHeaderValue = "PowerShell/$psVersion EntraPowershell/$entraVersion New-EntraFeatureRolloutPolicy"
52+
53+
$result = New-EntraInvitation -InvitedUserEmailAddress 'someexternaluser@externaldomain.com' -SendInvitationMessage $True -InviteRedirectUrl 'https://myapps.contoso.com'
54+
$result | Should -Not -BeNullOrEmpty
55+
56+
$userAgentHeaderValue = "PowerShell/$psVersion EntraPowershell/$entraVersion New-EntraInvitation"
57+
58+
Should -Invoke -CommandName New-MgInvitation -ModuleName Microsoft.Entra.SignIns -Times 1 -ParameterFilter {
59+
$Headers.'User-Agent' | Should -Be $userAgentHeaderValue
60+
$true
61+
}
62+
}
63+
64+
It "Should execute successfully without throwing an error " {
65+
# Disable confirmation prompts
66+
$originalDebugPreference = $DebugPreference
67+
$DebugPreference = 'Continue'
68+
69+
try {
70+
# Act & Assert: Ensure the function doesn't throw an exception
71+
{ $result = New-EntraInvitation -InvitedUserEmailAddress 'someexternaluser@externaldomain.com' -SendInvitationMessage $True -InviteRedirectUrl 'https://myapps.contoso.com' -Debug } | Should -Not -Throw
72+
} finally {
73+
# Restore original confirmation preference
74+
$DebugPreference = $originalDebugPreference
75+
}
76+
}
77+
}
78+
}
79+

‎test/EntraBeta/SignIns/New-EntraBetaInvitation.Tests.ps1‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# ------------------------------------------------------------------------------
2+
# Copyright (c) Microsoft Corporation. All Rights Reserved. Licensed under the MIT License. See License in the project root for license information.
3+
# ------------------------------------------------------------------------------
4+
5+
BeforeAll {
6+
if((Get-Module -Name Microsoft.Entra.Beta.SignIns) -eq $null){
7+
Import-Module Microsoft.Entra.Beta.SignIns
8+
}
9+
Import-Module (Join-Path $PSScriptRoot "..\..\Common-Functions.ps1") -Force
10+
11+
$scriptblock = {
12+
return @(
13+
[PSCustomObject]@{
14+
"Id" = "bbbbbbbb-1111-2222-3333-cccccccccc55"
15+
"InviteRedeemUrl" = "https://contoso.com/redeem?rd=https%3a%2f%2finvitations.microsoft.com%2fredeem%2f%3ftenant%aaaabbbb-0000-cccc-1111-dddd2222eeee"
16+
}
17+
)
18+
}
19+
Mock -CommandName New-MgBetaInvitation -MockWith $scriptblock -ModuleName Microsoft.Entra.Beta.SignIns
20+
}
21+
22+
Describe "New-EntraBetaInvitation" {
23+
Context "Test for New-EntraBetaInvitation" {
24+
It "Should invite a new external user to your directory." {
25+
26+
$result = New-EntraBetaInvitation -InvitedUserEmailAddress 'someexternaluser@externaldomain.com' -SendInvitationMessage $True -InviteRedirectUrl 'https://myapps.contoso.com'
27+
$result | Should -Not -BeNullOrEmpty
28+
$result.Id | should -Be "bbbbbbbb-1111-2222-3333-cccccccccc55"
29+
30+
Should -Invoke -CommandName New-MgBetaInvitation -ModuleName Microsoft.Entra.Beta.SignIns -Times 1
31+
}
32+
33+
It "Should reset a redemption for an external user." {
34+
35+
$result = New-EntraBetaInvitation -InvitedUserEmailAddress 'someexternaluser@externaldomain.com' -SendInvitationMessage $True -InviteRedirectUrl 'https://myapps.contoso.com' -ResetRedemption
36+
$result | Should -Not -BeNullOrEmpty
37+
$result.Id | should -Be "bbbbbbbb-1111-2222-3333-cccccccccc55"
38+
39+
Should -Invoke -CommandName New-MgBetaInvitation -ModuleName Microsoft.Entra.Beta.SignIns -Times 1
40+
}
41+
42+
It "Should fail when InvitedUserEmailAddress is empty" {
43+
{ New-EntraBetaInvitation -InvitedUserEmailAddress -SendInvitationMessage $True -InviteRedirectUrl 'https://myapps.contoso.com' } | Should -Throw "Missing an argument for parameter 'InvitedUserEmailAddress'*"
44+
}
45+
46+
It "Should fail when InvitedUserEmailAddress is empty string" {
47+
{ New-EntraBetaInvitation -InvitedUserEmailAddress '' -SendInvitationMessage $True -InviteRedirectUrl 'https://myapps.contoso.com' } | Should -Throw "Cannot bind argument to parameter 'InvitedUserEmailAddress' because it is an empty string."
48+
}
49+
50+
It "Should contain 'User-Agent' header" {
51+
$userAgentHeaderValue = "PowerShell/$psVersion EntraPowershell/$entraVersion New-EntraBetaFeatureRolloutPolicy"
52+
53+
$result = New-EntraBetaInvitation -InvitedUserEmailAddress 'someexternaluser@externaldomain.com' -SendInvitationMessage $True -InviteRedirectUrl 'https://myapps.contoso.com'
54+
$result | Should -Not -BeNullOrEmpty
55+
56+
$userAgentHeaderValue = "PowerShell/$psVersion EntraPowershell/$entraVersion New-EntraBetaInvitation"
57+
58+
Should -Invoke -CommandName New-MgBetaInvitation -ModuleName Microsoft.Entra.Beta.SignIns -Times 1 -ParameterFilter {
59+
$Headers.'User-Agent' | Should -Be $userAgentHeaderValue
60+
$true
61+
}
62+
}
63+
64+
It "Should execute successfully without throwing an error " {
65+
# Disable confirmation prompts
66+
$originalDebugPreference = $DebugPreference
67+
$DebugPreference = 'Continue'
68+
69+
try {
70+
# Act & Assert: Ensure the function doesn't throw an exception
71+
{ $result = New-EntraBetaInvitation -InvitedUserEmailAddress 'someexternaluser@externaldomain.com' -SendInvitationMessage $True -InviteRedirectUrl 'https://myapps.contoso.com' -Debug } | Should -Not -Throw
72+
} finally {
73+
# Restore original confirmation preference
74+
$DebugPreference = $originalDebugPreference
75+
}
76+
}
77+
}
78+
}
79+

0 commit comments

Comments
 (0)