universal-github-app-jwt
Advanced tools
Package description
The universal-github-app-jwt npm package is designed to help developers generate JSON Web Tokens (JWT) for GitHub Apps. This is particularly useful for authenticating GitHub Apps and making API requests on behalf of the app.
Generate JWT
This feature allows you to generate a JWT for your GitHub App using the app's ID, private key, and installation ID. The generated token can then be used to authenticate API requests.
const { createAppAuth } = require('universal-github-app-jwt');
const auth = createAppAuth({
appId: process.env.GITHUB_APP_ID,
privateKey: process.env.GITHUB_PRIVATE_KEY,
installationId: process.env.GITHUB_INSTALLATION_ID
});
async function getToken() {
const { token } = await auth({ type: 'app' });
console.log(token);
}
getToken();The octokit/auth-app package is part of the Octokit library and provides similar functionality for generating JWTs for GitHub Apps. It offers a more integrated experience with the rest of the Octokit ecosystem, which is a set of tools and libraries for working with GitHub's API.
The github-app package is another alternative for generating JWTs for GitHub Apps. It provides a straightforward API for creating tokens and can be a simpler choice for developers who do not need the full suite of features provided by Octokit.
Readme
Calculate GitHub App bearer tokens for Node & modern browsers
⚠ The private keys provide by GitHub are in PKCS#1 format, but the WebCrypto API only supports PKCS#8. And neither Node nor the WEbCrypto API supports private keys in the OpenSSH format. You can see the difference in the first line, PKCS#1 format starts with -----BEGIN RSA PRIVATE KEY----- while PKCS#8 starts with -----BEGIN PRIVATE KEY-----, and OpenSSH starts with -----BEGIN OPENSSH PRIVATE KEY-----.
You can convert PKCS#1 to PKCS#8 using oppenssl:
openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt -in private-key.pem -out private-key-pkcs8.key
You can convert OpenSSH to PKCS#8 using ssh-keygen:
cp private-key.pem private-key-pkcs8.key && ssh-keygen -m PKCS8 -N "" -f private-key-pkcs8.key
It's also possible to convert the formats with JavaScript, e.g. using node-rsa, but it turns a 4kb to a 200kb+ built. I'm looking for help to create a minimal PKCS#1 to PKCS#8 convert library that I can recommend people to use before passing the private key to githubAppJwt. Please create an issue if you'd like to help. The same to convert OpenSSH to PKCS#8.
You can convert PKCS#1 to PKCS#8 in Node.js using the built-in crypto module:
const crypto = require("crypto");
const PRIVATE_KEY = `-----BEGIN RSA PRIVATE KEY-----
...
-----END RSA PRIVATE KEY-----`;
const privateKeyPkcs8 = crypto.createPrivateKey(PRIVATE_KEY).export({
type: "pkcs8",
format: "pem",
});
When using a node, a conversion is not necessary, the implementation is agnostic to either PKCS format.
However, if you got the error Private Key is in PKCS#1 format, but only PKCS#8 is supported. inside Node.js, it is possible that your bundler or your app framework incorrectly bundled the web version instead of the node version (example).
| Browsers |
Load universal-github-app-jwt directly from esm.sh
|
|---|---|
| Node |
Install with |
| Deno |
Load |
const { token, appId, expiration } = await githubAppJwt({
id: APP_ID,
privateKey: PRIVATE_KEY,
});
The retrieved token can now be used in Authorization request header, e.g. with @octokit/request:
request("GET /app", {
headers: {
authorization: `bearer ${token}`,
},
});
For a complete implementation of GitHub App authentication strategies, see @octokit/auth-app.js.
githubAppJwt(options)| name | type | description |
|---|---|---|
options.id
|
number
| Required. Find App ID on the app’s about page in settings. |
options.privateKey
|
string
|
Required. Content of the *.pem file you downloaded from the app’s about page. You can generate a new private key if needed. Make sure to preserve the line breaks.
|
options.now
|
number
|
An optional override for the current time in seconds since the UNIX epoch. Defaults to Math.floor(Date.now() / 1000)). This value can be overridden to account for a time skew between the local machine and the authentication server.
|
githubAppJwt(options) resolves with an object with the following keys
| name | type | description |
|---|---|---|
token
|
string
| The JSON Web Token (JWT) to authenticate as the app. |
appId
|
number
|
The GitHub App database ID passed in options.id.
|
expiration
|
number
|
Timestamp as UNIX epoch, e.g. 1530922170. A Date object can be created using new Date(authentication.expiration).
|
FAQs
Calculate GitHub App bearer tokens for Node & modern browsers
The npm package universal-github-app-jwt receives a total of 864,899 weekly downloads. As such, universal-github-app-jwt popularity was classified as popular.
We found that universal-github-app-jwt demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Product
Socket now supports four distinct alert actions instead of the previous two, and alert triaging allows users to override the actions taken for all individual alerts.
Security News
Polyfill.io has been serving malware for months via its CDN, after the project's open source maintainer sold the service to a company based in China.
Security News
OpenSSF is warning open source maintainers to stay vigilant against reputation farming on GitHub, where users artificially inflate their status by manipulating interactions on closed issues and PRs.