Support using a remote HSM or JWT signing service in lieu of private keys #712

jeffwilcox · 2025-08-06T21:23:09Z

Resolves #711 711

To use @octokit/auth-app.js, you must always provide a full privateKey option. This can expose a GitHub App's private key to runtime environments which is much less secure than keeping the private key in a HSM or remote key signing service.

The GitHub docs on storing private keys specifically suggests using sign-only keys stored securely.

This change is a basic update to allow for this alternate path from a privateCertificate for this more advanced and secure approach.

I'm looking for feedback on this pull request, especially around variable names, approach on the types for the Strategy, etc. Since most users will continue to use privateKey, unless the external JWT signing option is truthy, I've kept the "privateKey required" type helpful error message in place.

Before the change?

No support for remote signing servers or HSMs.

After the change?

Can optionally provide a callback to remotely sign a JWT, instead of using the universal-github-app-jwt dependency and an in-memory key

Pull request checklist

Tests for the changes have been added (for bug fixes / features)
Docs have been reviewed and added / updated if needed (for bug fixes / features)

Does this introduce a breaking change?

No

To enable the use of Azure Key Vault keys, or other HSMs, this allows for a callback to be provided in lieu of a GitHub App's private certificate. Does not contain test updates.

github-actions · 2025-08-06T21:23:18Z

👋 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! 🚀

gr2m

Hi Jeff!! I think it's a great change! The request to accept a JWT instead of a private key came up several times across octokit and its dependents.

I like the approach of using a callback instead of passing a fixed JWT. That way @octokit/auth-app can re-create the JWT as needed.

I'd recommend to verify that usage with Octokit keeps working as before. It should be able to create installation tokens upon first request and auto-renew it when it expires.

Maybe consider renaming externalSignJwt to something simpler, like createJwt? The method should also accept a timeDifference argument to account for time skew between client and server, see

auth-app.js/src/hook.ts

Lines 69 to 79 in 3b732be

    
           state.log.warn(error.message); 
        
           state.log.warn( 
        
             `[@octokit/auth-app] GitHub API time and system time are different by ${diff} seconds. Retrying request with the difference accounted for.`, 
        
           ); 
        
           const { token } = await getAppAuthentication({ 
        
             ...state, 
        
             timeDifference: diff, 
        
           }); 
        
           endpoint.headers.authorization = `bearer ${token}`; 
        
           return request(endpoint as EndpointOptions);

jeffwilcox · 2025-08-11T17:13:48Z

Sounds good, I'll get this cleaned up a bit. We've been using it in production with rest.js on jobs that run 24/7 and renew just fine but I'll integrate the updates I can make here to bake it a bit more.

- renames to shorter "signJwt" method - adds "timeDifference" (number, seconds) to pass along for any errors related to skew

…fwilcox/auth-app.js into external-jwt-signing-support

jeffwilcox · 2025-08-19T18:24:25Z

@gr2m k, minor updates addressed for now. Hopefully straightforward to rebase vs merge at some point.

name createJwt for simplicity
passing along any timeDifference seconds to the method

Since the universal JWT module itself has a built-in -30s buffer in its logic, I don't love it, but added a comment in the README example to as much. It's probably not worth refactoring multiple libraries to consider passing now as a true Date or not implicitly addressing clock skew with the 30s in there.

jeffwilcox · 2025-08-19T21:11:29Z

Also just to confirm, wrote a hello world octokit app that calls rest.repos.get every minute and let it run the last hour+, along with some classy console logging when a new JWT is minted by my remote signing service in the callback.

crafting an awesome JWT now: 418639 at 2025-08-19T20:04:33.495Z
crafting an awesome JWT now: 418639 at 2025-08-19T21:03:56.167Z

App ran fine.

src/types.ts

wolfy1339 · 2025-08-20T01:47:52Z

test/index.test.ts

      appId: APP_ID,
      // @ts-ignore
-      privateKey: undefined,
+      privateKey: undefined as string,


This shouldn't be needed. The // @ts-ignore should make it be ignored

wolfy1339

LGTM

github-actions · 2025-08-26T17:58:39Z

🎉 This PR is included in version 8.1.0 🎉

The release is available on:

