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