From 2c31e34253796767db9132ac97502caa86c7dfcc Mon Sep 17 00:00:00 2001 From: Pim Simons <32359437+pim-simons@users.noreply.github.com> Date: Thu, 18 Aug 2022 09:04:19 +0200 Subject: [PATCH] feat: Add Remove-AzApiManagementUser script (#321) * added Remove-AzApiManagementUser script * fix create user docs * added docs for Remove-AzApiManagementUser * renamed scripts to prevent issues Co-authored-by: Pim Simons --- .../powershell/azure-api-management.md | 49 +++++-- .../Arcus.Scripting.ApiManagement.psd1 | Bin 8586 -> 8686 bytes .../Arcus.Scripting.ApiManagement.psm1 | 47 ++++++- .../Arcus.Scripting.ApiManagement.pssproj | 3 +- ... => Create-AzApiManagementUserAccount.ps1} | 0 .../Remove-AzApiManagementUserAccount.ps1 | 40 ++++++ .../Arcus.Scripting.ApiManagement.tests.ps1 | 131 ++++++++++++++++-- 7 files changed, 243 insertions(+), 27 deletions(-) rename src/Arcus.Scripting.ApiManagement/Scripts/{Create-AzApiManagementUser.ps1 => Create-AzApiManagementUserAccount.ps1} (100%) create mode 100644 src/Arcus.Scripting.ApiManagement/Scripts/Remove-AzApiManagementUserAccount.ps1 diff --git a/docs/preview/02-Features/powershell/azure-api-management.md b/docs/preview/02-Features/powershell/azure-api-management.md index 77f2e590..73a6e144 100644 --- a/docs/preview/02-Features/powershell/azure-api-management.md +++ b/docs/preview/02-Features/powershell/azure-api-management.md @@ -89,7 +89,7 @@ PS> Create-AzApiManagementApiOperation -ResourceGroupName $ResourceGroup -Servic ## Creating a new user in an Azure API Management service -Signup or invite a new user in an existing API in Azure API Management. +Signup or invite a new user in an existing Azure API Management instance. | Parameter | Mandatory | Description | | ------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -109,55 +109,78 @@ Signup or invite a new user in an existing API in Azure API Management. **Example** -Invite a new user in an existing API in Azure API Management. +Invite a new user in an existing Azure API Management instance. ```powershell -PS> Create-AzApiManagementUser -ResourceGroupName $ResourceGroup -ServiceName $ServiceName -FirstName $FirstName -LastName $LastName -MailAddress $MailAddress +PS> Create-AzApiManagementUserAccount -ResourceGroupName $ResourceGroup -ServiceName $ServiceName -FirstName $FirstName -LastName $LastName -MailAddress $MailAddress # Attempting to invite $FirstName $LastName ($MailAddress) # Invitation has been sent to FirstName $LastName ($MailAddress) ``` -Invite a new user in an existing API in Azure API Management and specify a UserId. +Invite a new user in an existing Azure API Management instance and specify a UserId. ```powershell -PS> Create-AzApiManagementUser -ResourceGroupName $ResourceGroup -ServiceName $ServiceName -FirstName $FirstName -LastName $LastName -MailAddress $MailAddress -UserId $UserId +PS> Create-AzApiManagementUserAccount -ResourceGroupName $ResourceGroup -ServiceName $ServiceName -FirstName $FirstName -LastName $LastName -MailAddress $MailAddress -UserId $UserId # Attempting to invite $FirstName $LastName ($MailAddress) # Invitation has been sent to FirstName $LastName ($MailAddress) ``` -Invite a new user in an existing API in Azure API Management and include a note. +Invite a new user in an existing Azure API Management instance and include a note. ```powershell -PS> Create-AzApiManagementUser -ResourceGroupName $ResourceGroup -ServiceName $ServiceName -FirstName $FirstName -LastName $LastName -MailAddress $MailAddress -Note $Note +PS> Create-AzApiManagementUserAccount -ResourceGroupName $ResourceGroup -ServiceName $ServiceName -FirstName $FirstName -LastName $LastName -MailAddress $MailAddress -Note $Note # Attempting to invite $FirstName $LastName ($MailAddress) # Invitation has been sent to FirstName $LastName ($MailAddress) ``` -Invite a new user in an existing API in Azure API Management and send a notification. +Invite a new user in an existing Azure API Management instance and send a notification. ```powershell -PS> Create-AzApiManagementUser -ResourceGroupName $ResourceGroup -ServiceName $ServiceName -FirstName $FirstName -LastName $LastName -MailAddress $MailAddress -SendNotification +PS> Create-AzApiManagementUserAccount -ResourceGroupName $ResourceGroup -ServiceName $ServiceName -FirstName $FirstName -LastName $LastName -MailAddress $MailAddress -SendNotification # Attempting to invite $FirstName $LastName ($MailAddress) # Invitation has been sent to FirstName $LastName ($MailAddress) ``` -Signup a new user in an existing API in Azure API Management. +Signup a new user in an existing Azure API Management instance. ```powershell -PS> Create-AzApiManagementUser -ResourceGroupName $ResourceGroup -ServiceName $ServiceName -FirstName $FirstName -LastName $LastName -MailAddress $MailAddress -ConfirmationType signup +PS> Create-AzApiManagementUserAccount -ResourceGroupName $ResourceGroup -ServiceName $ServiceName -FirstName $FirstName -LastName $LastName -MailAddress $MailAddress -ConfirmationType signup # Attempting to create account for FirstName $LastName ($MailAddress) # Account has been created for FirstName $LastName ($MailAddress) # Since no password was provided, one has been generated. Please advise the user to change this password the first time logging in ``` -Signup a new user in an existing API in Azure API Management and specify a password. +Signup a new user in an existing Azure API Management instance and specify a password. ```powershell -PS> Create-AzApiManagementUser -ResourceGroupName $ResourceGroup -ServiceName $ServiceName -FirstName $FirstName -LastName $LastName -MailAddress $MailAddress -Password $Password -ConfirmationType signup +PS> Create-AzApiManagementUserAccount -ResourceGroupName $ResourceGroup -ServiceName $ServiceName -FirstName $FirstName -LastName $LastName -MailAddress $MailAddress -Password $Password -ConfirmationType signup # Attempting to create account for FirstName $LastName ($MailAddress) # Account has been created for FirstName $LastName ($MailAddress) ``` +## Removing a user from an Azure API Management service + +Remove a user from an existing Azure API Management instance based on e-mail address. + +| Parameter | Mandatory | Description | +| ------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `ResourceGroupName` | yes | The resource group containing the Azure API Management instance | +| `ServiceName` | yes | The name of the Azure API Management instance located in Azure | +| `MailAddress` | yes | The email address of the user that is to be removed | +| `SubscriptionId` | no | The Id of the subscription containing the Azure API Management instance. When not provided, it will be retrieved from the current context (Get-AzContext). | +| `AccessToken` | no | The access token to be used to add the user to the Azure API Management instance. When not provided, it will be retrieved from the current context (Get-AzContext). | + +**Example** + +Remove a user from an existing Azure API Management instance. + +```powershell +PS> Remove-AzApiManagementUserAccount -ResourceGroupName $ResourceGroup -ServiceName $ServiceName -MailAddress $MailAddress +# Retrieving the user account with e-mail '$MailAddress' +# Attempting to remove the user account with e-mail '$MailAddress' and id '1' +# Removed the user account with e-mail '$MailAddress' and id '1' +``` + ## Importing a policy to a product in the Azure API Management instance Imports a policy from a file to a product in Azure API Management. diff --git a/src/Arcus.Scripting.ApiManagement/Arcus.Scripting.ApiManagement.psd1 b/src/Arcus.Scripting.ApiManagement/Arcus.Scripting.ApiManagement.psd1 index 1e7f2a19540f79fd1241abfae8a8686e0f573c27..5cae572ea1e1cc501a67cad00c04ca912838278f 100644 GIT binary patch delta 60 zcmeBje&@WQPk6GPu)yRw!X~_q49P&4&rr&c$51l)zM#EmC_^zrDnk(iip=Ko!n=6^ DBBK!` delta 16 XcmaFo+~vHXPk8bKVW-U|BD;72KClLg diff --git a/src/Arcus.Scripting.ApiManagement/Arcus.Scripting.ApiManagement.psm1 b/src/Arcus.Scripting.ApiManagement/Arcus.Scripting.ApiManagement.psm1 index e6a96273..775bd6dc 100644 --- a/src/Arcus.Scripting.ApiManagement/Arcus.Scripting.ApiManagement.psm1 +++ b/src/Arcus.Scripting.ApiManagement/Arcus.Scripting.ApiManagement.psm1 @@ -111,7 +111,7 @@ Export-ModuleMember -Function Create-AzApiManagementApiOperation Creates a user in Azure API Management. .Description - Signup or invite a new user in an existing API in Azure API Management. + Signup or invite a new user in an existing Azure API Management instance. .Parameter ResourceGroupName The resource group containing the API Management service. @@ -152,7 +152,7 @@ Export-ModuleMember -Function Create-AzApiManagementApiOperation .Parameter AccessToken [Optional] The access token to be used. When not provided, it will be retrieved from the current context (Get-AzContext). #> -function Create-AzApiManagementUser { +function Create-AzApiManagementUserAccount { param( [string][Parameter(Mandatory = $true)] $ResourceGroupName = $(throw "Resource group name is required"), [string][parameter(Mandatory = $true)] $ServiceName = $(throw "API management service name is required"), @@ -169,13 +169,50 @@ function Create-AzApiManagementUser { [string][parameter(Mandatory = $false)] $AccessToken ) if ($SendNotification) { - . $PSScriptRoot\Scripts\Create-AzApiManagementUser.ps1 -ResourceGroupName $ResourceGroupName -ServiceName $ServiceName -FirstName $FirstName -LastName $LastName -MailAddress $MailAddress -UserId $UserId -Password $Password -Note $Note -ConfirmationType $ConfirmationType -ApiVersion $ApiVersion -SubscriptionId $SubscriptionId -AccessToken $AccessToken -SendNotification + . $PSScriptRoot\Scripts\Create-AzApiManagementUserAccount.ps1 -ResourceGroupName $ResourceGroupName -ServiceName $ServiceName -FirstName $FirstName -LastName $LastName -MailAddress $MailAddress -UserId $UserId -Password $Password -Note $Note -ConfirmationType $ConfirmationType -ApiVersion $ApiVersion -SubscriptionId $SubscriptionId -AccessToken $AccessToken -SendNotification } else { - . $PSScriptRoot\Scripts\Create-AzApiManagementUser.ps1 -ResourceGroupName $ResourceGroupName -ServiceName $ServiceName -FirstName $FirstName -LastName $LastName -MailAddress $MailAddress -UserId $UserId -Password $Password -Note $Note -ConfirmationType $ConfirmationType -ApiVersion $ApiVersion -SubscriptionId $SubscriptionId -AccessToken $AccessToken + . $PSScriptRoot\Scripts\Create-AzApiManagementUserAccount.ps1 -ResourceGroupName $ResourceGroupName -ServiceName $ServiceName -FirstName $FirstName -LastName $LastName -MailAddress $MailAddress -UserId $UserId -Password $Password -Note $Note -ConfirmationType $ConfirmationType -ApiVersion $ApiVersion -SubscriptionId $SubscriptionId -AccessToken $AccessToken } } -Export-ModuleMember -Function Create-AzApiManagementUser +Export-ModuleMember -Function Create-AzApiManagementUserAccount + +<# + .Synopsis + Removes a user from Azure API Management. + + .Description + Remove a user from Azure API Management based on e-mail address. + + .Parameter ResourceGroupName + The resource group containing the API Management service. + + .Parameter ServiceName + The name of the API Management service located in Azure. + + .Parameter MailAddress + The e-mail address of the user. + + .Parameter SubscriptionId + [Optional] The Id of the subscription containing the Azure API Management service. When not provided, it will be retrieved from the current context (Get-AzContext). + + .Parameter AccessToken + [Optional] The access token to be used. When not provided, it will be retrieved from the current context (Get-AzContext). +#> +function Remove-AzApiManagementUserAccount { + param( + [string][Parameter(Mandatory = $true)] $ResourceGroupName = $(throw "Resource group name is required"), + [string][parameter(Mandatory = $true)] $ServiceName = $(throw "API management service name is required"), + [string][parameter(Mandatory = $true)] $MailAddress = $(throw "The mail-address of the user is required"), + [string][parameter(Mandatory = $false)] $SubscriptionId, + [string][parameter(Mandatory = $false)] $AccessToken + ) + + . $PSScriptRoot\Scripts\Remove-AzApiManagementUserAccount.ps1 -ResourceGroupName $ResourceGroupName -ServiceName $ServiceName -MailAddress $MailAddress + +} + +Export-ModuleMember -Function Remove-AzApiManagementUserAccount <# .Synopsis diff --git a/src/Arcus.Scripting.ApiManagement/Arcus.Scripting.ApiManagement.pssproj b/src/Arcus.Scripting.ApiManagement/Arcus.Scripting.ApiManagement.pssproj index fe893601..65bbefc6 100644 --- a/src/Arcus.Scripting.ApiManagement/Arcus.Scripting.ApiManagement.pssproj +++ b/src/Arcus.Scripting.ApiManagement/Arcus.Scripting.ApiManagement.pssproj @@ -33,11 +33,12 @@ - + + diff --git a/src/Arcus.Scripting.ApiManagement/Scripts/Create-AzApiManagementUser.ps1 b/src/Arcus.Scripting.ApiManagement/Scripts/Create-AzApiManagementUserAccount.ps1 similarity index 100% rename from src/Arcus.Scripting.ApiManagement/Scripts/Create-AzApiManagementUser.ps1 rename to src/Arcus.Scripting.ApiManagement/Scripts/Create-AzApiManagementUserAccount.ps1 diff --git a/src/Arcus.Scripting.ApiManagement/Scripts/Remove-AzApiManagementUserAccount.ps1 b/src/Arcus.Scripting.ApiManagement/Scripts/Remove-AzApiManagementUserAccount.ps1 new file mode 100644 index 00000000..5eff7102 --- /dev/null +++ b/src/Arcus.Scripting.ApiManagement/Scripts/Remove-AzApiManagementUserAccount.ps1 @@ -0,0 +1,40 @@ +param( + [string][Parameter(Mandatory = $true)] $ResourceGroupName = $(throw "Resource group name is required"), + [string][parameter(Mandatory = $true)] $ServiceName = $(throw "API management service name is required"), + [string][parameter(Mandatory = $true)] $MailAddress = $(throw "The mail-address of the user is required"), + [string][parameter(Mandatory = $false)] $SubscriptionId, + [string][parameter(Mandatory = $false)] $AccessToken +) + +$apim = Get-AzApiManagement -ResourceGroupName $ResourceGroupName -Name $ServiceName +if ($apim -eq $null) { + throw "Unable to find the Azure API Management Instance $ServiceName in resource group $ResourceGroupName" +} +$apimContext = New-AzApiManagementContext -ResourceGroupName $ResourceGroupName -ServiceName $ServiceName + +if ($SubscriptionId -eq "" -or $AccessToken -eq "") { + # Request accessToken in case the script contains no records + $token = Get-AzCachedAccessToken + + $AccessToken = $token.AccessToken + $SubscriptionId = $token.SubscriptionId +} + +try { + Write-Host "Retrieving the user account with e-mail '$mailAddress'" + $apimUser = Get-AzApiManagementUser -Context $apimContext -Email $MailAddress + + if ($apimUser -ne $null) { + $apimUserId = $apimUser.UserId + + Write-Host "Attempting to remove the user account with e-mail '$mailAddress' and id '$apimUserId'" + Remove-AzApiManagementUser -Context $apimContext -UserId $apimUserId + Write-Host "Removed the user account with e-mail '$mailAddress' and id '$apimUserId'" + } else { + Write-Host "User account with e-mail '$mailAddress' not found in the APIM instance '$ServiceName'" + } +} +catch { + Write-Host $_ + throw "Failed to remove the user account for '$MailAddress' in the APIM instance '$ServiceName'" +} \ No newline at end of file diff --git a/src/Arcus.Scripting.Tests.Unit/Arcus.Scripting.ApiManagement.tests.ps1 b/src/Arcus.Scripting.Tests.Unit/Arcus.Scripting.ApiManagement.tests.ps1 index 0e64b6b2..5fdc60d3 100644 --- a/src/Arcus.Scripting.Tests.Unit/Arcus.Scripting.ApiManagement.tests.ps1 +++ b/src/Arcus.Scripting.Tests.Unit/Arcus.Scripting.ApiManagement.tests.ps1 @@ -1139,7 +1139,7 @@ InModuleScope Arcus.Scripting.ApiManagement { } # Act - Create-AzApiManagementUser ` + Create-AzApiManagementUserAccount ` -ResourceGroupName $resourceGroup ` -ServiceName $serviceName ` -FirstName $firstName ` @@ -1185,7 +1185,7 @@ InModuleScope Arcus.Scripting.ApiManagement { } # Act - Create-AzApiManagementUser ` + Create-AzApiManagementUserAccount ` -ResourceGroupName $resourceGroup ` -ServiceName $serviceName ` -FirstName $firstName ` @@ -1233,7 +1233,7 @@ InModuleScope Arcus.Scripting.ApiManagement { } # Act - Create-AzApiManagementUser ` + Create-AzApiManagementUserAccount ` -ResourceGroupName $resourceGroup ` -ServiceName $serviceName ` -FirstName $firstName ` @@ -1282,7 +1282,7 @@ InModuleScope Arcus.Scripting.ApiManagement { } # Act - Create-AzApiManagementUser ` + Create-AzApiManagementUserAccount ` -ResourceGroupName $resourceGroup ` -ServiceName $serviceName ` -FirstName $firstName ` @@ -1331,7 +1331,7 @@ InModuleScope Arcus.Scripting.ApiManagement { } # Act - Create-AzApiManagementUser ` + Create-AzApiManagementUserAccount ` -ResourceGroupName $resourceGroup ` -ServiceName $serviceName ` -FirstName $firstName ` @@ -1380,7 +1380,7 @@ InModuleScope Arcus.Scripting.ApiManagement { } # Act - Create-AzApiManagementUser ` + Create-AzApiManagementUserAccount ` -ResourceGroupName $resourceGroup ` -ServiceName $serviceName ` -FirstName $firstName ` @@ -1410,7 +1410,7 @@ InModuleScope Arcus.Scripting.ApiManagement { # Act { - Create-AzApiManagementUser ` + Create-AzApiManagementUserAccount ` -ResourceGroupName $resourceGroup ` -ServiceName $serviceName ` -FirstName $firstName ` @@ -1438,7 +1438,7 @@ InModuleScope Arcus.Scripting.ApiManagement { # Act { - Create-AzApiManagementUser ` + Create-AzApiManagementUserAccount ` -ResourceGroupName $resourceGroup ` -ServiceName $serviceName ` -FirstName $firstName ` @@ -1447,6 +1447,121 @@ InModuleScope Arcus.Scripting.ApiManagement { } | Should -Throw -ExpectedMessage "Unable to find the Azure API Management Instance $serviceName in resource group $resourceGroup" + # Assert + Assert-VerifiableMock + Assert-MockCalled Get-AzApiManagement -Times 1 + } + } + Context "Remove Azure API Management User" { + It "Removing a user from Azure API Management is OK" { + # Arrange + $resourceGroup = "contoso" + $serviceName = "contosoApi" + $mailAddress = "john.doe@contoso.com" + $context = New-Object -TypeName Microsoft.Azure.Commands.ApiManagement.ServiceManagement.Models.PsApiManagementContext + $stubApiManagement = New-Object -TypeName Microsoft.Azure.Commands.ApiManagement.Models.PsApiManagement + $userId = 1 + $apiUser = [pscustomobject] @{ + UserId = $userId; + }; + + Mock Get-AzApiManagement { + $ResourceGroupName | Should -Be $resourceGroup + $Name | Should -Be $serviceName + return $stubApiManagement } -Verifiable + Mock New-AzApiManagementContext { + $ResourceGroupName | Should -Be $resourceGroup + $ServiceName | Should -Be $serviceName + return $context } -Verifiable + Mock Get-AzCachedAccessToken -MockWith { + return @{ + SubscriptionId = "123456" + AccessToken = "accessToken" + } + } + Mock Get-AzApiManagementUser { + $Context | Should -Be $context + $Email | Should -Be $mailAddress + return $apiUser } -Verifiable + Mock Remove-AzApiManagementUser { + $Context | Should -Be $context + $UserId | Should -Be $userId + return $null } -Verifiable + + # Act + Remove-AzApiManagementUserAccount ` + -ResourceGroupName $resourceGroup ` + -ServiceName $serviceName ` + -MailAddress $mailAddress + + # Assert + Assert-VerifiableMock + Assert-MockCalled Get-AzApiManagement -Times 1 + Assert-MockCalled New-AzApiManagementContext -Times 1 + Assert-MockCalled Get-AzCachedAccessToken -Times 1 + Assert-MockCalled Get-AzApiManagementUser -Times 1 + Assert-MockCalled Remove-AzApiManagementUser -Times 1 + } + It "Removing a user from Azure API Management that does not exist is OK" { + # Arrange + $resourceGroup = "contoso" + $serviceName = "contosoApi" + $mailAddress = "john.doe@contoso.com" + $context = New-Object -TypeName Microsoft.Azure.Commands.ApiManagement.ServiceManagement.Models.PsApiManagementContext + $stubApiManagement = New-Object -TypeName Microsoft.Azure.Commands.ApiManagement.Models.PsApiManagement + + Mock Get-AzApiManagement { + $ResourceGroupName | Should -Be $resourceGroup + $Name | Should -Be $serviceName + return $stubApiManagement } -Verifiable + Mock New-AzApiManagementContext { + $ResourceGroupName | Should -Be $resourceGroup + $ServiceName | Should -Be $serviceName + return $context } -Verifiable + Mock Get-AzCachedAccessToken -MockWith { + return @{ + SubscriptionId = "123456" + AccessToken = "accessToken" + } + } + Mock Get-AzApiManagementUser { + $Context | Should -Be $context + $Email | Should -Be $mailAddress + return $null } -Verifiable + + # Act + Remove-AzApiManagementUserAccount ` + -ResourceGroupName $resourceGroup ` + -ServiceName $serviceName ` + -MailAddress $mailAddress + + # Assert + Assert-VerifiableMock + Assert-MockCalled Get-AzApiManagement -Times 1 + Assert-MockCalled New-AzApiManagementContext -Times 1 + Assert-MockCalled Get-AzCachedAccessToken -Times 1 + Assert-MockCalled Get-AzApiManagementUser -Times 1 + } + It "Removing a user from a non-existing Azure API Management fails" { + # Arrange + $resourceGroup = "contoso" + $serviceName = "contosoApi" + $mailAddress = "john.doe@contoso.com" + + Mock Get-AzApiManagement { + $ResourceGroupName | Should -Be $resourceGroup + $Name | Should -Be $serviceName + return $null } -Verifiable + + # Act + { + Remove-AzApiManagementUserAccount ` + -ResourceGroupName $resourceGroup ` + -ServiceName $serviceName ` + -MailAddress $mailAddress + } | Should -Throw -ExpectedMessage "Unable to find the Azure API Management Instance $serviceName in resource group $resourceGroup" + + # Assert Assert-VerifiableMock Assert-MockCalled Get-AzApiManagement -Times 1