Merge pull request #51 from JulianHayward/users/kaiaschulz/1.3.2

Bump module version to 1.3.2 and enhance logging for access token val…

Author: JulianHayward

README.md

@@ -5,6 +5,7 @@
 You want to have an easy way to interact with the Microsoft Azure API endpoints without getting headache of taking care of valid bearer token and error handling?
 
 ## Table of content
+
 - [AzAPICall](#azapicall)
   - [Table of content](#table-of-content)
   - [AzAPICall example](#azapicall-example)
@@ -20,6 +21,8 @@ You want to have an easy way to interact with the Microsoft Azure API endpoints
   - [Good to know](#good-to-know)
     - [Don´t accept the defaults](#dont-accept-the-defaults)
     - [AzAPICall Tracking](#azapicall-tracking)
+  - [Runtime environment](#runtime-environment)
+    - [Azure DevOps](#azure-devops)
   - [Prerequisites](#prerequisites)
     - [Powershell Modules](#powershell-modules)
   - [Contribute](#contribute)
@@ -54,38 +57,49 @@ $parameters4AzAPICallModule = @{
 $azAPICallConf = initAzAPICall @parameters4AzAPICallModule
 ```
 
-### How to use AzAPICall ?!  
+### How to use AzAPICall ?
 
 #### Example for Microsoft Graph
-Get AAD Groups:  
+
+Get AAD Groups:
+
 ```POWERSHELL
 AzAPICall -uri "$($azAPICallConf['azAPIEndpointUrls'].MicrosoftGraph)/v1.0/groups" -AzAPICallConfiguration $azAPICallConf
 ```
+
 _confused by_ '`$($azAPICallConf['azAPIEndpointUrls'].MicrosoftGraph)`'_? It´s basically a reference to the correct endpoint (think public cloud, sovereign clouds). You can of course also hardcode the endpoint URI:_
 
 ```POWERSHELL
 AzAPICall -uri "https://graph.microsoft.com/v1.0/groups" -AzAPICallConfiguration $azAPICallConf
 ```
 
 #### Example for Azure Resource Manager
-List Azure Subscriptions (expect multiple results):  
+
+List Azure Subscriptions (expect multiple results):
+
 ```POWERSHELL
 AzAPICall -uri "$($azAPICallConf['azAPIEndpointUrls'].ARM)/subscriptions?api-version=2020-01-01" -AzAPICallConfiguration $azAPICallConf
 ```
-Get Azure Subscription (expect one result):  
+
+Get Azure Subscription (expect one result):
+
 ```POWERSHELL
 AzAPICall -uri "$($azAPICallConf['azAPIEndpointUrls'].ARM)/subscriptions/$($subscriptionId)?api-version=2020-01-01" -AzAPICallConfiguration $azAPICallConf -listenOn Content
 ```
+
 [AzAPICallExample.ps1](pwsh/AzAPICallExample.ps1)
 
 ## Public functions
-* initAzAPICall
-* AzAPICall
-* getAzAPICallFunctions
-* getAzAPICallRuleSet
-* createBearerToken
 
-createBearerToken example: 
+- initAzAPICall
+
+- AzAPICall
+- getAzAPICallFunctions
+- getAzAPICallRuleSet
+- createBearerToken
+
+createBearerToken example:
+
 ```POWERSHELL
 $azAPICallConf = initAzAPICall
 createBearerToken -AzAPICallConfiguration $azapicallconf -targetEndPoint 'Storage'
@@ -107,7 +121,7 @@ Add a new endpoint -> setAzureEnvironment.ps1
 
 ## General Parameters
 
-Parameters that can be used with the initAzAPICall cmdlet 
+Parameters that can be used with the initAzAPICall cmdlet
 
 Example: [Initialize AzAPICall](#initialize-azapicall)
 
@@ -121,7 +135,6 @@ Example: [Initialize AzAPICall](#initialize-azapicall)
 | AzAPICallCustomRuleSet              | `object` | wip                                                                                                                                                                                                                                                                                                                                                                                                                          |          |
 | SkipAzContextSubscriptionValidation |  `bool`  | Only use in case you do not have any valid (quotaId != AAD_* & state != disabled) subscriptions in your tenant OR you do not have any permissions on Azure Resources (Management Groups, Subscriptions, Resource Groups, Resources) and but want to connect non-ARM API endpoints such as Microsoft Graph etc. (Per default a subscription is expected to be present in the Az context, if not then AzAPICall will throw..). |          |
 
-
 ## AzAPICall Parameters
 
 Parameters that can be used with the AzAPICall cmdlet
@@ -144,6 +157,7 @@ Example: `AzAPICall -uri "https://management.azure.com/subscriptions?api-version
 | unhandledErrorAction   | `string`  | When a call to an API returns an Error, that error is processed by AzAPICallErrorHandler. If that error is unhandled, AzAPICallErrorHandler will log the error and Throw a message which terminates the script. This happens when parameter -unhandledErrorAction is set to `Stop` (which is also the default if not configured). When -unhandledErrorAction is set to `Continue`, AzAPICallErrorHandler logs the error including full details to raise an issue at the repo and continues processing. When -unhandledErrorAction is set to `ContinueQuiet`, AzAPICallErrorHandler only logs the error (excluding full details to raise an issue at the repo) and continues processing | default is `Stop`, options: `Continue`, `ContinueQuiet` |
 
 ## Good to know
+
 ### Don´t accept the defaults
 
 By default, endPoints return results in batches of e.g. `100`. You can increase the return count defining e.g. `$top=999` (`$top` requires use of `consistencyLevel` = `eventual`)
@@ -155,6 +169,7 @@ To get some insights on all API calls you can check the `$azAPICallConf['arrayAP
 ```POWERSHELL
 $azAPICallConf['arrayAPICallTracking'][0] | ConvertTo-Json
 ```
+
 ```JSON
 {
   "CurrentTask": "Microsoft Graph API: Get - Groups",
@@ -183,10 +198,13 @@ $azAPICallConf['arrayAPICallTracking'][0] | ConvertTo-Json
                     [..]
                   }"
 ```
+
 As well you can see how fast a AzAPICall was responding:
+
 ```POWERSHELL
 ($azAPICallConf['arrayAPICallTracking'].Duration | Measure-Object -Average -Maximum -Minimum) | ConvertTo-Json
 ```
+
 ```JSON
 {
   "Count": 1000,
@@ -199,8 +217,51 @@ As well you can see how fast a AzAPICall was responding:
 }
 ```
 
+## Runtime environment
+
+### Azure DevOps
+
+If you are using a PowerShell script within a pipeline and an `OIDC` service connection, you need to set the [`SYSTEM_ACCESSTOKEN` environment variable](https://learn.microsoft.com/en-us/azure/devops/pipelines/build/variables?view=azure-devops&tabs=yaml#systemaccesstoken) in the task of your pipeline. This allows the AzAPICall module to use it for token renewal:
+
+```YML
+  - task: AzurePowerShell@5
+    displayName: 'OIDC testing with AzurePowerShell@5'
+    env:
+      SYSTEM_ACCESSTOKEN: $(System.AccessToken)
+    inputs:
+      azureSubscription: '$(ServiceConnection)'
+      azurePowerShellVersion: LatestVersion
+      ScriptType: 'InlineScript'
+      Inline: |
+        try {
+            Install-Module -Name 'AzAPICall' -RequiredVersion '1.3.2' -ErrorAction Stop # ? https://www.powershellgallery.com/packages/AzAPICall/1.3.2
+        }
+        catch {
+            Write-Warning '33596ac3-5aab-4704-aef2-e1de6ac71f05'
+            Throw $_
+        }
+
+        # [..]
+```
+
+Otherwise, you will encounter an error message during your pipeline execution:
+
+```POWERSHELL
+Logging: /home/vsts/work/1/s/AzAPICall/functions/AzAPICallFunctions.ps1:1672
+Line |
+1672 |  …             Logging -logMessage "-ERROR: OIDC ADO - Could not find ac …
+     |                ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+     | -ERROR: OIDC ADO - Could not find access token, check if the environment
+     | variable 'SYSTEM_ACCESSTOKEN' exists and has valid data.
+     | https://learn.microsoft.com/en-us/azure/devops/pipelines/build/variables?view=azure-devops&tabs=yaml#systemaccesstoken
+
+##[error]PowerShell exited with code '1'.
+```
+
 ## Prerequisites
+
 ### Powershell Modules
+
 | PowerShell Module |
 | ----------------- |
 | Az.Accounts       |
@@ -210,8 +271,9 @@ As well you can see how fast a AzAPICall was responding:
 Your contribution is welcome.
 
 Thanks to the awesome contributors:
-* Brooks Vaugn
-* Kai Schulz
-* Simon Wahlin
-* Tim Stock
-* Tim Wanierke
+
+- Brooks Vaugn
+- Kai Schulz
+- Simon Wahlin
+- Tim Stock
+- Tim Wanierke

pwsh/module/build/AzAPICall.zip

@@ -12,7 +12,7 @@
     RootModule        = 'AzAPICall.psm1'
 
     # Version number of this module.
-    ModuleVersion     = '1.3.1'
+    ModuleVersion     = '1.3.2'
 
     # Supported PSEditions
     # CompatiblePSEditions = @()

pwsh/module/build/AzAPICall/AzAPICall.psd1

@@ -1668,6 +1668,11 @@ function createBearerToken {
                     if ($_ -like '*ClientAssertionCredential authentication failed*') {
                         Logging -logMessage " Running on '$(($AzApiCallConfiguration['htParameters']).codeRunPlatform)' OIDC: '$(($AzApiCallConfiguration['htParameters']).accountType)' - Getting Bearer Token from Login endpoint '$(($AzApiCallConfiguration['azAPIEndpointUrls']).Login)'"
 
+                        if ([string]::IsNullOrWhiteSpace($env:SYSTEM_ACCESSTOKEN)) {
+                            Logging -logMessage "-ERROR: OIDC ADO - Could not find access token, check if the environment variable 'SYSTEM_ACCESSTOKEN' exists and has valid data. https://learn.microsoft.com/en-us/azure/devops/pipelines/build/variables?view=azure-devops&tabs=yaml#systemaccesstoken" -logMessageWriteMethod 'Error'
+                            Throw "Error - OIDC ADO - Could not find access token, check if the environment variable 'SYSTEM_ACCESSTOKEN' exists and has valid data. https://learn.microsoft.com/en-us/azure/devops/pipelines/build/variables?view=azure-devops&tabs=yaml#systemaccesstoken"
+                        }
+
                         try {
                             $serviceConnectionId = (Get-ChildItem -ErrorAction Stop -Path Env: -Recurse -Include ENDPOINT_DATA_*)[0].Name.Split('_')[2]
                         }
@@ -1794,7 +1799,7 @@ function getAzAPICallFunctions {
 function getAzAPICallRuleSet {
     return $function:AzAPICallErrorHandler.ToString()
 }
-function getAzAPICallVersion { return '1.3.1' }
+function getAzAPICallVersion { return '1.3.2' }
 
 function getJWTDetails {
     <#
@@ -2088,19 +2093,19 @@ function initAzAPICall {
 }
 function Logging {
     param (
-        [Parameter(Mandatory = $true)]
+        [Parameter(Mandatory)]
         [string]
         $logMessage,
 
-        [Parameter(Mandatory = $false)]
+        [Parameter()]
         [string]
         $logMessageForegroundColor = $debugForeGroundColor,
 
-        [Parameter(Mandatory = $false)]
+        [Parameter()]
         [string]
         $logMessageWriteMethod = $AzAPICallConfiguration['htParameters'].writeMethod,
 
-        [Parameter(Mandatory = $false)]
+        [Parameter()]
         [bool]
         $preventWriteOutput
     )
@@ -2122,6 +2127,7 @@ function Logging {
         'Progress' { Write-Progress $logMessage }
         'Verbose' { Write-Verbose $logMessage -Verbose }
         'Warning' { Write-Warning $logMessage }
+        'Throw' { throw $logMessage }
         Default { Write-Host $logMessage -ForegroundColor $logMessageForegroundColor }
     }
 }

pwsh/module/build/AzAPICall/functions/AzAPICallFunctions.ps1

@@ -12,7 +12,7 @@
     RootModule        = 'AzAPICall.psm1'
 
     # Version number of this module.
-    ModuleVersion     = '1.3.1'
+    ModuleVersion     = '1.3.2'
 
     # Supported PSEditions
     # CompatiblePSEditions = @()

pwsh/module/dev/AzAPICall/AzAPICall.psd1

@@ -1,18 +1,18 @@
 function Logging {
     param (
-        [Parameter(Mandatory = $true)]
+        [Parameter(Mandatory)]
         [string]
         $logMessage,
 
-        [Parameter(Mandatory = $false)]
+        [Parameter()]
         [string]
         $logMessageForegroundColor = $debugForeGroundColor,
 
-        [Parameter(Mandatory = $false)]
+        [Parameter()]
         [string]
         $logMessageWriteMethod = $AzAPICallConfiguration['htParameters'].writeMethod,
 
-        [Parameter(Mandatory = $false)]
+        [Parameter()]
         [bool]
         $preventWriteOutput
     )
@@ -34,6 +34,7 @@
         'Progress' { Write-Progress $logMessage }
         'Verbose' { Write-Verbose $logMessage -Verbose }
         'Warning' { Write-Warning $logMessage }
+        'Throw' { throw $logMessage }
         Default { Write-Host $logMessage -ForegroundColor $logMessageForegroundColor }
     }
 }

pwsh/module/dev/AzAPICall/functions/Logging.ps1

@@ -160,6 +160,11 @@
                     if ($_ -like '*ClientAssertionCredential authentication failed*') {
                         Logging -logMessage " Running on '$(($AzApiCallConfiguration['htParameters']).codeRunPlatform)' OIDC: '$(($AzApiCallConfiguration['htParameters']).accountType)' - Getting Bearer Token from Login endpoint '$(($AzApiCallConfiguration['azAPIEndpointUrls']).Login)'"
 
+                        if ([string]::IsNullOrWhiteSpace($env:SYSTEM_ACCESSTOKEN)) {
+                            Logging -logMessage "-ERROR: OIDC ADO - Could not find access token, check if the environment variable 'SYSTEM_ACCESSTOKEN' exists and has valid data. https://learn.microsoft.com/en-us/azure/devops/pipelines/build/variables?view=azure-devops&tabs=yaml#systemaccesstoken" -logMessageWriteMethod 'Error'
+                            Throw "Error - OIDC ADO - Could not find access token, check if the environment variable 'SYSTEM_ACCESSTOKEN' exists and has valid data. https://learn.microsoft.com/en-us/azure/devops/pipelines/build/variables?view=azure-devops&tabs=yaml#systemaccesstoken"
+                        }
+
                         try {
                             $serviceConnectionId = (Get-ChildItem -ErrorAction Stop -Path Env: -Recurse -Include ENDPOINT_DATA_*)[0].Name.Split('_')[2]
                         }

pwsh/module/dev/AzAPICall/functions/createBearerToken.ps1

@@ -1 +1 @@
-function getAzAPICallVersion { return '1.3.1' }
+function getAzAPICallVersion { return '1.3.2' }