chore: streamline logging in apim, appservice & az active dir (#348)

* chore: streamline logging in apim, appservice & az active dir

* pr-fix: correct exception messages in unit test assertions

* Update src/Arcus.Scripting.ActiveDirectory/Scripts/Add-AzADAppRoleAssignment.ps1

Co-authored-by: Pim Simons <32359437+pim-simons@users.noreply.github.com>

* pr-sug: streamline logging parameters

* pr-fix: update w/ more streamlined logging params

* pr-sug: use green color for all succesful operations

Co-authored-by: Pim Simons <32359437+pim-simons@users.noreply.github.com>

Author: stijnmoreels

src/Arcus.Scripting.ActiveDirectory/Scripts/Add-AzADAppRoleAssignment.ps1

@@ -24,7 +24,7 @@ if (!$adServicePrincipalRoleAssignTo) {
 
 try {
     if ($adApplication.AppRole.Value -notcontains $Role) {
-        Write-Host "Active Directory Application '$($adApplication.DisplayName)' does not contain the role '$Role', adding the role"
+        Write-Verbose "Active Directory Application '$($adApplication.DisplayName)' does not contain the role '$Role', adding the role"
 
         $newRole = @{
           "DisplayName" = $Role
@@ -38,11 +38,11 @@ try {
         $adApplication.AppRole += $newRole
 
         Update-AzADApplication -ObjectId $adApplication.Id -AppRole $adApplication.AppRole
-        Write-Host "Added role '$Role' to Active Directory Application '$($adApplication.DisplayName)'"
+        Write-Host "Added role '$Role' to Active Directory Application '$($adApplication.DisplayName)'" -ForegroundColor White
 
         $currentAppRole = $newRole
     } else {
-        Write-Host "Active Directory Application '$($adApplication.DisplayName)' already contains the role '$Role'"
+        Write-Host "Active Directory Application '$($adApplication.DisplayName)' already contains the role '$Role'" -ForegroundColor Yellow
         $currentAppRole = $adApplication.AppRole | Where-Object Value -eq $Role
     }
 
@@ -51,7 +51,7 @@ try {
         $updatedAdServicePrincipal = Get-MgServicePrincipal -ServicePrincipalId $adServicePrincipal.Id
 
         while ($updatedAdServicePrincipal.AppRoles.Value -notcontains $Role -and $counter -lt 10) {
-            Write-Host "Role '$Role' has been added to Active Directory Application '$($adApplication.DisplayName)' but not yet available for use, waiting 10 seconds to retry..."
+            Write-Versbose "Role '$Role' has been added to Active Directory Application '$($adApplication.DisplayName)' but not yet available for use, waiting 10 seconds to retry..."
             Start-Sleep -Seconds 10
             $counter++
             $updatedAdServicePrincipal = Get-MgServicePrincipal -ServicePrincipalId $adServicePrincipal.Id
@@ -62,9 +62,9 @@ try {
         }
 
         $newRoleAssignment = New-MgServicePrincipalAppRoleAssignment -ServicePrincipalId $adServicePrincipalRoleAssignTo.Id -PrincipalId $adServicePrincipalRoleAssignTo.Id -ResourceId $adServicePrincipal.Id -AppRoleId $currentAppRole.Id
-        Write-Host "Role Assignment for the role '$Role' added to the Active Directory Application '$($adApplicationRoleAssignTo.DisplayName)'"
+        Write-Host "Role Assignment for the role '$Role' added to the Active Directory Application '$($adApplicationRoleAssignTo.DisplayName)'" -ForegroundColor Green
     } else {
-        Write-Host "Active Directory Application '$($adApplicationRoleAssignTo.DisplayName)' already contains a role assignment for the role '$Role'"
+        Write-Host "Active Directory Application '$($adApplicationRoleAssignTo.DisplayName)' already contains a role assignment for the role '$Role'" -ForegroundColor Yellow
     }
 } catch {
     throw "Adding the role '$Role' for the Active Directory Application with ClientId '$ClientId' failed. Details: $($_.Exception.Message)"

src/Arcus.Scripting.ActiveDirectory/Scripts/List-AzADAppRoleAssignments.ps1

@@ -5,28 +5,28 @@ param(
 
 $adApplication = Get-AzADApplication -Filter "AppId eq '$ClientId'"
 if (!$adApplication) { 
-    throw "Active Directory Application for the ClientId '$ClientId' could not be found" 
+    throw "Active Directory Application for the ClientId '$ClientId' could not be found"
 }
 $adServicePrincipal = Get-AzADServicePrincipal -Filter "AppId eq '$ClientId'"
 if (!$adServicePrincipal) { 
-    throw "Active Directory Service Principal for the ClientId '$ClientId' could not be found" 
+    throw "Active Directory Service Principal for the ClientId '$ClientId' could not be found"
 }
 
 if ($RolesAssignedToClientId -ne '') {
-    $adApplicationRolesAssignedTo = Get-AzADApplication -Filter "AppId eq '$RolesAssignedToClientId'"    
+    $adApplicationRolesAssignedTo = Get-AzADApplication -Filter "AppId eq '$RolesAssignedToClientId'"
     if (!$adApplicationRolesAssignedTo) { 
-        throw "Active Directory Application for the ClientId '$RolesAssignedToClientId' could not be found" 
+        throw "Active Directory Application for the ClientId '$RolesAssignedToClientId' could not be found"
     }
     $adServicePrincipalRolesAssignedTo = Get-AzADServicePrincipal -Filter "AppId eq '$RolesAssignedToClientId'"
     if (!$adServicePrincipalRolesAssignedTo) { 
-        throw "Active Directory Service Principal for the ClientId '$RolesAssignedToClientId' could not be found" 
+        throw "Active Directory Service Principal for the ClientId '$RolesAssignedToClientId' could not be found"
     }
 }
 
 try {
     if ($adApplication.AppRole.Count -eq 0)
     {
-        Write-Host "No roles found"
+        Write-Host "No roles found in Active Directory Application '$($adApplication.DisplayName)'" -ForegroundColor Yellow
     }
 
     foreach ($appRole in $adApplication.AppRole) {
@@ -41,11 +41,11 @@ try {
             foreach ($serviceAppRoleAssignment in $appRoleAssignments) {
                 $servicePrincipal = Get-AzADServicePrincipal -ObjectId $serviceAppRoleAssignment.PrincipalId
                 if ($servicePrincipal -ne $null) {
-                    Write-Host "Role '$($appRole.Value)' is assigned to the Active Directory Application '$($serviceAppRoleAssignment.PrincipalDisplayName)' with ID '$($servicePrincipal.AppId)'" -ForegroundColor White
+                    Write-Host "Role '$($appRole.Value)' is assigned to the Active Directory Application '$($serviceAppRoleAssignment.PrincipalDisplayName)' with ID '$($servicePrincipal.AppId)'" -ForegroundColor Green
                 }
             }
         } else {
-            Write-Host "No role assignments found"
+            Write-Host "No role assignments found in Active Directory Application '$($adApplication.DisplayName)'" -ForegroundColor Yellow
         }
     }
 } catch {

src/Arcus.Scripting.ActiveDirectory/Scripts/Remove-AzADAppRoleAssignment.ps1

@@ -25,7 +25,7 @@ if (!$adServicePrincipalRoleRemoveFrom) {
 
 try {
     if ($adApplication.AppRole.Value -notcontains $Role) {
-        Write-Host "Active Directory Application '$($adApplication.DisplayName)' does not contain the role '$Role', skipping removal"
+        Write-Host "Active Directory Application '$($adApplication.DisplayName)' does not contain the role '$Role', skipping removal" -ForegroundColor Yellow
     } else {
         $appRole = $adApplication.AppRole | Where-Object {($_.DisplayName -eq $Role)}
         $appRoleAssignment = Get-MgServicePrincipalAppRoleAssignedTo -ServicePrincipalId $adServicePrincipal.Id | Where-Object {($_.AppRoleId -eq $appRole.Id) -and ($_.PrincipalId -eq $adServicePrincipalRoleRemoveFrom.Id)}
@@ -34,7 +34,7 @@ try {
             Remove-MgServicePrincipalAppRoleAssignment -ServicePrincipalId $adServicePrincipalRoleRemoveFrom.Id -AppRoleAssignmentId $appRoleAssignment.Id
             Write-Host "Role assignment for '$Role' has been removed from Active Directory Application '$($adApplicationRoleRemoveFrom.DisplayName)'"
         } else {
-            Write-Host "Role '$Role' is not assigned to Active Directory Application '$($adApplicationRoleRemoveFrom.DisplayName)', skipping role assignment removal"
+            Write-Host "Role '$Role' is not assigned to Active Directory Application '$($adApplicationRoleRemoveFrom.DisplayName)', skipping role assignment removal" -ForegroundColor Yellow
         }
 
         if ($RemoveRoleIfNoAssignmentsAreLeft) {
@@ -49,7 +49,7 @@ try {
                 $appRoles = $adApplication.AppRole | Where-Object Id -ne $appRole.Id
                 if ($appRoles) {
                     Update-AzADApplication -ObjectId $adApplication.Id -AppRole $appRoles
-                    Write-Host "Role '$Role' removed from Active Directory Application '$($adApplication.DisplayName)' as no more role assignments were left and the option 'RemoveRoleIfNoAssignmentsAreLeft' is set"
+                    Write-Host "Role '$Role' with App Role '$appRoles' removed from Active Directory Application '$($adApplication.DisplayName)' as no more role assignments were left and the option 'RemoveRoleIfNoAssignmentsAreLeft' is set"
                 } else {
                     Update-AzADApplication -ObjectId $adApplication.Id -AppRole @()
                     Write-Host "Role '$Role' removed from Active Directory Application '$($adApplication.DisplayName)' as no more role assignments were left and the option 'RemoveRoleIfNoAssignmentsAreLeft' is set"

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

@@ -9,20 +9,20 @@ param(
     [Parameter(Mandatory = $false)][Microsoft.Azure.Commands.Common.Authentication.Abstractions.Core.IAzureContextContainer] $DefaultProfile = $null
 )
 
-Write-Host "Getting Azure storage account key..."
+Write-Verbose "Getting Azure storage account key for storage account '$($StorageAccountName)' in resource group '$($StorageAccountResourceGroupName)'..."
 $storageKeys = Get-AzStorageAccountKey -ResourceGroupName $StorageAccountResourceGroupName -StorageAccountName $StorageAccountName
 
 if ($storageKeys -eq $null -or $storageKeys.count -eq 0) {
-    Write-Error "Cannot backup API Management service because no access keys found for storage account '$StorageAccountName'"
+    Write-Error "Cannot backup API Management service because no access keys found for storage account '$StorageAccountName' in resource group '$($StorageAccountResourceGroupName)'"
 } else {
-    Write-Host "Got Azure storage key!"
+    Write-Host "Got Azure storage key for storage account '$($StorageAccountName)' in resource group '$($StorageAccountResourceGroupName)'!" -ForegroundColor Green
     $storageKey = $storageKeys[0]
 
-    Write-Host "Create new Azure storage context with storage key..."
+    Write-Verbose "Create new Azure storage context for storage account '$($StorageAccountName)' with storage key..."
     $storageContext = New-AzStorageContext -StorageAccountName $StorageAccountName -StorageAccountKey $storageKey.Value
-    Write-Host "New Azure storage context with storage key created!"
+    Write-Host "New Azure storage context for storage account '$($StorageAccountName)' with storage key created!" -ForegroundColor Green
 
-    Write-Host "Start backing up API management service..."
+    Write-Verbose "Start backing up Azure API management service '$($ServiceName)' in resource group '$($ResourceGroupName)'..."
     if ($BlobName -ne $null) {
         if ($PassThru) {
             if ($DefaultProfile -ne $null) {
@@ -53,5 +53,5 @@ if ($storageKeys -eq $null -or $storageKeys.count -eq 0) {
         }
     }
 
-    Write-Host "API management service is backed-up!"
+    Write-Host "Azure API management service '$($ServiceName)' in resource group '$($ResourceGroupName)' is backed-up!" -ForegroundColor Green
 }

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

@@ -12,19 +12,20 @@ param(
 
 $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"
+    throw "Unable to find the Azure API Management service '$ServiceName' in resource group '$ResourceGroupName'"
 }
 $apimContext = New-AzApiManagementContext -ResourceGroupName $ResourceGroupName -ServiceName $ServiceName
 
 New-AzApiManagementOperation -Context $apimContext -ApiId $ApiId -OperationId $OperationId -Name $OperationName -Method $Method -UrlTemplate $UrlTemplate -Description $Description
-Write-Host "New API operation '$OperationName' on API Management instance was added."
+Write-Host "New API operation '$OperationName' was added on Azure API Management service '$($ServiceName)' in resource group '$($ResourceGroupName)'"
 
 if($OperationId -eq "" -or $PolicyFilePath -eq "")
 {
-    Write-Host "No policy has been defined."
+    Write-Host "No policy has been defined for Azure API Management service '$ServiceName' in resource group '$ResourceGroupName'" -ForegroundColor Yellow
 }
 else
 {
-    Write-Host "Updating policy of the operation '$OperationId' in API '$ApiId'"
+    Write-Verbose "Updating policy of the operation '$OperationId' in API '$ApiId' of the Azure API Management service '$ServiceName' in resource group '$ResourceGroupName'..."
     Set-AzApiManagementPolicy -Context $apimContext -ApiId $ApiId -OperationId $OperationId -PolicyFilePath $PolicyFilePath
+    Write-Host "Updated policy of the operation '$OperationId' in API '$ApiId' of the Azure API Management service '$ServiceName' in resource group '$ResourceGroupName'" -ForegroundColor Green
 }

src/Arcus.Scripting.ApiManagement/Scripts/Create-AzApiManagementUserAccount.ps1

@@ -16,7 +16,7 @@ param(
 
 $apimContext = Get-AzApiManagement -ResourceGroupName $ResourceGroupName -Name $ServiceName
 if ($apimContext -eq $null) {
-    throw "Unable to find the Azure API Management Instance $ServiceName in resource group $ResourceGroupName"
+    throw "Unable to find the Azure API Management service '$ServiceName' in resource group '$ResourceGroupName'"
 }
 
 if ($SubscriptionId -eq "" -or $AccessToken -eq "") {
@@ -34,11 +34,11 @@ try
 {
     if($ConfirmationType -eq 'invite')
     {
-        Write-Host "Attempting to invite $FirstName $LastName ($mailAddress)"
+        Write-Verbose "Attempting to invite $FirstName $LastName ($mailAddress) for Azure API Management service '$ServiceName' in resource group '$ResourceGroupName'"
     }
     else
     {
-        Write-Host "Attempting to create account for $FirstName $LastName ($mailAddress)"
+        Write-Verbose "Attempting to create account for $FirstName $LastName ($mailAddress) for Azure API Management service '$ServiceName' in resource group '$ResourceGroupName'"
     }
 
     $jsonRequest = ConvertTo-Json -Depth 3 @{
@@ -67,19 +67,19 @@ try
 
     if($ConfirmationType -eq 'invite')
     {
-        Write-Host "Invitation has been sent to $FirstName $LastName ($mailAddress)"
+        Write-Host "Invitation has been sent to $FirstName $LastName ($mailAddress) for Azure API Management service '$ServiceName' in resource group '$ResourceGroupName'" -ForegroundColor Green
     }
     else
     {
-        Write-Host "Account has been created for $FirstName $LastName ($mailAddress)"
+        Write-Host "Account has been created for $FirstName $LastName ($mailAddress) for Azure API Management service '$ServiceName' in resource group '$ResourceGroupName'" -ForegroundColor Green
         if($Password -eq $null -or $Password -eq ""){
-            Write-Host "Since no password was provided, one has been generated. Please advise the user to change this password the first time logging in"
+            Write-Host "Since no password was provided, one has been generated. Please advise the user to change this password the first time logging in for the Azure API Management service '$($ServiceName)' in resource group '$($ResourceGroupName)'" -ForegroundColor Yellow
         }
     }
 
     return $UserId
 }
 catch {
     Write-Host $_
-    throw "Failed to create an account for $FirstName $LastName ($MailAddress) in the APIM instance $ServiceName"
+    throw "Failed to create an account for $FirstName $LastName ($MailAddress) for Azure API Management service '$ServiceName' in resource group '$ResourceGroupName'"
 }

src/Arcus.Scripting.ApiManagement/Scripts/Import-AzApiManagementApiPolicy.ps1

@@ -7,14 +7,14 @@ param(
 
 $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"
+    throw "Unable to find the Azure API Management service '$ServiceName' in resource group '$ResourceGroupName'"
 }
 $apimContext = New-AzApiManagementContext -ResourceGroupName $ResourceGroupName -ServiceName $ServiceName
 
-Write-Host "Updating policy of API '$ApiId'"
+Write-Verbose "Updating policy of API '$ApiId' for the Azure API Management service '$ServiceName' in resource group '$ResourceGroupName'"
 $result = Set-AzApiManagementPolicy -Context $apimContext -ApiId $ApiId -PolicyFilePath $PolicyFilePath -PassThru
 if ($result) {
-    Write-Host "Successfully updated API policy"
+    Write-Host "Successfully updated API policy for the Azure API Management service '$ServiceName' in resource group '$ResourceGroupName'" -ForegroundColor Green
 } else {
-    throw "Failed to update API policy, please check parameters"
+    throw "Failed to update API policy for the Azure API Management service '$ServiceName' in resource group '$ResourceGroupName', please check parameters"
 }

src/Arcus.Scripting.ApiManagement/Scripts/Import-AzApiManagementOperationPolicy.ps1

@@ -8,14 +8,14 @@ param(
 
 $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"
+    throw "Unable to find the Azure API Management service '$ServiceName' in resource group '$ResourceGroupName'"
 }
 $apimContext = New-AzApiManagementContext -ResourceGroupName $ResourceGroupName -ServiceName $ServiceName
 
-Write-Host "Updating policy of the operation '$OperationId' in API '$ApiId'"
+Write-Verbose "Updating policy of the operation '$OperationId' in API '$ApiId' for the Azure API Management service '$ServiceName' in resource group '$ResourceGroupName'"
 $result = Set-AzApiManagementPolicy -Context $apimContext -ApiId $ApiId -OperationId $OperationId -PolicyFilePath $PolicyFilePath -PassThru
 if ($result) {
-    Write-Host "Successfully updated the operation policy"
+    Write-Host "Successfully updated the operation policy for the Azure API Management service $ServiceName in resource group $ResourceGroupName" -ForegroundColor Green
 } else {
-    throw "Failed to update the operation policy, please check parameters"
+    throw "Failed to update the operation policy for the Azure API Management service '$ServiceName' in resource group '$ResourceGroupName', please check parameters"
 }

src/Arcus.Scripting.ApiManagement/Scripts/Import-AzApiManagementProductPolicy.ps1

@@ -7,14 +7,14 @@ param(
 
 $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"
+    throw "Unable to find the Azure API Management service '$ServiceName' in resource group '$ResourceGroupName'"
 }
 $apimContext = New-AzApiManagementContext -ResourceGroupName $ResourceGroupName -ServiceName $ServiceName
 
-Write-Host "Updating policy of product '$ProductId'"
+Write-Verbose "Updating policy of product '$ProductId' for the Azure API Management service '$ServiceName' in resource group '$ResourceGroupName'"
 $result = Set-AzApiManagementPolicy -Context $apimContext -ProductId $ProductId -PolicyFilePath $PolicyFilePath -PassThru
 if ($result) {
-    Write-Host "Successfully updated the product policy"
+    Write-Host "Successfully updated the product policy for the Azure API Management service $ServiceName in resource group $ResourceGroupName" -ForegroundColor Green
 } else {
-    throw "Failed to update the product policy"
+    throw "Failed to update the product policy for the Azure API Management service '$ServiceName' in resource group '$ResourceGroupName'"
 }