auth-app.js

> GitHub App authentication for JavaScript


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

- Standalone usage
- Authenticate as GitHub App (JSON Web Token)
- Authenticate as OAuth App (client ID/client secret)
- Authenticate as installation
- Authenticate as user
- Usage with Octokit
- createAppAuth(options) or new Octokit({ auth })
- auth(options) or octokit.auth(options)
- JSON Web Token (JWT) Authentication
- OAuth App authentication
- Installation authentication
- User authentication (web flow)
- User authentication (device flow)
- Authentication object
- JSON Web Token (JWT) authentication
- OAuth App authentication
- Installation access token authentication
- GitHub APP user authentication token with expiring disabled
- GitHub APP user authentication token with expiring enabled
- auth.hook(request, route, parameters) or auth.hook(request, options)
- Types
- Implementation details
- License

Standalone usage

> [!IMPORTANT]
> As we use conditional exports, you will need to adapt your tsconfig.json by setting "moduleResolution": "node16", "module": "node16".
>
> See the TypeScript docs on package.json "exports".

> See this helpful guide on transitioning to ESM from @sindresorhus

$3

`js
const auth = createAppAuth({
appId: 1,
privateKey: "-----BEGIN PRIVATE KEY-----\n...",
clientId: "lv1.1234567890abcdef",
clientSecret: "1234567890abcdef12341234567890abcdef1234",
});

// Retrieve JSON Web Token (JWT) to authenticate as app
const appAuthentication = await auth({ type: "app" });
`

resolves with

`json
{
"type": "app",
"token": "jsonwebtoken123",
"appId": 123,
"expiresAt": "2018-07-07T00:09:30.000Z"
}
`

$3

If your app's private key is stored in a key management service or hardware security
module, you can use the createJwt option instead of a private key to remotely sign a
JWT. You provide an async callback to perform the token signing.

`js
const auth = createAppAuth({
appId: 1,
createJwt: async (clientId, timeDifference) => {
// ... sign the JWT remotely
// universal-github-app-jwt accounts for clock skew by issuing at -30s from now
// if a timeDifference is present, add that to the seconds
return { jwt, expiresAt };
}
clientId: "lv1.1234567890abcdef",
clientSecret: "1234567890abcdef12341234567890abcdef1234",
});

// Retrieve JSON Web Token (JWT) to authenticate as app
const appAuthentication = await auth({ type: "app" });
`

resolves with

`json
{
"type": "app",
"token": "jsonwebtoken123",
"appId": 123,
"expiresAt": "2018-07-07T00:09:30.000Z"
}
`

$3

The OAuth Application APIs require the app to authenticate using clientID/client as Basic Authentication

`js
const auth = createAppAuth({
appId: 1,
privateKey: "-----BEGIN PRIVATE KEY-----\n...",
clientId: "lv1.1234567890abcdef",
clientSecret: "1234567890abcdef12341234567890abcdef1234",
});

const appAuthentication = await auth({
type: "oauth-app",
});
`

resolves with

`json
{
"type": "oauth-app",
"clientId": "lv1.1234567890abcdef",
"clientSecret": "1234567890abcdef1234567890abcdef12345678",
"headers": {
"authorization": "basic bHYxLjEyMzQ1Njc4OTBhYmNkZWY6MTIzNDU2Nzg5MGFiY2RlZjEyMzQ1Njc4OTBhYmNkZWYxMjM0NTY3OA=="
}
}
`

$3

`js
const auth = createAppAuth({
appId: 1,
privateKey: "-----BEGIN PRIVATE KEY-----\n...",
clientId: "lv1.1234567890abcdef",
clientSecret: "1234567890abcdef12341234567890abcdef1234",
});

// Retrieve installation access token
const installationAuthentication = await auth({
type: "installation",
installationId: 123,
});
`

resolves with

`json
{
"type": "token",
"tokenType": "installation",
"token": "token123",
"installationId": 123,
"createdAt": "2018-07-07T00:00:00.000Z",
"expiresAt": "2018-07-07T00:59:00.000Z"
}
`

$3

