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
  • JSON Web Token (JWT) authentication
  • Installation access token authentication
  • OAuth access token authentication
• auth.hook(request, route, parameters) or auth.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

1. JSON Web Token (JWT) authentication
2. Installation access token authentication
3. 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.

License

MIT