🚀 [Feature]: Adding functionality to sign JWTs via Key Vault Keys (#481)

## Description

This pull request introduces support for signing GitHub App JSON Web
Tokens (JWTs) using Azure Key Vault in addition to local RSA private
keys. It also refactors and enhances existing JWT-related functionality
to improve maintainability and clarity. The most significant changes
include the addition of Azure Key Vault integration, refactoring of JWT
signing methods, and updates to related utility functions.

- Fixes #470.

### Improvements to Authentication Logic

* Enhanced `Connect-GitHubAccount` to support both private key and Azure
Key Vault-based authentication for GitHub Apps, introducing new
parameter sets and validation for `KeyVaultKeyReference`.

### Azure Key Vault Integration

* Added a new `KeyVaultKeyReference` property to the `GitHubAppContext`
class for specifying Azure Key Vault keys as an alternative to local
private keys.
* Introduced the `Add-GitHubKeyVaultJWTSignature` function to sign JWTs
using Azure Key Vault keys, supporting both Azure CLI and Az PowerShell
authentication.
* Added utility functions `Test-GitHubAzureCLI` and
`Test-GitHubAzPowerShell` to check for Azure CLI and Az PowerShell
module installation and authentication.

### Refactoring of JWT Signing

* Renamed `Add-GitHubJWTSignature` to `Add-GitHubLocalJWTSignature` for
clarity and updated it to use the new `GitHubJWTComponent` helper for
base64 URL encoding.
* Updated `Update-GitHubAppJWT` to conditionally use either
`Add-GitHubLocalJWTSignature` or `Add-GitHubKeyVaultJWTSignature` based
on the presence of `PrivateKey` or `KeyVaultKeyReference` in the
context.

### Enhancements to JWT Utility Functions

* Added `GitHubJWTComponent` class to centralize base64 URL encoding
logic and simplify JWT creation.
* Updated `New-GitHubUnsignedJWT` to use `GitHubJWTComponent` for
encoding JWT headers and payloads.

## See it in action


https://github.com/PSModule/GitHub-Script/actions/runs/16364842244/job/46239654619



## Type of change

<!-- Use the check-boxes [x] on the options that are relevant. -->

- [ ] 📖 [Docs]
- [ ] 🪲 [Fix]
- [ ] 🩹 [Patch]
- [ ] ⚠️ [Security fix]
- [x] 🚀 [Feature]
- [ ] 🌟 [Breaking change]

## Checklist

<!-- Use the check-boxes [x] on the options that are relevant. -->

- [x] I have performed a self-review of my own code
- [x] I have commented my code, particularly in hard-to-understand areas

Author: MariusStorhaug

README.md

@@ -154,6 +154,48 @@ Connect-GitHubAccount -ClientID $ClientID -PrivateKey $PrivateKey
 
 Using this approach, the module will autogenerate a JWT every time you run a command. I.e. Get-GitHubApp.
 
+#### Using a GitHub App with Azure Key Vault
+
+For enhanced security, you can store your GitHub App's keys in Azure Key Vault and use that as way to signing the JWTs.
+This approach requires a pre-authenticated session with either Azure CLI or Azure PowerShell.
+
+**Prerequisites:**
+- Azure CLI authenticated session (`az login`) or Azure PowerShell authenticated session (`Connect-AzAccount`)
+- GitHub App private key stored as a key in Azure Key Vault, with 'Sign' as a permitted operation
+- Appropriate permissions to read keys from the Key Vault, like 'Key Vault Crypto User'
+
+**Using Azure CLI authentication:**
+
+```powershell
+# Ensure you're authenticated with Azure CLI
+az login
+
+# Connect using Key Vault key reference (URI with or without version)
+Connect-GitHubAccount -ClientID $ClientID -KeyVaultKeyReference 'https://my-keyvault.vault.azure.net/keys/github-app-private-key'
+✓ Logged in as my-github-app!
+```
+
+**Using Azure PowerShell authentication:**
+
+```powershell
+# Ensure you're authenticated with Azure PowerShell
+Connect-AzAccount
+
+# Connect using Key Vault key reference (URI with or without version)
+Connect-GitHubAccount -ClientID $ClientID -KeyVaultKeyReference 'https://my-keyvault.vault.azure.net/keys/github-app-private-key'
+✓ Logged in as my-github-app!
+```
+
+**Using Key Vault key reference with version:**
+
+```powershell
+# Connect using Key Vault key reference with specific version
+Connect-GitHubAccount -ClientID $ClientID -KeyVaultKeyReference 'https://my-keyvault.vault.azure.net/keys/github-app-private-key/abc123def456'
+✓ Logged in as my-github-app!
+```
+
+This method ensures that your private key is securely stored in Azure Key Vault and never exposed in your scripts or configuration files.
+
 #### Using a different host
 
 If you are using GitHub Enterprise, you can use the `-Host` (or `-HostName`) parameter to specify the host you want to connect to.

src/classes/public/Context/GitHubContext/GitHubAppContext.ps1

@@ -5,6 +5,9 @@
     # The private key for the app.
     [securestring] $PrivateKey
 
+    # Azure Key Vault key reference for JWT signing (alternative to PrivateKey).
+    [string] $KeyVaultKeyReference
+
     # Owner of the GitHub App
     [string] $OwnerName
 
@@ -41,6 +44,7 @@
         $this.PerPage = $Object.PerPage
         $this.ClientID = $Object.ClientID
         $this.PrivateKey = $Object.PrivateKey
+        $this.KeyVaultKeyReference = $Object.KeyVaultKeyReference
         $this.OwnerName = $Object.OwnerName
         $this.OwnerType = $Object.OwnerType
         $this.Permissions = $Object.Permissions

src/classes/public/GitHubJWTComponent.ps1

@@ -0,0 +1,15 @@
+class GitHubJWTComponent {
+    static [string] ToBase64UrlString([hashtable] $Data) {
+        return [GitHubJWTComponent]::ConvertToBase64UrlFormat(
+            [System.Convert]::ToBase64String(
+                [System.Text.Encoding]::UTF8.GetBytes(
+                    (ConvertTo-Json -InputObject $Data)
+                )
+            )
+        )
+    }
+
+    static [string] ConvertToBase64UrlFormat([string] $Base64String) {
+        return $Base64String.TrimEnd('=').Replace('+', '-').Replace('/', '_')
+    }
+}

src/functions/private/Apps/GitHub Apps/Add-GitHubKeyVaultJWTSignature.ps1

@@ -0,0 +1,101 @@
+function Add-GitHubKeyVaultJWTSignature {
+    <#
+        .SYNOPSIS
+        Adds a JWT signature using Azure Key Vault.
+
+        .DESCRIPTION
+        Signs an unsigned JWT (header.payload) using a key stored in Azure Key Vault.
+        The function supports authentication via Azure CLI or Az PowerShell module and returns the signed JWT as a secure string.
+
+        .EXAMPLE
+        Add-GitHubKeyVaultJWTSignature -UnsignedJWT 'header.payload' -KeyVaultKeyReference 'https://myvault.vault.azure.net/keys/mykey'
+
+        Output:
+        ```powershell
+        System.Security.SecureString
+        ```
+
+        Signs the provided JWT (`header.payload`) using the specified Azure Key Vault key, returning a secure string containing the signed JWT.
+
+        .OUTPUTS
+        System.Security.SecureString
+
+        .NOTES
+        The function returns a secure string containing the fully signed JWT (header.payload.signature).
+        Ensure Azure CLI or Az PowerShell is installed and authenticated before running this function.
+    #>
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute(
+        'PSAvoidUsingConvertToSecureStringWithPlainText', '',
+        Justification = 'Used to handle secure string private keys.'
+    )]
+    [CmdletBinding()]
+    param (
+        # The unsigned JWT (header.payload) to sign.
+        [Parameter(Mandatory)]
+        [string] $UnsignedJWT,
+
+        # The Azure Key Vault key URL used for signing.
+        [Parameter(Mandatory)]
+        [string] $KeyVaultKeyReference
+    )
+
+    begin {
+        $stackPath = Get-PSCallStackPath
+        Write-Debug "[$stackPath] - Start"
+    }
+
+    process {
+        if (Test-GitHubAzureCLI) {
+            try {
+                $accessToken = (az account get-access-token --resource 'https://vault.azure.net/' --output json | ConvertFrom-Json).accessToken
+            } catch {
+                Write-Error "Failed to get access token from Azure CLI: $_"
+                return
+            }
+        } elseif (Test-GitHubAzPowerShell) {
+            try {
+                $accessToken = (Get-AzAccessToken -ResourceUrl 'https://vault.azure.net/').Token
+            } catch {
+                Write-Error "Failed to get access token from Az PowerShell: $_"
+                return
+            }
+        } else {
+            Write-Error 'Azure authentication is required. Please ensure you are logged in using either Azure CLI or Az PowerShell.'
+            return
+        }
+
+        if ($accessToken -isnot [securestring]) {
+            $accessToken = ConvertTo-SecureString -String $accessToken -AsPlainText
+        }
+
+        $hash64url = [GitHubJWTComponent]::ConvertToBase64UrlFormat(
+            [System.Convert]::ToBase64String(
+                [System.Security.Cryptography.SHA256]::Create().ComputeHash(
+                    [System.Text.Encoding]::UTF8.GetBytes($UnsignedJWT)
+                )
+            )
+        )
+
+        $KeyVaultKeyReference = $KeyVaultKeyReference.TrimEnd('/')
+
+        $params = @{
+            Method         = 'POST'
+            URI            = "$KeyVaultKeyReference/sign?api-version=7.4"
+            Body           = @{
+                alg   = 'RS256'
+                value = $hash64url
+            } | ConvertTo-Json
+            ContentType    = 'application/json'
+            Authentication = 'Bearer'
+            Token          = $accessToken
+        }
+
+        $result = Invoke-RestMethod @params
+        $signature = $result.value
+        return (ConvertTo-SecureString -String "$UnsignedJWT.$signature" -AsPlainText)
+    }
+
+    end {
+        Write-Debug "[$stackPath] - End"
+    }
+}

