[FEAT]: Support external KMS signing for GitHub App JWT authentication

[u-kai]

Describe the need

Description

Support delegating GitHub App JWT signing to external KMS providers (AWS KMS, GCP Cloud KMS, Azure Key Vault), so the private key never leaves the KMS boundary.

Motivation

Supply chain attacks targeting CI/CD pipelines are an increasing concern.
A GitHub App with permissions to manage repositories and environments can access all environments and their secrets across an entire Organization.

If the App's private key leaks from a CI/CD environment, the blast radius is enormous.

External KMS services ensure the private key never leaves the KMS — signing is performed via API calls, and all usage is auditable through cloud provider logging.

Proposed solution

Add a kms_key_id option that delegates JWT signing to an external KMS instead of requiring a raw PEM key:

provider "github" {
  app_auth {
    id              = "12345"
    installation_id = "67890"
    kms_key_id      = "arn:aws:kms:ap-northeast-1:111122223333:key/xxxx"
  }
}

The provider would detect the KMS backend from the key identifier format and use the cloud SDK's default credential chain for authentication.

Considerations

• pem_file and kms_key_id are mutually exclusive
• Users must import the GitHub App's RSA key into their KMS with signing permissions
• Implementation can be phased: start with one cloud provider, add others incrementally

SDK Version

No response

API Version

No response

Relevant log output

Code of Conduct

• I agree to follow this project's Code of Conduct

[github-actions]

👋 Hi! Thank you for this contribution! Just to let you know, our GitHub SDK team does a round of issue and PR reviews twice a week, every Monday and Friday! We have a process in place for prioritizing and responding to your input. Because you are a part of this community please feel free to comment, add to, or pick up any issues/PRs that are labeled with Status: Up for grabs. You & others like you are the reason all of this works! So thank you & happy coding! 🚀

[deiga]

This is a really cool idea!

I don't personally know how to implement this, so if you have more knowledge of that I'd welcome a more detailed write-up of how to build this.
And also how to use automated tests to verify this (especially the ~automatic setup would be important)

[u-kai]

Thanks for the response, and sorry for the late reply.

The current signing path in github/apps.go (generateAppJWT) takes raw PEM bytes and hands them directly to go-jose. My proposal is to introduce a small Signer interface:

type Signer interface {
    SignJWT(context.Context,claims jwt.Claims) (string, error)
}

Then refactor generateAppJWT to take a Signer instead of pemData.
The existing PEM path becomes a PEMSigner implementation — no behavior change for current users.
KMS backends (AWS KMS, GCP KMS, Azure Key Vault) plug in as additional implementations that call the cloud SDK's Sign API instead of signing locally.

Testing

• Unit tests are straightforward with a fake Signer — verify JWT claims are constructed correctly and the token-exchange flow works.
• PEMSigner can be verified end-to-end locally by signing and validating against the public key.
• KMS backends: each KMS implementation is essentially a thin wrapper that calls the cloud SDK's Sign API with the correct algorithm and key reference.
  The responsibility of importing the RSA key into KMS with the right permissions sits with the user, not with this provider.
  Our responsibility is to call the SDK correctly — which can be verified through code review against the official SDK documentation (e.g., AWS KMS Sign API).

That said, I understand the desire for e2e verification.
However, I'm not in a position to judge whether this repository can or should integrate with cloud providers like AWS.
If you have any guidance or preferences on that, I'd appreciate the input.

Happy to open a draft PR for the interface refactor as a starting point!

[deiga]

Thanks for the thorough writeup. I'm not sure if it's sustainable for this provider to maintain some wrapper code for different KMS providers. I wonder if something like that would be possible with using other terraform providers together with this one. 🤔

In general I like the idea, but as this adds some complexity to the codebase there needs to be a thorough discussion amongst maintainers.

A draft PR would be welcome as it can make discussion easier with tangible examples. I just can't promise at this point that it will be accepted for merging

[u-kai]

Sorry for the late reply. I've opened two draft PRs for this.

The first approach integrates AWS KMS signing directly into the provider. If this is
accepted, I'd like to extend it to support other cloud providers as well.
That said, I agree with your point that it comes with maintenance overhead.

The second approach accepts a pre-signed JWT and uses it as-is.
I looked into your suggestion of combining other Terraform providers,
but couldn't find a way to make it work for JWT signing.
Instead, I landed on letting users handle the signing externally (e.g., via AWS KMS or Vault)
and pass the resulting JWT through an environment variable.
This puts more work on the user side, but keeps the provider itself much simpler to maintain.

[deiga]

Thanks for doing the work and providing both draft PRs!

I'm fairly certain we are not going to be able to incorporate the AWS KMS support.

The second approach could have an example of using local_command to call aws kms sign to generate the JWT token via CLI
https://registry.terraform.io/providers/hashicorp/local/latest/docs/actions/command
https://registry.terraform.io/providers/hashicorp/local/latest/docs/data-sources/command

[deiga]

@stevehipwell What do you think about this suggestion?

I like the idea of being able to secure the PKEY somewhere else and use KMS signing. I can already see that this would generate interest at my company