@octokit/auth-oauth-app

What is @octokit/auth-oauth-app?

@octokit/auth-oauth-app is an npm package that provides authentication strategies for GitHub OAuth Apps. It allows developers to authenticate users, manage tokens, and handle OAuth flows with ease.

What are @octokit/auth-oauth-app's main functionalities?

Authenticate using OAuth App

This feature allows you to authenticate a user using an OAuth App by exchanging an authorization code for an access token.

const { createOAuthAppAuth } = require('@octokit/auth-oauth-app');

const auth = createOAuthAppAuth({
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret'
});

(async () => {
  const { token } = await auth({
    type: 'oauth-user',
    code: 'authorization-code'
  });
  console.log(token);
})();

Check token

This feature allows you to check the validity of an OAuth token by making a request to the GitHub API.

const { createOAuthAppAuth } = require('@octokit/auth-oauth-app');

const auth = createOAuthAppAuth({
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret'
});

(async () => {
  const { token } = await auth({
    type: 'oauth-user',
    code: 'authorization-code'
  });
  const { data } = await auth.hook({
    method: 'GET',
    url: '/applications/:client_id/token',
    headers: {
      authorization: `bearer ${token}`
    },
    client_id: 'your-client-id',
    access_token: token
  });
  console.log(data);
})();

Revoke token

This feature allows you to revoke an OAuth token, effectively logging the user out and invalidating the token.

const { createOAuthAppAuth } = require('@octokit/auth-oauth-app');

const auth = createOAuthAppAuth({
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret'
});

(async () => {
  const { token } = await auth({
    type: 'oauth-user',
    code: 'authorization-code'
  });
  await auth.hook({
    method: 'DELETE',
    url: '/applications/:client_id/token',
    headers: {
      authorization: `bearer ${token}`
    },
    client_id: 'your-client-id',
    access_token: token
  });
  console.log('Token revoked');
})();

Other packages similar to @octokit/auth-oauth-app

passport-github

passport-github is a Passport strategy for authenticating with GitHub using the OAuth 2.0 API. It is similar to @octokit/auth-oauth-app in that it allows for GitHub authentication, but it is designed to be used with the Passport.js middleware for Node.js.

simple-oauth2

simple-oauth2 is a library that provides a simple and consistent way to handle OAuth 2.0 authentication in Node.js. It is more general-purpose compared to @octokit/auth-oauth-app, which is specifically tailored for GitHub OAuth.

client-oauth2

client-oauth2 is a library for handling OAuth 2.0 authentication in client-side and server-side JavaScript applications. It offers a more flexible and low-level approach compared to @octokit/auth-oauth-app, which provides higher-level abstractions for GitHub OAuth.

README

auth-oauth-app.js

GitHub OAuth App authentication for JavaScript

@octokit/auth-oauth-app is implementing one of GitHub’s authentication strategies.

It implements authentication using an OAuth app’s client ID and secret as well as creating user access tokens GitHub's OAuth web application flow and device flow.

• Standalone Usage
  • Authenticate as app
  • Authenticate user using OAuth Web Flow
  • Authenticate user using OAuth Device flow
• Usage with Octokit
• createOAuthAppAuth(options) or new Octokit({ auth })
• auth(options) or octokit.auth(options)
  • Client ID/Client Secret Basic authentication
  • OAuth web flow
  • OAuth device flow
• Authentication object
  • OAuth App authentication
  • OAuth user 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

Browsers	⚠️ @octokit/auth-oauth-app is not meant for usage in the browser. The OAuth APIs to create tokens do not have CORS enabled, and a client secret must not be exposed to the client. If you know what you are doing, load @octokit/auth-oauth-app directly from esm.sh <script type="module"> import { createOAuthAppAuth } from "https://esm.sh/@octokit/auth-oauth-app"; </script>
Node	Install with npm install @octokit/auth-oauth-app import { createOAuthAppAuth } from "@octokit/auth-oauth-app";