`js
const auth = createAppAuth({
appId: 1,
privateKey: "-----BEGIN PRIVATE KEY-----\n...",
clientId: "lv1.1234567890abcdef",
clientSecret: "1234567890abcdef12341234567890abcdef1234",
});

// Retrieve an oauth-access token
const userAuthentication = await auth({ type: "oauth-user", code: "123456" });
`

Resolves with

`json
{
"type": "token",
"tokenType": "oauth",
"token": "token123"
}
`

Usage with Octokit

`js
const appOctokit = new Octokit({
authStrategy: createAppAuth,
auth: {
appId: 1,
privateKey: "-----BEGIN PRIVATE KEY-----\n...",
clientId: "1234567890abcdef1234",
clientSecret: "1234567890abcdef1234567890abcdef12345678",
},
});

// Send requests as GitHub App
const { slug } = await appOctokit.request("GET /app");
console.log("authenticated as %s", slug);

// Send requests as OAuth App
await appOctokit.request("POST /application/{client_id}/token", {
client_id: "1234567890abcdef1234",
access_token: "existingtoken123",
});
console.log("token is valid");

// create a new octokit instance that is authenticated as the user
const userOctokit = await appOctokit.auth({
type: "oauth-user",
code: "code123",
factory: (options) => {
return new Octokit({
authStrategy: createOAuthUserAuth,
auth: options,
});
},
});

// Exchanges the code for the user access token authentication on first request
// and caches the authentication for successive requests
const {
data: { login },
} = await userOctokit.request("GET /user");
console.log("Hello, %s!", login);
`

In order to create an octokit instance that is authenticated as an installation, with automated installation token refresh, set installationId as auth option

`js
const installationOctokit = new Octokit({
authStrategy: createAppAuth,
auth: {
appId: 1,
privateKey: "-----BEGIN PRIVATE KEY-----\n...",
installationId: 123,
},
});

// transparently creates an installation access token the first time it is needed
// and refreshes it when it expires
await installationOctokit.request("POST /repos/{owner}/{repo}/issues", {
owner: "octocat",
repo: "hello-world",
title: "title",
});
`

createAppAuth(options) or new Octokit({ auth })

auth(options) or octokit.auth(options)

The async auth() method accepts different options depending on your use case

$3

Authenticate as the GitHub app to list installations, repositories, and create installation access tokens.

$3

Create, reset, refresh, delete OAuth user-to-server tokens

$3

$3

Exchange code received from the web flow redirect described in step 2 of GitHub's OAuth web flow

$3

Create a token using GitHub's device flow.

The device flow does not require a client secret, but it is required as strategy option for @octokit/auth-app, even for the device flow. If you want to implement the device flow without requiring a client secret, use @octokit/auth-oauth-device.

Authentication object

Depending on on the auth() call, the resulting authentication object can be one of

1. JSON Web Token (JWT) authentication
1. OAuth App authentication
1. Installation access token authentication
1. GitHub APP user authentication token with expiring disabled
1. GitHub APP user authentication token with expiring enabled

$3

$3

$3

$3

$3

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. Although the "machine-man" preview has graduated to the official API, https://developer.github.com/changes/2020-08-20-graduate-machine-man-and-sailor-v-previews/, it is still required in versions of GitHub Enterprise up to 2.21 so it automatically sets the "machine-man" preview 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

`js
const { data: installations } = await auth.hook(
request,
"GET /app/installations",
);
`

Or it can be passed as option to request().

`js
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:

`js
const { token } = await auth({
type: "oauth-user",
code: "123456",
});
const requestWithAuth = request.defaults({
headers: {
authentication: token ${token},
},
});
`

Types

`ts
import {
// strategy options
StrategyOptions,
// auth options
AuthOptions,
AppAuthOptions,
OAuthAppAuthOptions,
InstallationAuthOptions,
OAuthWebFlowAuthOptions,
OAuthDeviceFlowAuthOptions,
// authentication objects
Authentication,
AppAuthentication,
OAuthAppAuthentication,
InstallationAccessTokenAuthentication,
GitHubAppUserAuthentication,
GitHubAppUserAuthenticationWithExpiration,
} from "@octokit/auth-app";
``

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.

All OAuth features are implemented internally using @octokit/auth-oauth-app.

License

MIT