oauth-app.js

GitHub OAuth toolset for Node.js

Table of contents

Usage
Examples
Constructor options
app.on(eventName, eventHandler)
app.octokit
app.getAuthorizationUrl(options)
app.createToken(options)
app.checkToken(options)
app.resetToken(options)
app.deleteToken(options)
app.deleteAuthorization(options)
Stateless methods
Middlewares
- getNodeMiddleware(app, options)
Contributing
License

Usage

Browsers

@octokit/oauth-app is not meant for browser usage.

Node

Install with npm install @octokit/core @octokit/oauth-app

const { OAuthApp, getNodeMiddleware } = require("@octokit/oauth-app");

const app = new OAuthApp({
  clientId: "0123",
  clientSecret: "0123secret",
});

app.on("token", async ({ token, octokit }) => {
  const { data } = await octokit.request("GET /user");
  console.log(`Token retrieved for ${data.login}`);
});

require("http").createServer(getNodeMiddleware(app)).listen(3000);
// can now receive user authorization callbacks at /api/github/oauth/callback

Examples

Node server with static files served from public/ folder, hosted on Glitch: https://glitch.com/~github-oauth-client
Serverless functions, hosted on Zeit's now: https://github.com/gr2m/octokit-oauth-app-now-example
Serverless functions, hosted on AWS (via begin.com): https://github.com/gr2m/octokit-oauth-app-begin-example/

Constructor options

name	type	description
`clientId`	`number`	Required. Find Client ID on the app’s about page in settings.
`clientSecret`	`number`	Required. Find Client Secret on the app’s about page in settings.
`allowSignup`	`boolean`	Sets the default value for `app.getAuthorizationUrl(options)`.
`defaultScopes`	`Array of strings`	Sets the default `scopes` value for `app.getAuthorizationUrl(options)`. See available scopes
`log`	`object`	Used for internal logging. Defaults to `console`.
`Octokit`	`Constructor`	You can pass in your own Octokit constructor with custom defaults and plugins. The Octokit Constructor must accept `options.auth` to be set to an OAuth access token string, such as `@octokit/auth-token` does. For usage with enterprise, set `baseUrl` to the hostname + `/api/v3`. Example: const { Octokit } = require("@octokit/core"); new OAuthApp({ clientId: 123, clientSecret: "secret", Octokit: Octokit.defaults({ baseUrl: "https://ghe.my-company.com/api/v3", }), }); Defaults to `@octokit/core`.

`app.on(eventName, eventHandler)`

Called whenever a new OAuth access token is created for a user. It accepts two parameters, an event name and a function with one argument

app.on("token.created", async (context) => {
  const { data } = await context.octokit.request("GET /user");
  app.log.info(`New token created for ${data.login}`);
});

The eventName can be one of (or an array of)

token.created
token.reset
token.deleted
token.before_deleted
authorization.before_deleted
authorization.deleted

All event handlers are awaited before continuing.

context can have the following properties

property	type	description
`context.name`	`string`	Name of the event. One of: `token`, `authorization`
`context.action`	`string`	Action of the event. One of: `created`, `reset`, `deleted`, `before_deleted`
`context.token`	`string`	The OAuth access token.
`context.octokit`	`Octokit instance`	Authenticated instance using the `Octokit` option passed to the constructor. Not set for `"token.deleted"` and `"authorization.deleted"` events.
`scopes`	`Array of strings`	An array of scopes the `context.token` has access to. Not set for `"token.before_deleted"`, `"token.deleted"`, `"authorization.before_deleted"`, and `"authorization.deleted"` events.

`app.octokit`

Octokit instance with OAuth App authentication. Uses Octokit constructor option

`app.getAuthorizationUrl(options)`

Returns a URL string.

const url = app.getAuthorizationUrl({
  state: "state123",
  scopes: ["repo"],
});

name	type	description
`redirectUrl`	`string`	The URL in your application where users will be sent after authorization. See Redirect URLs in GitHub’s Developer Guide.
`login`	`string`	Suggests a specific account to use for signing in and authorizing the app.
`scopes`	`array of strings`	An array of scope names (or: space-delimited list of scopes). If not provided, scope defaults to an empty list for users that have not authorized any scopes for the application. For users who have authorized scopes for the application, the user won't be shown the OAuth authorization page with the list of scopes. Instead, this step of the flow will automatically complete with the set of scopes the user has authorized for the application. For example, if a user has already performed the web flow twice and has authorized one token with user scope and another token with repo scope, a third web flow that does not provide a scope will receive a token with user and repo scope.
`state`	`string`	An unguessable random string. It is used to protect against cross-site request forgery attacks. Defaults to `Math.random().toString(36).substr(2)`.
`allowSignup`	`boolean`	Whether or not unauthenticated users will be offered an option to sign up for GitHub during the OAuth flow. The default is `true`. Use `false` in the case that a policy prohibits signups.

`app.createToken(options)`

const { token, scopes } = await app.createToken({
  state: "state123",
  code: "code123",
});

name	type	description
`code`	`string`	Required. Pass the code that was passed as `?code` query parameter in the authorization redirect URL.
`state`	`string`	Required. Pass the state that was passed as `?state` query parameter in the authorization redirect URL.

