auth-oauth-user.js

Octokit authentication strategy for OAuth user authentication

Important: @octokit/auth-oauth-user requires your app's client_secret, which must not be exposed. If you are looking for an OAuth user authentication strategy that can be used on a client (browser, IoT, CLI), check out @octokit/auth-oauth-user-client. Note that @octokit/auth-oauth-user-client requires a backend. The only exception is @octokit/auth-oauth-device which does not require the client_secret, but does not work in browsers due to CORS constraints.

Features

• Code for token exchange from GitHub's OAuth web flow
• GitHub's OAuth device flow
• Caches token for succesive calls
• Auto-refreshing for expiring user access tokens
• Applies the correct authentication strategy based on the request URL when using with Octokit
• Token verification
• Token reset
• Token invalidation
• Application grant revocation

Standalone usage

1<script type="module">
2  import { createOAuthUserAuth } from "https://esm.sh/@octokit/auth-oauth-user";
3</script>

1import { createOAuthUserAuth } from "@octokit/auth-oauth-user";

Exchange code from OAuth web flow

1const auth = createOAuthUserAuth({
2  clientId: "1234567890abcdef1234",
3  clientSecret: "1234567890abcdef1234567890abcdef12345678",
4  code: "code123",
5  // optional
6  state: "state123",
7  redirectUrl: "https://acme-inc.com/login",
8});
9
10// Exchanges the code for the user access token authentication on first call
11// and caches the authentication for successive calls
12const { token } = await auth();

About GitHub's OAuth web flow

OAuth Device flow

1const auth = createOAuthUserAuth({
2  clientId: "1234567890abcdef1234",
3  clientSecret: "1234567890abcdef1234567890abcdef12345678",
4  onVerification(verification) {
5    // verification example
6    // {
7    //   device_code: "3584d83530557fdd1f46af8289938c8ef79f9dc5",
8    //   user_code: "WDJB-MJHT",
9    //   verification_uri: "https://github.com/login/device",
10    //   expires_in: 900,
11    //   interval: 5,
12    // };
13
14    console.log("Open %s", verification.verification_uri);
15    console.log("Enter code: %s", verification.user_code);
16  },
17});
18
19// resolves once the user entered the `user_code` on `verification_uri`
20const { token } = await auth();

About GitHub's OAuth device flow

Use an existing authentication

1const auth = createOAuthUserAuth({
2  clientId: "1234567890abcdef1234",
3  clientSecret: "1234567890abcdef1234567890abcdef12345678",
4  clientType: "oauth-app",
5  token: "token123",
6});
7
8// will return the passed authentication
9const { token } = await auth();

See Authentication object.

Usage with Octokit

1import { Octokit } from "@octokit/core";
2import { createOAuthUserAuth } from "@octokit/auth-oauth-user";

1const octokit = new Octokit({
2  authStrategy: createOAuthUserAuth,
3  auth: {
4    clientId: "1234567890abcdef1234",
5    clientSecret: "1234567890abcdef1234567890abcdef12345678",
6    code: "code123",
7  },
8});
9
10// Exchanges the code for the user access token authentication on first request
11// and caches the authentication for successive requests
12const {
13  data: { login },
14} = await octokit.request("GET /user");
15console.log("Hello, %s!", login);

createOAuthUserAuth(options) or new Octokit({ auth })

The createOAuthUserAuth method accepts a single options object as argument. The same set of options can be passed as auth to the Octokit constructor when setting authStrategy: createOAuthUserAuth

When using GitHub's OAuth web flow

1import { request } from "@octokit/request";
2createOAuthAppAuth({
3  clientId: "1234567890abcdef1234",
4  clientSecret: "1234567890abcdef1234567890abcdef12345678",
5  request: request.defaults({
6    baseUrl: "https://ghe.my-company.com/api/v3",
7  }),
8});

When using GitHub's OAuth device flow

1const auth = createOAuthUserAuth({
2  clientId: "1234567890abcdef1234",
3  clientSecret: "1234567890abcdef1234567890abcdef12345678",
4  onVerification(verification) {
5    console.log("Open %s", verification.verification_uri);
6    console.log("Enter code: %s", verification.user_code);
7
8    await prompt("press enter when you are ready to continue");
9  },
10});

1import { request } from "@octokit/request";
2createOAuthAppAuth({
3  clientId: "1234567890abcdef1234",
4  clientSecret: "1234567890abcdef1234567890abcdef12345678",
5  onVerification(verification) {
6    console.log("Open %s", verification.verification_uri);
7    console.log("Enter code: %s", verification.user_code);
8
9    await prompt("press enter when you are ready to continue");
10  },
11  request: request.defaults({
12    baseUrl: "https://ghe.my-company.com/api/v3",
13  }),
14});

When passing an existing authentication object

1import { request } from "@octokit/request";
2createOAuthAppAuth({
3  clientId: "1234567890abcdef1234",
4  clientSecret: "1234567890abcdef1234567890abcdef12345678",
5  request: request.defaults({
6    baseUrl: "https://ghe.my-company.com/api/v3",
7  }),
8});

[!IMPORTANT] As we use conditional exports, you will need to adapt your tsconfig.json by setting "moduleResolution": "node16", "module": "node16".

See the TypeScript docs on package.json "exports".
See this helpful guide on transitioning to ESM from @sindresorhus

auth(options) or octokit.auth(options)

The async auth() method is returned by createOAuthUserAuth(options) or set on the octokit instance when the Octokit constructor was called with authStrategy: createOAuthUserAuth.

Once auth() receives a valid authentication object it caches it in memory and uses it for subsequent calls. It also caches if the token is invalid and no longer tries to send any requests. If the authentication is using a refresh token, a new token will be requested as needed. Calling auth({ type: "reset" }) will replace the internally cached authentication.

Resolves with an authentication object.

Authentication object

There are three possible results

1. OAuth APP authentication token
2. GitHub APP user authentication token with expiring disabled
3. GitHub APP user authentication token with expiring enabled

The differences are

1. scopes is only present for OAuth Apps
2. refreshToken, expiresAt, refreshTokenExpiresAt are only present for GitHub Apps, and only if token expiration is enabled

OAuth APP authentication token

GitHub APP user authentication token with expiring disabled

GitHub APP user authentication token with expiring enabled

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

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

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

1const requestWithAuth = request.defaults({
2  request: {
3    hook: auth.hook,
4  },
5});
6
7const { data: user } = await requestWithAuth("GET /user");

Types

1import {
2  GitHubAppAuthentication,
3  GitHubAppAuthenticationWithExpiration,
4  GitHubAppAuthOptions,
5  GitHubAppStrategyOptions,
6  GitHubAppStrategyOptionsDeviceFlow,
7  GitHubAppStrategyOptionsExistingAuthentication,
8  GitHubAppStrategyOptionsExistingAuthenticationWithExpiration,
9  GitHubAppStrategyOptionsWebFlow,
10  OAuthAppAuthentication,
11  OAuthAppAuthOptions,
12  OAuthAppStrategyOptions,
13  OAuthAppStrategyOptionsDeviceFlow,
14  OAuthAppStrategyOptionsExistingAuthentication,
15  OAuthAppStrategyOptionsWebFlow,
16} from "@octokit/auth-oauth-user";

Contributing

See CONTRIBUTING.md

License

MIT