@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 OAuth access tokens in exchange for a code from the web application flow.

• Usage
• createOAuthAppAuth(options)
• auth()
• Authentication object
  • OAuth authentication
  • OAuth access token authentication
• auth.hook(request, route, parameters) or auth.hook(request, options)
• Implementation details
• License

Usage

Browsers	Load @octokit/auth-oauth-app directly from cdn.pika.dev <script type="module"> import { createOAuthAppAuth } from "https://cdn.pika.dev/@octokit/auth-oauth-app"; </script>
Node	Install with npm install @octokit/auth-oauth-app const { createOAuthAppAuth } = require("@octokit/auth-oauth-app"); // or: import { createOAuthAppAuth } from "@octokit/auth-oauth-app";

const auth = createOAuthAppAuth({
  clientId: "123",
  clientSecret: "secret"
});

// OAuth Apps authenticate using ?client_id=...&client_secret=... query parameters
// or Basic auth, depending on the request URL (see implementation details below).
const appAuthentication = await auth({
  type: "oauth-app",
  url: "/orgs/:org/repos"
});
// resolves with
// {
//   type: 'oauth-app',
//   clientId: '123',
//   clientSecret: 'secret',
//   query: {
//     client_id: '123',
//     client_secret: 'secret'
//   }
// }

const tokenAuthentication = await auth({
  type: "token",
  code: "random123", // code from OAuth web flow, see https://git.io/fhd1D
  state: "mystate123"
});
// resolves with
// {
//   type: 'token',
//   tokenType: 'oauth',
//   token: '...', /* the created oauth token */
//   scopes: [] /* depend on request scopes by OAuth app */
// }

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.code	string	The authorization code which was passed as query parameter to the callback URL from the OAuth web application flow.
options.redirectUrl	string	The URL in your application where users are sent after authorization. See redirect urls.
options.state	string	The unguessable random string you provided in Step 1 of the OAuth web application flow.
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
options.type	string	Required. Either "oauth-app" or "token".
options.url	string	Required if options.type set to "oauth-app". 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"
options.code	string	Only relevant if options.type is set to "token". The authorization code which was passed as query parameter to the callback URL from the OAuth web application flow. Defaults to what was set in the strategy options.
options.redirectUrl	string	Only relevant if options.type is set to "token". The URL in your application where users are sent after authorization. See redirect urls. Defaults to what was set in the strategy options.
options.state	string	Only relevant if options.type is set to "token". The unguessable random string you provided in Step 1 of the OAuth web application flow. Defaults to what was set in the strategy options.

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

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 based on the request URL.

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: authorizations } = await auth.hook(
  request,
  "GET /applications/:client_id/tokens/:access_token"
);

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

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

const { data: authorization } = await requestWithAuth(
  "GET /applications/:client_id/tokens/:access_token"
);

Implementation details

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

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 if options.type is set to oauth-app. Additionally, :client_id and :access_token are defaulted to options.clientId passed to createOAuthAppAuth(options) and the token which was created using options.code, if passed.

To reset the current access token, you can do this

await auth.hook(request, "POST /applications/:client_id/tokens/:access_token");

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

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

License

MIT