Resolves with result

name	type	description
`result.token`	`string`	The OAuth access token
`result.scopes`	`array of strings`	The names of the scopes the token has access to

`app.checkToken(options)`

try {
  const { created_at, app, user } = await app.checkToken({ token });
  console.log(
    `token valid, created on %s by %s for %s`,
    created_at,
    user.login,
    app.name
  );
} catch (error) {
  // token invalid or request error
}

name	type	description
`token`	`string`	Required.

Resolves with response body from "Check a token" request.

`app.resetToken(options)`

const { token } = await app.resetToken({
  token: "token123",
});
// "token123" is no longer valid. Use `token` instead

name	type	description
`token`	`string`	Required.

Resolves with response body from "Reset a token" request.

`app.deleteToken(options)`

await app.deleteToken({
  token: "token123",
});
// "token123" is no longer valid.

name	type	description
`token`	`string`	Required.

Resolves with response body from "Delete a token" request.

`app.deleteAuthorization(options)`

await app.deleteAuthorization({
  token: "token123",
});
// "token123" is no longer valid, and no tokens can be created until the app gets re-authorized.

name	type	description
`token`	`string`	Required.

Resolves with response body from "Delete an app authorization" request.

Stateless methods

Each method can be loaded separately to minimize the payload. That is particularly useful for serverless environment, as the payload will be the smallest possible.

const {
  getAuthorizationUrl,
  createToken,
  checkToken,
  resetToken,
  deleteToken,
  deleteAuthorization,
} = require("@octokit/oauth-app");

`getAuthorizationUrl(options)`

Returns a URL string.

const { getAuthorizationUrl } = require("@octokit/oauth-app");
const url = getAuthorizationUrl({
  clientId: "0123",
  state: "state123",
});

name	type	description
`clientId`	`string`	Required. The client ID you received from GitHub when you registered.
`state`	`string`	Required. An unguessable random string. It is used to protect against cross-site request forgery attacks. Defaults to `Math.random().toString(36).substr(2)`.
`redirectUrl`	`string`	The URL in your application where users will be sent after authorization. See Redirect URLs in GitHub’s Developer Guide.
`login`	`string`	Suggests a specific account to use for signing in and authorizing the app.
`scopes`	`array of strings`	An array of scope names (or: space-delimited list of scopes). If not provided, scope defaults to an empty list for users that have not authorized any scopes for the application. For users who have authorized scopes for the application, the user won't be shown the OAuth authorization page with the list of scopes. Instead, this step of the flow will automatically complete with the set of scopes the user has authorized for the application. For example, if a user has already performed the web flow twice and has authorized one token with user scope and another token with repo scope, a third web flow that does not provide a scope will receive a token with user and repo scope.
`allowSignup`	`boolean`	Whether or not unauthenticated users will be offered an option to sign up for GitHub during the OAuth flow. The default is `true`. Use `false` in the case that a policy prohibits signups.
`log`	`object`	When invalid options are passed, warnings are logged using `log.warn(message)`. Defaults to `console`.
`baseUrl`	`string`	When using GitHub Enterprise Server, set the baseUrl to the origin, e.g. `https://github.my-enterprise.com/`.

`createToken(options)`

const { createToken } = require("@octokit/oauth-app");
const { token, scopes } = await createToken({
  clientId: "0123",
  clientSecret: "0123secret",
  state: "state123",
  code: "code123",
});

name	type	description
`clientId`	`number`	Required. Find Client ID on the app’s about page in settings.
`clientSecret`	`number`	Required. Find Client Secret on the app’s about page in settings.
`code`	`string`	Required. Pass the code that was passed in the `?code` query parameter in the authorization redirect URL.
`state`	`string`	Required. Pass the state that was passed in the `?state` query parameter in the authorization redirect URL.

Resolves with result

name	type	description
`result.token`	`string`	The OAuth access token
`result.scopes`	`array of strings`	The names of the scopes the token has access to

`checkToken(options)`

const { checkToken } = require("@octokit/oauth-app");
try {
  const { created_at, app, user } = await checkToken({
    clientId: "0123",
    clientSecret: "0123secret",
    token: "token123",
  });
  console.log(
    `token valid, created on %s by %s for %s`,
    created_at,
    user.login,
    app.name
  );
} catch (error) {
  // token invalid or request error
}

name	type	description
`clientId`	`number`	Required. Find Client ID on the app’s about page in settings.
`clientSecret`	`number`	Required. Find Client Secret on the app’s about page in settings.
`token`	`string`	Required.

Resolves with response body from "Check a token" request.

`resetToken(options)`

const { resetToken } = require("@octokit/oauth-app");
const { token } = await resetToken({
  clientId: "0123",
  clientSecret: "0123secret",
  token: "token123",
});
// "token123" is no longer valid. Use `token` instead

name	type	description
`clientId`	`number`	Required. Find Client ID on the app’s about page in settings.
`clientSecret`	`number`	Required. Find Client Secret on the app’s about page in settings.
`token`	`string`	Required.

