@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

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. This is meant for the use on servers only: never expose an OAuth client secret on a client such as a web application!

Client ID and secret can be passed as URL query parameters (?client_id=...&client_secret=...) to get a higher rate limit compared to unauthenticated requests.

The only exceptions are

• GET /applications/:client_id/tokens/:access_token - Check an authorization
• POST /applications/:client_id/tokens/:access_token - Reset an authorization
• DELETE /applications/:client_id/tokens/:access_token - Revoke an authorization for an application

For these endpoints, client ID and secret need to be passed as basic authentication in the Authorization header. Because of these exception an options.url parameter must be passed to the async auth() function.

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

Usage

import { createOAuthAppAuth } from "@octokit/auth-oauth-app";
import { request } from "@octokit/request";

(async () => {
  const auth = createOAuthAppAuth({
    clientId,
    clientSecret
  });

  // Request private repos for "octokit" org using client ID/secret authentication
  const appAuthentication = await auth({ url: "/orgs/:org/repos" });
  const result = await request("GET /orgs/:org/repos", {
    org: "octokit",
    type: "private",
    headers: appAuthentication.headers,
    ...appAuthentication.query
  });

  // Request private repos for "octokit" org using OAuth token authentication
  // "random123" is the authorization code from the web application flow, see below
  const tokenAuthentication = await auth({ code: "random123" });
  const result = await request("GET /orgs/:org/repos", {
    org: "octokit",
    type: "private",
    headers: tokenAuthentication.headers
  });
})();

createOAuthAppAuth(options)

The createOAuthAppAuth method accepts a single parameter with two keys

name	type	description
options.clientId	string	Required. Find your OAuth app’s Client ID in your account’s developer settings.
options.clientSecret	string	Required. Find your OAuth app’s Client Secret in your account’s developer settings.
options.request	function	You can pass in your own @octokit/request instance. For usage with enterprise, set baseUrl to the hostname. Example: const { request } = require("@octokit/request"); createOAuthAppAuth({ clientId: 123, clientSecret: "secret", request: request.defaults({ baseUrl: "https://ghe.my-company.com" }) });

auth()

The async auth() method returned by createOAuthAppAuth(options) accepts the following options

name	type	description
url	string	An absolute URL or endpoint route path. Examples: "https://enterprise.github.com/api/v3/applications/1234567890abcdef1234/tokens/secret123" "/applications/1234567890abcdef1234/tokens/secret123" "/applications/:client_id/tokens/:access_token"
code	string	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.

Authentication object

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

1. OAuth authentication if clientId and clientSecret options were passed.
2. OAuth access token authentication if code option was passed.

OAuth authentication

name	type	description
type	string	"oauth-app"
clientId	string	The client ID as passed to the constructor.
clientSecret	string	The client secret as passed to the constructor.
headers	object	{} if no url option was passed or the passed url option does not match /applications/:client_id/tokens/:access_token. { authorization } if the passed url option does match /applications/:client_id/tokens/:access_token.
query	object	{ client_id, client_secret } if no url option was passed or the passed url option does not match /applications/:client_id/tokens/:access_token. {} if the passed url option does match /applications/:client_id/tokens/:access_token.

OAuth access token authentication

name	type	description
type	string	"token"
token	string	The personal access token
tokenType	string	"oauth"
scopes	array of strings	array of scope names enabled for the token
headers	object	{ authorization } - value for the "Authorization" header
query	object	{} - not used

License

MIT