[!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

Authenticate as app

const auth = createOAuthAppAuth({
  clientType: "oauth-app",
  clientId: "1234567890abcdef1234",
  clientSecret: "1234567890abcdef1234567890abcdef12345678",
});

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

resolves with

{
  "type": "oauth-app",
  "clientId": "1234567890abcdef1234",
  "clientSecret": "1234567890abcdef1234567890abcdef12345678",
  "headers": {
    "authorization": "basic MTIzNDU2Nzg5MGFiY2RlZjEyMzQ6MTIzNDU2Nzg5MGFiY2RlZjEyMzQ1Njc4OTBhYmNkZWYxMjM0NTY3OA=="
  }
}

Authenticate user using OAuth Web Flow

Exchange code from GitHub's OAuth web flow, see https://docs.github.com/en/developers/apps/authorizing-oauth-apps#2-users-are-redirected-back-to-your-site-by-github

const auth = createOAuthAppAuth({
  clientType: "oauth-app",
  clientId: "1234567890abcdef1234",
  clientSecret: "1234567890abcdef1234567890abcdef12345678",
});

const userAuthenticationFromWebFlow = await auth({
  type: "oauth-user",
  code: "random123",
  state: "mystate123",
});

resolves with

{
  "clientType": "oauth-app",
  "clientId": "1234567890abcdef1234",
  "clientSecret": "1234567890abcdef1234567890abcdef12345678",
  "type": "token",
  "tokenType": "oauth",
  "token": "useraccesstoken123",
  "scopes": []
}

Authenticate user using OAuth Device flow

Pass an asynchronous onVerification() method which will be called with the response from step 1 of the device flow. In that function you have to prompt the user to enter the user code at the provided verification URL.

auth() will not resolve until the user entered the code and granted access to the app.

See https://docs.github.com/en/developers/apps/authorizing-oauth-apps#2-users-are-redirected-back-to-your-site-by-github

const auth = createOAuthAppAuth({
  clientType: "oauth-app",
  clientId: "1234567890abcdef1234",
  clientSecret: "1234567890abcdef1234567890abcdef12345678",
});

const userAuthenticationFromDeviceFlow = await auth({
  async onVerification(verification) {
    // verification example
    // {
    //   device_code: "3584d83530557fdd1f46af8289938c8ef79f9dc5",
    //   user_code: "WDJB-MJHT",
    //   verification_uri: "https://github.com/login/device",
    //   expires_in: 900,
    //   interval: 5,
    // };

    console.log("Open %s", verification.verification_uri);
    console.log("Enter code: %s", verification.user_code);
  },
});

resolves with

{
  "clientType": "oauth-app",
  "clientId": "1234567890abcdef1234",
  "clientSecret": "1234567890abcdef1234567890abcdef12345678",
  "type": "token",
  "tokenType": "oauth",
  "token": "useraccesstoken123",
  "scopes": []
}

Usage with Octokit

Browsers

⚠️ @octokit/auth-oauth-app is not meant for usage in the browser. The OAuth APIs to create tokens do not have CORS enabled, and a client secret must not be exposed to the client. If you know what you are doing, load @octokit/auth-oauth-app and @octokit/core (or a compatible module) directly from esm.sh <script type="module"> import { createOAuthAppAuth } from "https://esm.sh/@octokit/auth-oauth-app"; import { Octokit } from "https://esm.sh/@octokit/core"; </script>

Node

Install with npm install @octokit/core @octokit/auth-oauth-app. Optionally replace @octokit/core with a compatible module import { Octokit } from "@octokit/core"; import { createOAuthAppAuth, createOAuthUserAuth, } from "@octokit/auth-oauth-app";

const appOctokit = new Octokit({
  authStrategy: createOAuthAppAuth,
  auth: {
    clientId: "1234567890abcdef1234",
    clientSecret: "1234567890abcdef1234567890abcdef12345678",
  },
});

// Send requests as 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);

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

The createOAuthAppAuth method accepts a single options object as argument. The same set of options can be passed as auth to the Octokit constructor when setting authStrategy: createOAuthAppAuth

name	type	description
clientId	string	Required. Find your OAuth app’s Client ID in your account’s developer settings.
clientSecret	string	Required. Find your OAuth app’s Client Secret in your account’s developer settings.
clientType	string	Must be set to either "oauth-app" or "github-app". Defaults to "oauth-app"
request	function	You can pass in your own @octokit/request instance. For usage with enterprise, set baseUrl to the API root endpoint. Example: import { request } from "@octokit/request"; createOAuthAppAuth({ clientId: "1234567890abcdef1234", clientSecret: "1234567890abcdef1234567890abcdef12345678", request: request.defaults({ baseUrl: "https://ghe.my-company.com/api/v3", }), });

auth(options) or octokit.auth(options)

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

Client ID/Client Secret Basic authentication

All REST API routes starting with /applications/{client_id} need to be authenticated using the OAuth/GitHub App's Client ID and a client secret.

name	type	description
type	string	Required. Must be set to "oauth-app"

OAuth web flow

Exchange code for a user access token. See Web application flow.

name	type	description
type	string	Required. Must be set to "oauth-user".
code	string	Required. The authorization code which was passed as query parameter to the callback URL from the OAuth web application flow.
redirectUrl	string	The URL in your application where users are sent after authorization. See redirect urls.
state	string	The unguessable random string you provided in Step 1 of the OAuth web application flow.
factory	function	When the factory option is, the auth({type: "oauth-user", code, 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 a user using createOAuthUserAuth which implements auto-refreshing tokens, among other features. You can import createOAuthUserAuth directly from @octokit/auth-oauth-app which will ensure compatibility. import { createOAuthAppAuth, createOAuthUserAuth, } from "@octokit/auth-oauth-app"; const appAuth = createOAuthAppAuth({ clientType: "github-app", clientId: "lv1.1234567890abcdef", clientSecret: "1234567890abcdef1234567890abcdef12345678", }); const userAuth = await appAuth({ type: "oauth-user", code, factory: createOAuthUserAuth, }); // will create token upon first call, then cache authentication for successive calls, // until token needs to be refreshed (if enabled for the GitHub App) const authentication = await userAuth();

OAuth device flow

Create a user access token without an http redirect. See Device flow.

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

name	type	description
type	string	Required. Must be set to "oauth-user".
onVerification	function	Required. A function that is called once the device and user codes were retrieved. The onVerification() callback can be used to pause until the user completes step 2, which might result in a better user experience. const auth = auth({ type: "oauth-user", async onVerification(verification) { console.log("Open %s", verification.verification_uri); console.log("Enter code: %s", verification.user_code); await prompt("press enter when you are ready to continue"); }, });
scopes	array of strings	Only relevant if the clientType strategy option is set to "oauth-app".Array of OAuth scope names that the user access token should be granted. Defaults to no scopes ([]).
factory	function	When the factory option is, the auth({type: "oauth-user", code, 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 a user using createOAuthUserAuth which implements auto-refreshing tokens, among other features. You can import createOAuthUserAuth directly from @octokit/auth-oauth-app which will ensure compatibility. import { createOAuthAppAuth, createOAuthUserAuth, } from "@octokit/auth-oauth-app"; const appAuth = createOAuthAppAuth({ clientType: "github-app", clientId: "lv1.1234567890abcdef", clientSecret: "1234567890abcdef1234567890abcdef12345678", }); const userAuth = await appAuth({ type: "oauth-user", onVerification, factory: createOAuthUserAuth, }); // will create token upon first call, then cache authentication for successive calls, // until token needs to be refreshed (if enabled for the GitHub App) const authentication = await userAuth();

Authentication object

The async auth(options) method to one of four possible authentication objects

1. OAuth App authentication for auth({ type: "oauth-app" })
2. OAuth user access token authentication for auth({ type: "oauth-app" }) and App is an OAuth App (OAuth user access token)
3. GitHub APP user authentication token with expiring disabled for auth({ type: "oauth-app" }) and App is a GitHub App (user-to-server token)
4. GitHub APP user authentication token with expiring enabled for auth({ type: "oauth-app" }) and App is a GitHub App (user-to-server token)

OAuth App authentication

name	type	description
type	string	"oauth-app"
clientType	string	"oauth-app" or "github-app"
clientId	string	The client ID as passed to the constructor.
clientSecret	string	The client secret as passed to the constructor.
headers	object	{ authorization }.

OAuth user access token authentication

name	type	description
type	string	"token"
tokenType	string	"oauth"
clientType	string	"oauth-app"
clientId	string	The clientId from the strategy options
clientSecret	string	The clientSecret from the strategy options
token	string	The user access token
scopes	array of strings	array of scope names enabled for the token

GitHub APP user authentication token with expiring disabled

name	type	description
type	string	"token"
tokenType	string	"oauth"
clientType	string	"github-app"
clientId	string	The app's Client ID
clientSecret	string	One of the app's client secrets
token	string	The user access token

GitHub APP user authentication token with expiring enabled

name	type	description
type	string	"token"
tokenType	string	"oauth"
clientType	string	"github-app"
clientId	string	The app's Client ID
clientSecret	string	One of the app's client secrets
token	string	The user access token
refreshToken	string	The refresh token
expiresAt	string	Date timestamp in ISO 8601 standard. Example: 2022-01-01T08:00:0.000Z
refreshTokenExpiresAt	string	Date timestamp in ISO 8601 standard. Example: 2021-07-01T00:00:0.000Z

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 correctly using clientId and clientSecret as basic auth for the API endpoints that support it. It throws an error in other cases.

The request option is an instance of @octokit/request. The route/options parameters are the same as for the request() method.

auth.hook() can be called directly to send an authenticated request

const { data: user } = await auth.hook(
  request,
  "POST /applications/{client_id}/token",
  {
    client_id: "1234567890abcdef1234",
    access_token: "token123",
  },
);

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

const requestWithAuth = request.defaults({
  request: {
    hook: auth.hook,
  },
});

const { data: user } = await requestWithAuth(
  "POST /applications/{client_id}/token",
  {
    client_id: "1234567890abcdef1234",
    access_token: "token123",
  },
);

Types

import {
  // strategy options
  OAuthAppStrategyOptions,
  GitHubAppStrategyOptions,
  // auth options
  AppAuthOptions,
  WebFlowAuthOptions,
  OAuthAppDeviceFlowAuthOptions,
  GitHubAppDeviceFlowAuthOptions,
  // auth interfaces
  OAuthAppAuthInterface,
  GitHubAuthInterface,
  // authentication object
  AppAuthentication,
  OAuthAppUserAuthentication,
  GitHubAppUserAuthentication,
  GitHubAppUserAuthenticationWithExpiration,
} from "@octokit/auth-oauth-app";

Implementation details

Client ID and secret can be passed as Basic auth in the Authorization header in order to get a higher rate limit compared to unauthenticated requests. This is meant for the use on servers only: never expose an OAuth client secret on a client such as a web application!

auth.hook will set the correct authentication header automatically based on the request URL. For all OAuth Application endpoints, the Authorization header is set to basic auth. For all other endpoints and token is retrieved and used in the Authorization header. The token is cached and used for succeeding requests.

To reset the cached access token, you can do this

const { token } = await auth({ type: "oauth-user" });
await auth.hook(request, "POST /applications/{client_id}/token", {
  client_id: "1234567890abcdef1234",
  access_token: token,
});

The internally cached token will be replaced and used for succeeding requests. See also "the REST API documentation".

See also: octokit/oauth-authorization-url.js.

License

MIT