Skip to content

Commit 8d9d6fd

Browse files
pim-simonspim-simons
authored
feat: Add Create-AzApiManagementUser script (#316)
Co-authored-by: Pim Simons <pim.simons@codit.eu>
1 parent 34d33fd commit 8d9d6fd

6 files changed

Lines changed: 571 additions & 0 deletions

File tree

‎docs/preview/02-Features/powershell/azure-api-management.md‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ This module provides the following capabilities:
1010
- [Installation](#installation)
1111
- [Backing up an API Management service](#backing-up-an-api-management-service)
1212
- [Creating a new API operation in the Azure API Management instance](#creating-a-new-api-operation-in-the-azure-api-management-instance)
13+
- [Creating a new user in an Azure API Management service](#creating-a-new-user-in-an-azure-api-management-service)
1314
- [Importing a policy to an API in the Azure API Management instance](#importing-a-policy-to-an-api-in-the-azure-api-management-instance)
1415
- [Importing a policy to an operation in the Azure API Management instance](#importing-a-policy-to-an-operation-in-the-azure-api-management-instance)
1516
- [Removing all Azure API Management defaults from the instance](#removing-all-azure-api-management-defaults-from-the-instance)
@@ -86,6 +87,77 @@ PS> Create-AzApiManagementApiOperation -ResourceGroupName $ResourceGroup -Servic
8687
# New API operation '$OperationName' on API Management instance was added.
8788
```
8889

90+
## Creating a new user in an Azure API Management service
91+
92+
Signup or invite a new user in an existing API in Azure API Management.
93+
94+
| Parameter | Mandatory | Description |
95+
| ------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
96+
| `ResourceGroupName` | yes | The resource group containing the Azure API Management instance |
97+
| `ServiceName` | yes | The name of the Azure API Management instance located in Azure |
98+
| `FirstName` | yes | The first name of the user that is to be created |
99+
| `LastName` | yes | The last name of the user that is to be created |
100+
| `MailAddress` | yes | The email address of the user that is to be created |
101+
| `UserId` | no | The UserId that will be used to create the user |
102+
| `Password` | no | The password that the user will be able to login with |
103+
| `Note` | no | A note that will be added to the user |
104+
| `SendNotification` | no | Wether or not a notification will be sent to the email address of the user |
105+
| `ConfirmationType` | no | The confirmation type that will be used when creating the user, this can be `invite` (default) or `signup` |
106+
| `ApiVersion` | no | The version of the management API to be used. (default: `2021-08-01`) |
107+
| `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). |
108+
| `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). |
109+
110+
**Example**
111+
112+
Invite a new user in an existing API in Azure API Management.
113+
114+
```powershell
115+
PS> Create-AzApiManagementUser -ResourceGroupName $ResourceGroup -ServiceName $ServiceName -FirstName $FirstName -LastName $LastName -MailAddress $MailAddress
116+
# Attempting to invite $FirstName $LastName ($MailAddress)
117+
# Invitation has been sent to FirstName $LastName ($MailAddress)
118+
```
119+
120+
Invite a new user in an existing API in Azure API Management and specify a UserId.
121+
122+
```powershell
123+
PS> Create-AzApiManagementUser -ResourceGroupName $ResourceGroup -ServiceName $ServiceName -FirstName $FirstName -LastName $LastName -MailAddress $MailAddress -UserId $UserId
124+
# Attempting to invite $FirstName $LastName ($MailAddress)
125+
# Invitation has been sent to FirstName $LastName ($MailAddress)
126+
```
127+
128+
Invite a new user in an existing API in Azure API Management and include a note.
129+
130+
```powershell
131+
PS> Create-AzApiManagementUser -ResourceGroupName $ResourceGroup -ServiceName $ServiceName -FirstName $FirstName -LastName $LastName -MailAddress $MailAddress -Note $Note
132+
# Attempting to invite $FirstName $LastName ($MailAddress)
133+
# Invitation has been sent to FirstName $LastName ($MailAddress)
134+
```
135+
136+
Invite a new user in an existing API in Azure API Management and send a notification.
137+
138+
```powershell
139+
PS> Create-AzApiManagementUser -ResourceGroupName $ResourceGroup -ServiceName $ServiceName -FirstName $FirstName -LastName $LastName -MailAddress $MailAddress -SendNotification
140+
# Attempting to invite $FirstName $LastName ($MailAddress)
141+
# Invitation has been sent to FirstName $LastName ($MailAddress)
142+
```
143+
144+
Signup a new user in an existing API in Azure API Management.
145+
146+
```powershell
147+
PS> Create-AzApiManagementUser -ResourceGroupName $ResourceGroup -ServiceName $ServiceName -FirstName $FirstName -LastName $LastName -MailAddress $MailAddress -ConfirmationType signup
148+
# Attempting to create account for FirstName $LastName ($MailAddress)
149+
# Account has been created for FirstName $LastName ($MailAddress)
150+
# Since no password was provided, one has been generated. Please advise the user to change this password the first time logging in
151+
```
152+
153+
Signup a new user in an existing API in Azure API Management and specify a password.
154+
155+
```powershell
156+
PS> Create-AzApiManagementUser -ResourceGroupName $ResourceGroup -ServiceName $ServiceName -FirstName $FirstName -LastName $LastName -MailAddress $MailAddress -Password $Password -ConfirmationType signup
157+
# Attempting to create account for FirstName $LastName ($MailAddress)
158+
# Account has been created for FirstName $LastName ($MailAddress)
159+
```
160+
89161
## Importing a policy to a product in the Azure API Management instance
90162

91163
Imports a policy from a file to a product in Azure API Management.

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

68 Bytes
Binary file not shown.

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

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -106,6 +106,77 @@ function Create-AzApiManagementApiOperation {
106106

107107
Export-ModuleMember -Function Create-AzApiManagementApiOperation
108108

109+
<#
110+
.Synopsis
111+
Creates a user in Azure API Management.
112+
113+
.Description
114+
Signup or invite a new user in an existing API in Azure API Management.
115+
116+
.Parameter ResourceGroupName
117+
The resource group containing the API Management service.
118+
119+
.Parameter ServiceName
120+
The name of the API Management service located in Azure.
121+
122+
.Parameter FirstName
123+
The first name of the user.
124+
125+
.Parameter LastName
126+
The last name of the user.
127+
128+
.Parameter MailAddress
129+
The e-mail address of the user.
130+
131+
.Parameter UserId
132+
[Optional] The UserId the user should get in API Management.
133+
134+
.Parameter Password
135+
[Optional] The password for the user.
136+
137+
.Parameter Note
138+
[Optional] The note that should be added to the user in API Management.
139+
140+
.Parameter SendNotification
141+
[Optional] Whether or not to send a notification to the user.
142+
143+
.Parameter ConfirmationType
144+
[Optional] The confirmation type to use when creating the user, this can be set to 'invite' or 'signup'.
145+
146+
.Parameter ApiVersion
147+
[Optional] The version of the api to be used.
148+
149+
.Parameter SubscriptionId
150+
[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).
151+
152+
.Parameter AccessToken
153+
[Optional] The access token to be used. When not provided, it will be retrieved from the current context (Get-AzContext).
154+
#>
155+
function Create-AzApiManagementUser {
156+
param(
157+
[string][Parameter(Mandatory = $true)] $ResourceGroupName = $(throw "Resource group name is required"),
158+
[string][parameter(Mandatory = $true)] $ServiceName = $(throw "API management service name is required"),
159+
[string][parameter(Mandatory = $true)] $FirstName = $(throw "The first name of the user is required"),
160+
[string][parameter(Mandatory = $true)] $LastName = $(throw "The last name of the user is required"),
161+
[string][parameter(Mandatory = $true)] $MailAddress = $(throw "The mail-address of the user is required"),
162+
[string][parameter(Mandatory = $false)] $UserId = $($MailAddress -replace '\W', '-'),
163+
[string][parameter(Mandatory = $false)] $Password,
164+
[string][parameter(Mandatory = $false)] $Note,
165+
[switch][parameter(Mandatory = $false)] $SendNotification = $false,
166+
[string][parameter(Mandatory = $false)][ValidateSet('invite', 'signup')] $ConfirmationType = "invite",
167+
[string][parameter(Mandatory = $false)] $ApiVersion = "2021-08-01",
168+
[string][parameter(Mandatory = $false)] $SubscriptionId,
169+
[string][parameter(Mandatory = $false)] $AccessToken
170+
)
171+
if ($SendNotification) {
172+
. $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
173+
} else {
174+
. $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
175+
}
176+
}
177+
178+
Export-ModuleMember -Function Create-AzApiManagementUser
179+
109180
<#
110181
.Synopsis
111182
Import a policy to a product in Azure API Management.

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@
3333
<Compile Include="Arcus.Scripting.ApiManagement.psm1" />
3434
<Compile Include="Scripts\Backup-AzApiManagementService.ps1" />
3535
<Compile Include="Scripts\Create-AzApiManagementApiOperation.ps1" />
36+
<Compile Include="Scripts\Create-AzApiManagementUser.ps1" />
3637
<Compile Include="Scripts\Import-AzApiManagementProductPolicy.ps1" />
3738
<Compile Include="Scripts\Remove-AzApiManagementDefaults.ps1" />
3839
<Compile Include="Scripts\Import-AzApiManagementApiPolicy.ps1" />

‎src/Arcus.Scripting.ApiManagement/Scripts/Create-AzApiManagementUser.ps1‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
param(
2+
[string][Parameter(Mandatory = $true)] $ResourceGroupName = $(throw "Resource group name is required"),
3+
[string][parameter(Mandatory = $true)] $ServiceName = $(throw "API management service name is required"),
4+
[string][parameter(Mandatory = $true)] $FirstName = $(throw "The first name of the user is required"),
5+
[string][parameter(Mandatory = $true)] $LastName = $(throw "The last name of the user is required"),
6+
[string][parameter(Mandatory = $true)] $MailAddress = $(throw "The mail-address of the user is required"),
7+
[string][parameter(Mandatory = $false)] $UserId = $($MailAddress -replace '\W', '-'),
8+
[string][parameter(Mandatory = $false)] $Password,
9+
[string][parameter(Mandatory = $false)] $Note,
10+
[switch][parameter(Mandatory = $false)] $SendNotification = $false,
11+
[string][parameter(Mandatory = $false)][ValidateSet('invite', 'signup')] $ConfirmationType = "invite",
12+
[string][parameter(Mandatory = $false)] $ApiVersion = "2021-08-01",
13+
[string][parameter(Mandatory = $false)] $SubscriptionId,
14+
[string][parameter(Mandatory = $false)] $AccessToken
15+
)
16+
17+
$apimContext = Get-AzApiManagement -ResourceGroupName $ResourceGroupName -Name $ServiceName
18+
if ($apimContext -eq $null) {
19+
throw "Unable to find the Azure API Management Instance $ServiceName in resource group $ResourceGroupName"
20+
}
21+
22+
if ($SubscriptionId -eq "" -or $AccessToken -eq "") {
23+
# Request accessToken in case the script contains no records
24+
$token = Get-AzCachedAccessToken
25+
26+
$AccessToken = $token.AccessToken
27+
$SubscriptionId = $token.SubscriptionId
28+
}
29+
30+
$apimMgmtEndpoint = "https://management.azure.com/subscriptions/$SubscriptionId/resourceGroups/$ResourceGroupName/providers/Microsoft.ApiManagement/service/$ServiceName/users/$($UserId)?notify=$SendNotification&api-version=$ApiVersion"
31+
$fullUrl = $apimMgmtEndpoint.Replace('{subscriptionId}', $SubscriptionId)
32+
33+
try
34+
{
35+
if($ConfirmationType -eq 'invite')
36+
{
37+
Write-Host "Attempting to invite $FirstName $LastName ($mailAddress)"
38+
}
39+
else
40+
{
41+
Write-Host "Attempting to create account for $FirstName $LastName ($mailAddress)"
42+
}
43+
44+
$jsonRequest = ConvertTo-Json -Depth 3 @{
45+
'properties' = @{
46+
'firstName' = $FirstName
47+
'lastName' = $LastName
48+
'email' = $MailAddress
49+
'confirmation' = $ConfirmationType
50+
'password' = $Password
51+
'note' = $Note
52+
}
53+
}
54+
55+
$params = @{
56+
Method = 'Put'
57+
Headers = @{
58+
'authorization'="Bearer $AccessToken"
59+
}
60+
URI = $fullUrl
61+
Body = $jsonRequest
62+
}
63+
64+
$web = Invoke-WebRequest @params -ErrorAction Stop
65+
66+
Write-Verbose $web
67+
68+
if($ConfirmationType -eq 'invite')
69+
{
70+
Write-Host "Invitation has been sent to $FirstName $LastName ($mailAddress)"
71+
}
72+
else
73+
{
74+
Write-Host "Account has been created for $FirstName $LastName ($mailAddress)"
75+
if($Password -eq $null -or $Password -eq ""){
76+
Write-Host "Since no password was provided, one has been generated. Please advise the user to change this password the first time logging in"
77+
}
78+
}
79+
80+
return $UserId
81+
}
82+
catch {
83+
Write-Host $_
84+
throw "Failed to create an account for $FirstName $LastName ($MailAddress) in the APIM instance $ServiceName"
85+
}

0 commit comments

Comments
 (0)