Resolves with response body from "Reset a token" request.

`deleteToken(options)`

const { deleteToken } = require("@octokit/oauth-app");
await deleteToken({
  clientId: "0123",
  clientSecret: "0123secret",
  token: "token123",
});
// "token123" is no longer valid

name	type	description
`clientId`	`number`	Required. Find Client ID on the app’s about page in settings.
`clientSecret`	`number`	Required. Find Client Secret on the app’s about page in settings.
`token`	`string`	Required.

Resolves with response body from "Delete a token" request.

`deleteAuthorization(options)`

const { deleteAuthorization } = require("@octokit/oauth-app");
await deleteAuthorization({
  clientId: "0123",
  clientSecret: "0123secret",
  token: "token123",
});
// "token123" is no longer valid

name	type	description
`clientId`	`number`	Required. Find Client ID on the app’s about page in settings.
`clientSecret`	`number`	Required. Find Client Secret on the app’s about page in settings.
`token`	`string`	Required.

Resolves with response body from "Delete an app authorization" request.

Middlewares

A middle ware is a method or set of methods to handle requests for common environments.

By default, all middlewares exposes the following routes

Route	Route Description
`GET /api/github/oauth/login`	Redirects to GitHub's authorization endpoint. Accepts optional `?state` and `?scopes` query parameters. `?scopes` is a comma-separated list of supported OAuth scope names
`GET /api/github/oauth/callback`	The client's redirect endpoint. This is where the `token` event gets triggered
`POST /api/github/oauth/token`	Exchange an authorization code for an OAuth Access token. If successful, the `token` event gets triggered.
`GET /api/github/oauth/token`	Check if token is valid. Must authenticate using token in `Authorization` header. Uses GitHub's `POST /applications/:client_id/token` endpoint
`PATCH /api/github/oauth/token`	Resets a token (invalidates current one, returns new token). Must authenticate using token in `Authorization` header. Uses GitHub's `PATCH /applications/:client_id/token` endpoint.
`DELETE /api/github/oauth/token`	Invalidates current token, basically the equivalent of a logout. Must authenticate using token in `Authorization` header.
`DELETE /api/github/oauth/grant`	Revokes the user's grant, basically the equivalent of an uninstall. must authenticate using token in `Authorization` header.

`getNodeMiddleware(app, options)`

Native http server middleware for Node.js

const { OAuthApp, getNodeMiddleware } = require("@octokit/oauth-app");
const app = new OAuthApp({
  clientId: "0123",
  clientSecret: "0123secret",
});

const middleware = getNodeMiddleware(app, {
  pathPrefix: "/api/github/oauth/",
});

require("http").createServer(middleware).listen(3000);
// can now receive user authorization callbacks at /api/github/oauth/callback

name	type	description
`app`	`OAuthApp instance`	Required.
`options.pathPrefix`	`string`	All exposed paths will be prefixed with the provided prefix. Defaults to `"/api/github/oauth"`
`options.onUnhandledRequest`	`function`	Defaults to function onUnhandledRequest(request, response) { response.writeHead(400, { "content-type": "application/json", }); response.end( JSON.stringify({ error: error.message, }) ); }

Contributing

See CONTRIBUTING.md

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 79 Commits
.github		.github
src		src
test		test
.gitignore		.gitignore
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

oauth-app.js

Usage

Examples

Constructor options

`app.on(eventName, eventHandler)`

`app.octokit`

`app.getAuthorizationUrl(options)`

`app.createToken(options)`

`app.checkToken(options)`

`app.resetToken(options)`

`app.deleteToken(options)`

`app.deleteAuthorization(options)`

Stateless methods

`getAuthorizationUrl(options)`

`createToken(options)`

`checkToken(options)`

`resetToken(options)`

`deleteToken(options)`

`deleteAuthorization(options)`

Middlewares

`getNodeMiddleware(app, options)`

Contributing

License

About

Releases

Packages

Languages

License

topher2469/oauth-app.js

Folders and files

Latest commit

History

Repository files navigation

oauth-app.js

Usage

Examples

Constructor options

app.on(eventName, eventHandler)

app.octokit

app.getAuthorizationUrl(options)

app.createToken(options)

app.checkToken(options)

app.resetToken(options)

app.deleteToken(options)

app.deleteAuthorization(options)

Stateless methods

getAuthorizationUrl(options)

createToken(options)

checkToken(options)

resetToken(options)

deleteToken(options)

deleteAuthorization(options)

Middlewares

getNodeMiddleware(app, options)

Contributing

License

About

Resources

License

Code of conduct

Stars

Watchers

Forks

Releases

Packages 0

Languages

`app.on(eventName, eventHandler)`

`app.octokit`

`app.getAuthorizationUrl(options)`

`app.createToken(options)`

`app.checkToken(options)`

`app.resetToken(options)`

`app.deleteToken(options)`

`app.deleteAuthorization(options)`

`getAuthorizationUrl(options)`

`createToken(options)`

`checkToken(options)`

`resetToken(options)`

`deleteToken(options)`

`deleteAuthorization(options)`

`getNodeMiddleware(app, options)`

Packages