…s/GitHub Apps/Add-GitHubJWTSignature.ps1 …Hub Apps/Add-GitHubLocalJWTSignature.ps1src/functions/private/Apps/GitHub Apps/Add-GitHubJWTSignature.ps1 renamed to src/functions/private/Apps/GitHub Apps/Add-GitHubLocalJWTSignature.ps1 src/functions/private/Apps/GitHub Apps/Add-GitHubJWTSignature.ps1 renamed to src/functions/private/Apps/GitHub Apps/Add-GitHubLocalJWTSignature.ps1

@@ -1,4 +1,4 @@
-function Add-GitHubJWTSignature {
+function Add-GitHubLocalJWTSignature {
     <#
         .SYNOPSIS
         Signs a JSON Web Token (JWT) using a local RSA private key.
@@ -8,26 +8,25 @@ function Add-GitHubJWTSignature {
         This function handles the RSA signing process and returns the complete signed JWT.
 
         .EXAMPLE
-        Add-GitHubJWTSignature -UnsignedJWT 'eyJ0eXAiOi...' -PrivateKey '--- BEGIN RSA PRIVATE KEY --- ... --- END RSA PRIVATE KEY ---'
+        Add-GitHubLocalJWTSignature -UnsignedJWT 'eyJ0eXAiOi...' -PrivateKey '--- BEGIN RSA PRIVATE KEY --- ... --- END RSA PRIVATE KEY ---'
 
         Adds a signature to the unsigned JWT using the provided private key.
 
         .OUTPUTS
-        String
+        securestring
 
         .NOTES
         This function isolates the signing logic to enable support for multiple signing methods.
 
         .LINK
-        https://psmodule.io/GitHub/Functions/Apps/GitHub%20App/Add-GitHubJWTSignature
+        https://psmodule.io/GitHub/Functions/Apps/GitHub%20App/Add-GitHubLocalJWTSignature
     #>
     [Diagnostics.CodeAnalysis.SuppressMessageAttribute(
-        'PSAvoidUsingConvertToSecureStringWithPlainText',
-        '',
+        'PSAvoidUsingConvertToSecureStringWithPlainText', '',
         Justification = 'Used to handle secure string private keys.'
     )]
     [CmdletBinding()]
-    [OutputType([string])]
+    [OutputType([securestring])]
     param(
         # The unsigned JWT (header.payload) to sign.
         [Parameter(Mandatory)]
@@ -52,14 +51,16 @@ function Add-GitHubJWTSignature {
         $rsa.ImportFromPem($PrivateKey)
 
         try {
-            $signature = [Convert]::ToBase64String(
-                $rsa.SignData(
-                    [System.Text.Encoding]::UTF8.GetBytes($UnsignedJWT),
-                    [System.Security.Cryptography.HashAlgorithmName]::SHA256,
-                    [System.Security.Cryptography.RSASignaturePadding]::Pkcs1
+            $signature = [GitHubJWTComponent]::ConvertToBase64UrlFormat(
+                [System.Convert]::ToBase64String(
+                    $rsa.SignData(
+                        [System.Text.Encoding]::UTF8.GetBytes($UnsignedJWT),
+                        [System.Security.Cryptography.HashAlgorithmName]::SHA256,
+                        [System.Security.Cryptography.RSASignaturePadding]::Pkcs1
+                    )
                 )
-            ).TrimEnd('=').Replace('+', '-').Replace('/', '_')
-            return "$UnsignedJWT.$signature"
+            )
+            return (ConvertTo-SecureString -String "$UnsignedJWT.$signature" -AsPlainText)
         } finally {
             if ($rsa) {
                 $rsa.Dispose()

src/functions/private/Apps/GitHub Apps/New-GitHubUnsignedJWT.ps1

@@ -1,4 +1,4 @@
-function New-GitHubUnsignedJWT {
+function New-GitHubUnsignedJWT {
     <#
         .SYNOPSIS
         Creates an unsigned JSON Web Token (JWT) for a GitHub App.
@@ -38,30 +38,22 @@ function New-GitHubUnsignedJWT {
     }
 
     process {
-        $header = [Convert]::ToBase64String(
-            [System.Text.Encoding]::UTF8.GetBytes(
-                (
-                    ConvertTo-Json -InputObject @{
-                        alg = 'RS256'
-                        typ = 'JWT'
-                    }
-                )
-            )
-        ).TrimEnd('=').Replace('+', '-').Replace('/', '_')
+        $header = [GitHubJWTComponent]::ToBase64UrlString(
+            @{
+                alg = 'RS256'
+                typ = 'JWT'
+            }
+        )
         $now = [System.DateTimeOffset]::UtcNow
         $iat = $now.AddSeconds(-$script:GitHub.Config.JwtTimeTolerance)
         $exp = $now.AddSeconds($script:GitHub.Config.JwtTimeTolerance)
-        $payload = [Convert]::ToBase64String(
-            [System.Text.Encoding]::UTF8.GetBytes(
-                (
-                    ConvertTo-Json -InputObject @{
-                        iat = $iat.ToUnixTimeSeconds()
-                        exp = $exp.ToUnixTimeSeconds()
-                        iss = $ClientID
-                    }
-                )
-            )
-        ).TrimEnd('=').Replace('+', '-').Replace('/', '_')
+        $payload = [GitHubJWTComponent]::ToBase64UrlString(
+            @{
+                iat = $iat.ToUnixTimeSeconds()
+                exp = $exp.ToUnixTimeSeconds()
+                iss = $ClientID
+            }
+        )
         [pscustomobject]@{
             Base      = "$header.$payload"
             IssuedAt  = $iat.DateTime

src/functions/private/Apps/GitHub Apps/Test-GitHubJWTRefreshRequired.ps1

@@ -0,0 +1,43 @@
+function Test-GitHubJWTRefreshRequired {
+    <#
+        .SYNOPSIS
+        Test if the GitHub JWT should be refreshed.
+
+        .DESCRIPTION
+        Test if the GitHub JWT should be refreshed. JWTs are refreshed when they have 150 seconds or less remaining before expiration.
+
+        .EXAMPLE
+        Test-GitHubJWTRefreshRequired -Context $Context
+
+        This will test if the GitHub JWT should be refreshed for the specified context.
+
+        .NOTES
+        JWTs are short-lived tokens (typically 10 minutes) and need to be refreshed more frequently than user access tokens.
+        The refresh threshold is set to 150 seconds (2.5 minutes) to ensure the JWT doesn't expire during API operations.
+    #>
+    [OutputType([bool])]
+    [CmdletBinding()]
+    param(
+        # The context to run the command in. Used to get the details for the API call.
+        # Can be either a string or a GitHubContext object.
+        [Parameter(Mandatory)]
+        [object] $Context
+    )
+
+    begin {
+        $stackPath = Get-PSCallStackPath
+        Write-Debug "[$stackPath] - Start"
+    }
+
+    process {
+        try {
+            ($Context.TokenExpiresAt - [datetime]::Now).TotalSeconds -le ($script:GitHub.Config.JwtTimeTolerance / 2)
+        } catch {
+            return $true
+        }
+    }
+
+    end {
+        Write-Debug "[$stackPath] - End"
+    }
+}