Skip to content

Commit 2799d18

Browse files
pim-simonsstijnmoreels
pim-simons
and
stijnmoreels
authored
feat: Add script to apply user configuration to Azure API Management (#422)
* basic setup of new script * added extra functionality and unit tests * added docs * Apply suggestions from code review Co-authored-by: Stijn Moreels <9039753+stijnmoreels@users.noreply.github.com> * update docs * chnaged `Azure API Management service` to `Azure API Management instance` * fix try * `api` to `API` * updated logging * fix docs * added assertions * `Write-Host` to `Write-Error` --------- Co-authored-by: Stijn Moreels <9039753+stijnmoreels@users.noreply.github.com>
1 parent 934d4ef commit 2799d18

23 files changed

Lines changed: 972 additions & 98 deletions

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

Lines changed: 217 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -107,7 +107,7 @@ Sign-up or invite a new user in an existing Azure API Management instance.
107107
| `Note` | no | A note that will be added to the user |
108108
| `SendNotification` | no | Wether or not a notification will be sent to the email address of the user |
109109
| `ConfirmationType` | no | The confirmation type that will be used when creating the user, this can be `invite` (default) or `signup` |
110-
| `ApiVersion` | no | The version of the management API to be used. (default: `2021-08-01`) |
110+
| `ApiVersion` | no | The version of the management API to be used. (default: `2021-08-01`) |
111111
| `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). |
112112
| `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). |
113113

@@ -192,6 +192,222 @@ PS> Create-AzApiManagementUserAccount `
192192
# Account has been created for $FirstName $LastName ($mailAddress) for Azure API Management service '$ServiceName' in resource group '$ResourceGroupName'
193193
```
194194

