@mgga/auth-app v2.10.6
auth-app.js
GitHub App authentication for JavaScript
@octokit/auth-app
implements authentication for GitHub Apps using JSON Web Token and installation access tokens.
For other GitHub authentication strategies see octokit/auth.js.
- Usage
createAppAuth(options)
auth(options)
- Authentication object
auth.hook(request, route, parameters)
orauth.hook(request, options)
- Implementation details
- License
Usage
Load @octokit/auth-app
directly from cdn.skypack.dev
<script type="module">
import { createAppAuth } from "https://cdn.skypack.dev/@octokit/auth-app";
</script>
Install with npm install @octokit/auth-app
const { createAppAuth } = require("@octokit/auth-app");
// or: import { createAppAuth } from "@octokit/auth-app";
⚠️ For usage in browsers: The private keys provided by GitHub are in PKCS#1
format, but the WebCrypto API only supports PKCS#8
. You need to convert it first:
openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt -in private-key.pem -out private-key-pkcs8.key
No conversation is needed in Node, both PKCS#1
and PKCS#8
format will work.
const auth = createAppAuth({
appId: 1,
privateKey: "-----BEGIN PRIVATE KEY-----\n...",
installationId: 123,
clientId: "1234567890abcdef1234",
clientSecret: "1234567890abcdef12341234567890abcdef1234",
});
// Retrieve JSON Web Token (JWT) to authenticate as app
const appAuthentication = await auth({ type: "app" });
// resolves with
// {
// type: 'app',
// token: 'jsonwebtoken123',
// appId: 123,
// expiresAt: '2018-07-07T00:09:30.000Z'
// }
// Retrieve installation access token
const installationAuthentication = await auth({ type: "installation" });
// resolves with
// {
// type: 'token',
// tokenType: 'installation',
// token: 'token123',
// installationId: 123,
// createdAt: '2018-07-07T00:00:00.000Z'
// expiresAt: '2018-07-07T00:59:00.000Z'
// }
// Retrieve an oauth-access token
const oauthAuthentication = await auth({ type: "oauth", code: "123456" });
// resolves with
// {
// type: 'token',
// tokenType: 'oauth',
// token: 'token123',
// scopes: []
// }
createAppAuth(options)
const { request } = require("@octokit/request");
createAppAuth({
appId: 1,
privateKey: "-----BEGIN PRIVATE KEY-----\n...",
request: request.defaults({
baseUrl: "https://ghe.my-company.com/api/v3",
}),
});
const CACHE = {};
createAppAuth({
appId: 1,
privateKey: "-----BEGIN PRIVATE KEY-----\n...",
cache: {
async get(key) {
return CACHE[key];
},
async set(key, value) {
CACHE[key] = value;
},
},
});
createAppAuth({
appId: 1,
privateKey: "-----BEGIN PRIVATE KEY-----\n...",
log: require("console-log-level")({ level: "info" }),
});
auth(options)
When the factory
option is, the auth({type: "installation", installationId, factory })
call with resolve with whatever the factory function returns. The factory
function will be called with all the strategy option that auth
was created with, plus the additional options passed to auth
, besides type
and factory
.
For example, you can create a new auth
instance for an installation which shares the internal state (especially the access token cache) with the calling auth
instance:
const appAuth = createAppAuth({
appId: 1,
privateKey: "-----BEGIN PRIVATE KEY-----\n...",
});
const installationAuth123 = await appAuth({
type: "installation",
installationId: 123,
factory: createAppAuth,
});
Authentication object
There are three possible results
- JSON Web Token (JWT) authentication
- Installation access token authentication
- OAuth access token authentication
JSON Web Token (JWT) authentication
Installation access token authentication
OAuth access token authentication
auth.hook(request, route, parameters)
or auth.hook(request, options)
auth.hook()
hooks directly into the request life cycle. It amends the request to authenticate either as app or as installation based on the request URL. It also automatically sets the "machine-man"
preview which is currently required for all endpoints requiring JWT authentication.
The request
option is an instance of @octokit/request
. The arguments are the same as for the request()
method.
auth.hook()
can be called directly to send an authenticated request
const { data: installations } = await auth.hook(
request,
"GET /app/installations"
);
Or it can be passed as option to request()
.
const requestWithAuth = request.defaults({
request: {
hook: auth.hook,
},
});
const { data: installations } = await requestWithAuth("GET /app/installations");
Note that auth.hook()
does not create and set an OAuth authentication token. But you can use @octokit/auth-oauth-app
for that functionality. And if you don't plan on sending requests to routes that require authentication with client_id
and client_secret
, you can just retrieve the token and then create a new instance of request()
with the authentication header set:
const { token } = await auth({
type: "oauth",
code: "123456",
});
const requestWithAuth = request.defaults({
headers: {
authentication: `token ${token}`,
},
});
Implementation details
When creating a JSON Web Token, it sets the "issued at time" (iat) to 30s in the past as we have seen people running situations where the GitHub API claimed the iat would be in future. It turned out the clocks on the different machine were not in sync.
Installation access tokens are valid for 60 minutes. This library invalidates them after 59 minutes to account for request delays.