Description

Allow Connect-GitHubAccount to authenticate as a GitHub App using an Azure Key Vault key reference instead of providing a raw private key. Introduce an optional parameter (-KeyVaultKey) to the App parameter set, which would trigger JWT signing using Azure Key Vault rather than locally.

When provided, store this reference in the context, and have Resolve-GitHubContext (or a helper function) sign the JWT via KeyVault every time an app token is needed.

Example:

Connect-GitHubAccount -ClientID $ClientID -KeyVaultKey $vaultKey

Benefits

• Security: Eliminates the need to store or expose private key material locally.
• Compliance: Aligns with security best practices recommended by both GitHub and Azure.
• Integration: Simplifies workflows in environments already using Azure Key Vault for secret management.

Considerations

Security

• Azure Key Vault keys should be created as non-exportable to ensure the private key cannot be extracted.
• Permissions should be tightly scoped to only allow the keys/sign operation.
• Recommend enabling auditing/logging for Key Vault to track signing activities.
• Ensure clear error messages for authentication or permission issues.

Required Permissions

• The Azure identity (managed identity, service principal, etc.) used by the module needs the keys/sign permission on the target Azure Key Vault key.
• Document clearly the permissions required to facilitate correct configuration.

Performance

• Remote signing via Azure Key Vault introduces additional latency (typically tens to hundreds of milliseconds).
• Recommend caching GitHub installation tokens locally (valid up to 1 hour) to minimize frequent Key Vault calls.
• Handle potential Azure throttling (HTTP 429) gracefully, with recommended retry strategies.

Environment Compatibility and Authentication

Ensure compatibility and document recommended approaches for these environments:

• GitHub Actions:

  • Authenticate using azure/login.
  • Prefer using Azure CLI (az keyvault key sign) as it's readily available and faster to execute.

• Azure Automation:

  • Authenticate using Managed Identity and Azure PowerShell with Get-AzAccessToken.

• Azure Functions:

  • Authenticate using Managed Identity and Azure PowerShell with Get-AzAccessToken.

Tooling

Support JWT signing via:

• Azure CLI (az keyvault key sign) - preferred for GitHub Actions.
• Az PowerShell (Invoke-AzKeyVaultKeyOperation) - supported for Azure Automation and Azure Functions.
• Direct REST API calls - recommended as an advanced fallback option to reduce external dependencies.

Implementation Pre-requisites

• 🩹 [Patch]: Refactor: Split JWT Creation and Signing Logic #471

Alternatives

• Storing raw keys locally (less secure)
• Storing private keys as secrets (still exposes key material to the module)

Recommended Implementation Documentation

• Azure CLI: az keyvault key sign
• Az PowerShell: Invoke-AzKeyVaultKeyOperation
• Azure Key Vault REST API: Sign
• Managing private keys securely (GitHub)

Inspired by:

• Using Azure Key Vault to Sign JWT Thanks: @juunas11
• Signing JWT with Azure Key Vault Thanks: @Manbearpiet