195+
## Applying user configuration to an Azure API Management service from a configuration file
196+
197+
Apply user configuration to an existing Azure API Management instance. You can create or update users and assign groups and/or subscriptions to these users.
198+
199+
| Parameter | Mandatory | Description |
200+
| --------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
201+
| `ResourceGroupName` | yes | The resource group containing the Azure API Management instance |
202+
| `ServiceName` | yes | The name of the Azure API Management instance located in Azure |
203+
| `ConfigurationFile` | yes | Path to the JSON Configuration file containing the user configuration |
204+
| `StrictlyFollowConfigurationFile` | no | The switch to indicate whether the configuration file should strictly be followed, for example remove the user from groups not defined in the configuration file |
205+
| `ApiVersion` | no | The version of the management API to be used. (default: `2021-08-01`) |
206+
| `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). |
207+
| `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). |
208+
209+
**Configuration File**
210+
211+
The configuration file is a simple JSON file that contains the users that need to be created or updated, the JSON file consists of an array of JSON objects.
212+
213+
214+
The file needs to adhere to the following JSON schema.
215+
216+
<details>
217+
218+
<summary>Configuration File</summary>
219+
220+
``` json
221+
{
222+
"$schema": "https://json-schema.org/draft/2020-12/schema",
223+
"$id": "https://scripting.arcus-azure.net/Features/powershell/azure-api-management/config.json",
224+
"type": "array",
225+
"title": "The configuration JSON schema",
226+
"$defs": {},
227+
"prefixItems": [{
228+
"type": "object",
229+
"additionalProperties": false,
230+
"properties": {
231+
"firstName": {
232+
"type": "string"
233+
},
234+
"lastName": {
235+
"type": "string"
236+
},
237+
"userId": {
238+
"type": "string"
239+
},
240+
"mailAddress": {
241+
"type": "string"
242+
},
243+
"sendNotification": {
244+
"type": "boolean"
245+
},
246+
"confirmationType": {
247+
"type": "string",
248+
"enum": ["signup", "invite"]
249+
},
250+
"note": {
251+
"type": "string"
252+
},
253+
"groups": {
254+
"type": "array",
255+
"prefixItems": [{
256+
"type": "object",
257+
"additionalProperties": false,
258+
"properties": {
259+
"id": {
260+
"type": "string"
261+
},
262+
"displayName": {
263+
"type": "string"
264+
},
265+
"description": {
266+
"type": "string"
267+
}
268+
},
269+
"required": [
270+
"id",
271+
"displayName"
272+
]
273+
}
274+
]
275+
},
276+
"subscriptions": {
277+
"type": "array",
278+
"prefixItems": [{
279+
"type": "object",
280+
"additionalProperties": false,
281+
"properties": {
282+
"id": {
283+
"type": "string"
284+
},
285+
"displayName": {
286+
"type": "string"
287+
},
288+
"scope": {
289+
"type": "string"
290+
},
291+
"allowTracing": {
292+
"type": "boolean"
293+
}
294+
},
295+
"required": [
296+
"id",
297+
"displayName",
298+
"scope",
299+
"allowTracing"
300+
]
301+
}
302+
]
303+
}
304+
},
305+
"required": [
306+
"firstName",
307+
"lastName",
308+
"mailAddress",
309+
"sendNotification",
310+
"confirmationType"
311+
]
312+
}
313+
]
314+
}
315+
```
316+
317+
</details>
318+
319+
<details>
320+
321+
<summary>Example Configuration File</summary>
322+
323+
``` json
324+
[
325+
{
326+
"firstName": "John",
327+
"lastName": "Doe",
328+
"mailAddress": "john@doe.com",
329+
"sendNotification": true,
330+
"confirmationType": "signup",
331+
"note": "This is an optional note",
332+
"groups": [
333+
{
334+
"id": "SomeGroupId",
335+
"displayName": "Example Group",
336+
"description": "This is a example group"
337+
}
338+
],
339+
"subscriptions": [
340+
{
341+
"id": "SomeSubscriptionId",
342+
"displayName": "Example Subscription",
343+
"scope": "/products/starter",
344+
"allowTracing": false
345+
}
346+
]
347+
},
348+
{
349+
"firstName": "Jane",
350+
"lastName": "Doe",
351+
"mailAddress": "jane@doe.com",
352+
"sendNotification": true,
353+
"confirmationType": "signup",
354+
"note": "This is an optional note",
355+
"groups": [
356+
{
357+
"id": "SomeGroupId",
358+
"displayName": "Example Group",
359+
"description": "This is a example group"
360+
},
361+
{
362+
"id": "SomeOtherGroupId",
363+
"displayName": "Another Example Group",
364+
"description": "This is another example group"
365+
}
366+
],
367+
"subscriptions": [
368+
{
369+
"id": "SomeSubscriptionId",
370+
"displayName": "Example Subscription",
371+
"scope": "/products/starter",
372+
"allowTracing": false
373+
},
374+
{
375+
"id": "SomeSOtherubscriptionId",
376+
"displayName": "Another Example Subscription",
377+
"scope": "/products/starter",
378+
"allowTracing": false
379+
}
380+
]
381+
}
382+
]
383+
```
384+
385+
</details>
386+
387+
**Example**
388+
389+
Apply user configuration to an existing Azure API Management instance.
390+
391+
```powershell
392+
PS> Create-AzApiManagementUserAccountsFromConfig `
393+
-ResourceGroupName $ResourceGroup `
394+
-ServiceName $ServiceName `
395+
-ConfigurationFile ".\config.json"
396+
# User configuration has successfully been applied for user with ID 'some-id' to Azure API Management service '$ServiceName' in resource group '$ResourceGroup'
397+
```
398+
399+
Apply user configuration to an existing Azure API Management instance and strictly adhere to the configuration file.
400+
401+
```powershell
402+
PS> Create-AzApiManagementUserAccountsFromConfig `
403+
-ResourceGroupName $ResourceGroup `
404+
-ServiceName $ServiceName `
405+
-ConfigurationFile ".\config.json" `
406+
-StrictlyFollowConfigurationFile
407+
# User configuration has successfully been applied for user with ID 'some-id' to Azure API Management service '$ServiceName' in resource group '$ResourceGroup'
408+
```
409+
410+
195411
## Removing a user from an Azure API Management service
196412

197413
Remove a user from an existing Azure API Management instance based on e-mail address.

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

106 Bytes
Binary file not shown.

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

Lines changed: 55 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
Backs up an API Management service.
44
55
.Description
6-
The Backup-AzApiManagement cmdlet backs up an instance of an Azure API Management service by getting the account storage key and creating an new storage context.
6+
The Backup-AzApiManagement cmdlet backs up an instance of an Azure API Management instance by getting the account storage key and creating an new storage context.
77
This cmdlet stores the backup as an Azure Storage blob.
88
99
.Parameter ResourceGroupName
@@ -144,10 +144,10 @@ Export-ModuleMember -Function Create-AzApiManagementApiOperation
144144
[Optional] The confirmation type to use when creating the user, this can be set to 'invite' or 'signup'.
145145
146146
.Parameter ApiVersion
147-
[Optional] The version of the api to be used.
147+
[Optional] The version of the API to be used.
148148
149149
.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).
150+
[Optional] The Id of the subscription containing the Azure API Management instance. When not provided, it will be retrieved from the current context (Get-AzContext).
151151
152152
.Parameter AccessToken
153153
[Optional] The access token to be used. When not provided, it will be retrieved from the current context (Get-AzContext).
@@ -177,6 +177,54 @@ function Create-AzApiManagementUserAccount {
177177

178178
Export-ModuleMember -Function Create-AzApiManagementUserAccount
179179

180+
<#
181+
.Synopsis
182+
Create or update users in Azure API Management.
183+
184+
.Description
185+
Create or update users in an existing Azure API Management instance based on a configuration file.
186+
187+
.Parameter ResourceGroupName
188+
The resource group containing the API Management service.
189+
190+
.Parameter ServiceName
191+
The name of the API Management service located in Azure.
192+
193+
.Parameter ConfigurationFile
194+
The file containing the users and their configuration.
195+
196+
.Parameter StrictlyFollowConfigurationFile
197+
Indicates whether the configuration file should strictly be followed, for example remove the user from groups not defined in the configuration file.
198+
199+
.Parameter ApiVersion
200+
[Optional] The version of the API to be used.
201+
202+
.Parameter SubscriptionId
203+
[Optional] The Id of the subscription containing the Azure API Management instance. When not provided, it will be retrieved from the current context (Get-AzContext).
204+
205+
.Parameter AccessToken
206+
[Optional] The access token to be used. When not provided, it will be retrieved from the current context (Get-AzContext).
207+
#>
208+
function Create-AzApiManagementUserAccountsFromConfig {
209+
param(
210+
[string][Parameter(Mandatory = $true)] $ResourceGroupName = $(throw "Resource group name is required"),
211+
[string][parameter(Mandatory = $true)] $ServiceName = $(throw "API management service name is required"),
212+
[string][Parameter(Mandatory = $true)] $ConfigurationFile = $(throw "Name of configuration file is required"),
213+
[switch][parameter(Mandatory = $false)] $StrictlyFollowConfigurationFile = $false,
214+
[string][parameter(Mandatory = $false)] $ApiVersion = "2021-08-01",
215+
[string][parameter(Mandatory = $false)] $SubscriptionId,
216+
[string][parameter(Mandatory = $false)] $AccessToken
217+
)
218+
if ($StrictlyFollowConfigurationFile) {
219+
. $PSScriptRoot\Scripts\Create-AzApiManagementUserAccountsFromConfig.ps1 -ResourceGroupName $ResourceGroupName -ServiceName $ServiceName -ConfigurationFile $ConfigurationFile -ApiVersion $ApiVersion -SubscriptionId $SubscriptionId -AccessToken $AccessToken -StrictlyFollowConfigurationFile
220+
} else {
221+
. $PSScriptRoot\Scripts\Create-AzApiManagementUserAccountsFromConfig.ps1 -ResourceGroupName $ResourceGroupName -ServiceName $ServiceName -ConfigurationFile $ConfigurationFile -ApiVersion $ApiVersion -SubscriptionId $SubscriptionId -AccessToken $AccessToken
222+
}
223+
}
224+
225+
Export-ModuleMember -Function Create-AzApiManagementUserAccountsFromConfig
226+
227+
180228
<#
181229
.Synopsis
182230
Removes a user from Azure API Management.
@@ -194,7 +242,7 @@ Export-ModuleMember -Function Create-AzApiManagementUserAccount
194242
The e-mail address of the user.
195243
196244
.Parameter SubscriptionId
197-
[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).
245+
[Optional] The Id of the subscription containing the Azure API Management instance. When not provided, it will be retrieved from the current context (Get-AzContext).
198246
199247
.Parameter AccessToken
200248
[Optional] The access token to be used. When not provided, it will be retrieved from the current context (Get-AzContext).
@@ -281,7 +329,7 @@ Export-ModuleMember -Function Remove-AzApiManagementDefaults
281329
The resource group containing the Azure API Management instance.
282330
283331
.Parameter ServiceName
284-
The name of the Azure API Management service located in Azure.
332+
The name of the Azure API Management instance located in Azure.
285333
286334
.Parameter ApiId
287335
The ID to identify the API running in API Management.
@@ -415,7 +463,7 @@ Export-ModuleMember -Function Restore-AzApiManagementService
415463
function Set-AzApiManagementApiSubscriptionKey {
416464
param(
417465
[Parameter(Mandatory = $true)][string] $ResourceGroupName = $(throw = "Resource group name is required"),
418-
[Parameter(Mandatory = $true)][string] $ServiceName = $(throw = "Azure API Management service name is required"),
466+
[Parameter(Mandatory = $true)][string] $ServiceName = $(throw = "Azure API Management instance name is required"),
419467
[Parameter(Mandatory = $true)][string] $ApiId = $("API ID to identitfy the Azure API Management instance is required"),
420468
[Parameter(Mandatory = $false)][string] $HeaderName = "x-api-key",
421469
[Parameter(Mandatory = $false)][string] $QueryParamName = "apiKey"
@@ -463,7 +511,7 @@ Export-ModuleMember -Function Upload-AzApiManagementCertificate
463511
Uploads a CA certificate to the Azure API management certificate store.
464512
465513
.Description
466-
Uploads a public CA certificate to the Azure API management Root certificate store, allowing certificate validation in the Azure API Management service policy.
514+
Uploads a public CA certificate to the Azure API management Root certificate store, allowing certificate validation in the Azure API Management instance policy.
467515
468516
.Parameter ResourceGroupName
469517
The name of the resource group containing the Azure API Management instance.

‎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-AzApiManagementUserAccountsFromConfig.ps1" />
3637
<Compile Include="Scripts\Create-AzApiManagementUserAccount.ps1" />
3738
<Compile Include="Scripts\Import-AzApiManagementProductPolicy.ps1" />
3839
<Compile Include="Scripts\Remove-AzApiManagementDefaults.ps1" />

‎src/Arcus.Scripting.ApiManagement/Scripts/Backup-AzApiManagementService.ps1‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ if ($storageKeys -eq $null -or $storageKeys.count -eq 0) {
2222
$storageContext = New-AzStorageContext -StorageAccountName $StorageAccountName -StorageAccountKey $storageKey.Value
2323
Write-Host "New Azure storage context for storage account '$($StorageAccountName)' with storage key created!" -ForegroundColor Green
2424

25-
Write-Verbose "Start backing up Azure API management service '$($ServiceName)' in resource group '$($ResourceGroupName)'..."
25+
Write-Verbose "Start backing up Azure API Management instance '$($ServiceName)' in resource group '$($ResourceGroupName)'..."
2626
if ($BlobName -ne $null) {
2727
if ($PassThru) {
2828
if ($DefaultProfile -ne $null) {
@@ -53,5 +53,5 @@ if ($storageKeys -eq $null -or $storageKeys.count -eq 0) {
5353
}
5454
}
5555

56-
Write-Host "Azure API management service '$($ServiceName)' in resource group '$($ResourceGroupName)' is backed-up!" -ForegroundColor Green
56+
Write-Host "Azure API Management instance '$($ServiceName)' in resource group '$($ResourceGroupName)' is backed-up!" -ForegroundColor Green
5757
}

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

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -12,20 +12,20 @@ param(
1212

1313
$apim = Get-AzApiManagement -ResourceGroupName $ResourceGroupName -Name $ServiceName
1414
if ($apim -eq $null) {
15-
throw "Unable to find the Azure API Management service '$ServiceName' in resource group '$ResourceGroupName'"
15+
throw "Unable to find the Azure API Management instance '$ServiceName' in resource group '$ResourceGroupName'"
1616
}
1717
$apimContext = New-AzApiManagementContext -ResourceGroupName $ResourceGroupName -ServiceName $ServiceName
1818

1919
New-AzApiManagementOperation -Context $apimContext -ApiId $ApiId -OperationId $OperationId -Name $OperationName -Method $Method -UrlTemplate $UrlTemplate -Description $Description
20-
Write-Host "New API operation '$OperationName' was added on Azure API Management service '$ServiceName' in resource group '$ResourceGroupName'"
20+
Write-Host "New API operation '$OperationName' was added on Azure API Management instance '$ServiceName' in resource group '$ResourceGroupName'"
2121

2222
if($OperationId -eq "" -or $PolicyFilePath -eq "")
2323
{
24-
Write-Warning "No policy has been defined for Azure API Management service '$ServiceName' in resource group '$ResourceGroupName'"
24+
Write-Warning "No policy has been defined for Azure API Management instance '$ServiceName' in resource group '$ResourceGroupName'"
2525
}
2626
else
2727
{
28-
Write-Verbose "Updating policy of the operation '$OperationId' in API '$ApiId' of the Azure API Management service '$ServiceName' in resource group '$ResourceGroupName'..."
28+
Write-Verbose "Updating policy of the operation '$OperationId' in API '$ApiId' of the Azure API Management instance '$ServiceName' in resource group '$ResourceGroupName'..."
2929
Set-AzApiManagementPolicy -Context $apimContext -ApiId $ApiId -OperationId $OperationId -PolicyFilePath $PolicyFilePath
30-
Write-Host "Updated policy of the operation '$OperationId' in API '$ApiId' of the Azure API Management service '$ServiceName' in resource group '$ResourceGroupName'" -ForegroundColor Green
30+
Write-Host "Updated policy of the operation '$OperationId' in API '$ApiId' of the Azure API Management instance '$ServiceName' in resource group '$ResourceGroupName'" -ForegroundColor Green
3131
}

0 commit comments

Comments
 (0)