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 <pim.simons@codit.eu>

Author: pim-simons

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.

src/Arcus.Scripting.ApiManagement/Arcus.Scripting.ApiManagement.psd1

@@ -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

src/Arcus.Scripting.ApiManagement/Arcus.Scripting.ApiManagement.psm1

@@ -33,11 +33,12 @@
     <Compile Include="Arcus.Scripting.ApiManagement.psm1" />
     <Compile Include="Scripts\Backup-AzApiManagementService.ps1" />
     <Compile Include="Scripts\Create-AzApiManagementApiOperation.ps1" />
-    <Compile Include="Scripts\Create-AzApiManagementUser.ps1" />
+    <Compile Include="Scripts\Create-AzApiManagementUserAccount.ps1" />
     <Compile Include="Scripts\Import-AzApiManagementProductPolicy.ps1" />
     <Compile Include="Scripts\Remove-AzApiManagementDefaults.ps1" />
     <Compile Include="Scripts\Import-AzApiManagementApiPolicy.ps1" />
     <Compile Include="Scripts\Import-AzApiManagementOperationPolicy.ps1" />
+    <Compile Include="Scripts\Remove-AzApiManagementUserAccount.ps1" />
     <Compile Include="Scripts\Restore-AzApiManagementService.ps1" />
     <Compile Include="Scripts\Set-AzApiManagementApiSubscriptionKey.ps1" />
     <Compile Include="Scripts\Upload-AzApiManagementCertificate.ps1" />

src/Arcus.Scripting.ApiManagement/Arcus.Scripting.ApiManagement.pssproj

@@ -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'"
+}