Your semantic-release bot 📦🚀

jeffwilcox added 3 commits August 6, 2025 17:04

Support external JWT signing

53ddd90

To enable the use of Azure Key Vault keys, or other HSMs, this allows for a callback to be provided in lieu of a GitHub App's private certificate. Does not contain test updates.

Tests and README updates

bbfaa2d

TS: validation

afe21c5

octokitbot added this to 🧰 Octokit Active Aug 6, 2025

github-project-automation bot moved this to 🆕 Triage in 🧰 Octokit Active Aug 6, 2025

jeffwilcox mentioned this pull request Aug 6, 2025

[BUG]: Error authenticating API requests from Octokit JS client when using private key in Azure key vault octokit/octokit.js#2623

Open

1 task

gr2m reviewed Aug 9, 2025

View reviewed changes

gr2m mentioned this pull request Aug 9, 2025

be able to fetch Installation Token using a BYO JWT actions/create-github-app-token#219

Open

wolfy1339 added the Type: Feature New feature or request label Aug 11, 2025

wolfy1339 moved this from 🆕 Triage to 🏗 In progress in 🧰 Octokit Active Aug 11, 2025

jeffwilcox added 4 commits August 19, 2025 10:11

Merge branch 'main' into external-jwt-signing-support

4f75991

Support remote JWT signing: API changes

11361f1

- renames to shorter "signJwt" method - adds "timeDifference" (number, seconds) to pass along for any errors related to skew

Merge branch 'external-jwt-signing-support' of https://github.com/jef…

dfaaaa5

…fwilcox/auth-app.js into external-jwt-signing-support

Use "createJwt" for callback option name.

184c19f

wolfy1339 reviewed Aug 20, 2025

View reviewed changes

Type improvement - optional parameter

980b3bd

wolfy1339 approved these changes Aug 26, 2025

View reviewed changes

wolfy1339 merged commit ef7a95d into octokit:main Aug 26, 2025
7 checks passed

github-project-automation bot moved this from 🏗 In progress to ✅ Done in 🧰 Octokit Active Aug 26, 2025

github-actions bot added the released label Aug 26, 2025

Brakistad mentioned this pull request Nov 5, 2025

BUG: v2.1.4, update of auth-app.js is breaking, even if it claims not to be actions/create-github-app-token#301

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Support using a remote HSM or JWT signing service in lieu of private keys #712

Support using a remote HSM or JWT signing service in lieu of private keys #712

Uh oh!

jeffwilcox commented Aug 6, 2025

Uh oh!

github-actions bot commented Aug 6, 2025

Uh oh!

gr2m left a comment

Uh oh!

jeffwilcox commented Aug 11, 2025

Uh oh!

jeffwilcox commented Aug 19, 2025

Uh oh!

jeffwilcox commented Aug 19, 2025

Uh oh!

Uh oh!

wolfy1339 Aug 20, 2025

Uh oh!

wolfy1339 left a comment

Uh oh!

Uh oh!

github-actions bot commented Aug 26, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	state.log.warn(error.message);
	state.log.warn(
	`[@octokit/auth-app] GitHub API time and system time are different by ${diff} seconds. Retrying request with the difference accounted for.`,
	);

	const { token } = await getAppAuthentication({
	...state,
	timeDifference: diff,
	});
	endpoint.headers.authorization = `bearer ${token}`;
	return request(endpoint as EndpointOptions);

Support using a remote HSM or JWT signing service in lieu of private keys #712

Support using a remote HSM or JWT signing service in lieu of private keys #712

Uh oh!

Conversation

jeffwilcox commented Aug 6, 2025

Before the change?

After the change?

Pull request checklist

Does this introduce a breaking change?

Uh oh!

github-actions bot commented Aug 6, 2025

Uh oh!

gr2m left a comment

Choose a reason for hiding this comment

Uh oh!

jeffwilcox commented Aug 11, 2025

Uh oh!

jeffwilcox commented Aug 19, 2025

Uh oh!

jeffwilcox commented Aug 19, 2025

Uh oh!

Uh oh!

wolfy1339 Aug 20, 2025

Choose a reason for hiding this comment

Uh oh!

wolfy1339 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

github-actions bot commented Aug 26, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants