Learn about our RFC process, Open RFC meetings & more.Join in the discussion! »

@octokit/auth-oauth-app

3.0.5 • Public • Published

auth-oauth-app.js

GitHub OAuth App authentication for JavaScript

@latest Build Status

@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

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 Basic auth, where
// username is clientId and password is clientSecret
const appAuthentication = await auth({
  type: "oauth-app",
});
// resolves with
// {
//   type: 'oauth-app',
//   clientId: '123',
//   clientSecret: 'secret',
//   headers: {
//     authorization: 'basic MTIzOnNlY3JldA=='
//   }
// }
 
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 API root endpoint. Example:
const { request } = require("@octokit/request");
createOAuthAppAuth({
  clientId: 123,
  clientSecret: "secret",
  request: request.defaults({
    baseUrl: "https://ghe.my-company.com/api/v3",
  }),
});

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.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 { authorization }.

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: user } = await auth.hook(request, "GET /user");

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

const requestWithAuth = request.defaults({
  request: {
    hook: auth.hook,
  },
});
 
const { data: user } = await requestWithAuth("GET /user");

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 requsets.

To reset the cached access token, you can do this

const { token } = await auth({ type: "token" });
await auth.hook(request, "POST /applications/:client_id/token", {
  client_id: "123",
  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

Install

npm i @octokit/auth-oauth-app

DownloadsWeekly Downloads

2,744

Version

3.0.5

License

MIT

Unpacked Size

58.4 kB

Total Files

21

Last publish

Collaborators

  • avatar
  • avatar
  • avatar