1.3.1.2 OctoKit Auth-App Authentication Strategies

"GitHub App authentication for JavaScript"

• https://github.com/octokit/auth-app.js

@octokit/auth-app implements authentication for GitHub Apps using JSON Web Token and installation access tokens.

In the browser, load @octokit/auth-app directly from cdn.skypack.dev

<script type="module">import { createAppAuth } from "https://cdn.skypack.dev/@octokit/auth-app";</script>

NOTE

For usage in browsers: The private keys provided by GitHub are in ‘PKCS#1format’, 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.

Using Node.js install with

npm install @octokit/auth-app
const { createAppAuth } = require("@octokit/auth-app");
// or:
import { createAppAuth } from "@octokit/auth-app";

1. CreateAppAuth Options

   appId

   (number) Required

   privateKey

   (string) Required

   installationId

   (number)

   clientId

   (string)

   clientSecret

   (string)

   request

   (function)

   cache

   (object)

   log

   (object)

2. Auth Options

   type

   (string) Required Must be either

   • "app",
   • "installation", or
   • "oauth"

   installationId

   (number) Required if ‘type’ is set to "installation"

   repositoryIds

   permissions

   factory

   refresh

   code

   (string) relevant if type is set to "oauth";

   The authorization code which was passed as ‘query’ parameter to the callback URL from the OAuth web application flow.

   redirectUrl

   (string) relevant if type is set to "oauth".

   The URL in your application where users are sent after authorization. See redirect urls.

   state

   (string) relevant if type is set to "oauth".

   The unguessable random string you provided in Step 1 of the OAuth web application flow.

3. Authentication Object

   There are three possible results:

   1. JSON Web Token (JWT) authentication

      type

      (string) "app"

      token

      (string) The JSON Web Token (JWT) to authenticate as the app.

      appId

      (number) GitHub App database ID.

      expiresAt

      (string) Timestamp in UTC format

      A ‘Date’ object can be created using new Date(authentication.expiresAt).

   2. Installation access token authentication

      type

      token

      tokenType

      installationId

      createdAt

      expiresAt

      repositoryIds

      permissions

      singleFileName

   3. OAuth access token authentication

      type

      (string) "token"

      token

      (string) The personal access token

      tokenType

      "oauth"

      scopes

      array of scope names enabled for the token

4. Example Code

   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: []
   // }
   

5. Auth Hook

   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.

   auth.hook(request, route, parameters)
   auth.hook(request, options)
   

   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}`,
     },
   });