auth-oauth-device.js

GitHub OAuth Device authentication strategy for JavaScript

@octokit/auth-oauth-device is implementing one of GitHub’s OAuth Device Flow.

• Usage
  • For OAuth Apps
  • For GitHub Apps
• createOAuthDeviceAuth(options)
• auth(options)
• Authentication object
  • OAuth APP user authentication
  • GitHub APP user authentication with expiring tokens disabled
  • GitHub APP user authentication with expiring tokens enabled
• auth.hook(request, route, parameters) or auth.hook(request, options)
• Types
• How it works
• Contributing
• License

Usage

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

1import { createOAuthDeviceAuth } from "@octokit/auth-oauth-device";

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

For OAuth Apps

1const auth = createOAuthDeviceAuth({
2  clientType: "oauth-app",
3  clientId: "1234567890abcdef1234",
4  scopes: ["public_repo"],
5  onVerification(verification) {
6    // verification example
7    // {
8    //   device_code: "3584d83530557fdd1f46af8289938c8ef79f9dc5",
9    //   user_code: "WDJB-MJHT",
10    //   verification_uri: "https://github.com/login/device",
11    //   expires_in: 900,
12    //   interval: 5,
13    // };
14
15    console.log("Open %s", verification.verification_uri);
16    console.log("Enter code: %s", verification.user_code);
17  },
18});
19
20const tokenAuthentication = await auth({
21  type: "oauth",
22});
23// resolves with
24// {
25//   type: "token",
26//   tokenType: "oauth",
27//   clientType: "oauth-app",
28//   clientId: "1234567890abcdef1234",
29//   token: "...", /* the created oauth token */
30//   scopes: [] /* depend on request scopes by OAuth app */
31// }

For GitHub Apps

GitHub Apps do not support scopes. Client IDs of GitHub Apps have a lv1. prefix. If the GitHub App has expiring user tokens enabled, the resulting authentication object has extra properties related to expiration and refreshing the token.

1const auth = createOAuthDeviceAuth({
2  clientType: "github-app",
3  clientId: "lv1.1234567890abcdef",
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
19const tokenAuthentication = await auth({
20  type: "oauth",
21});
22// resolves with
23// {
24//   type: "token",
25//   tokenType: "oauth",
26//   clientType: "github-app",
27//   clientId: "lv1.1234567890abcdef",
28//   token: "...", /* the created oauth token */
29// }
30// or if expiring user tokens are enabled
31// {
32//   type: "token",
33//   tokenType: "oauth",
34//   clientType: "github-app",
35//   clientId: "lv1.1234567890abcdef",
36//   token: "...", /* the created oauth token */
37//   refreshToken: "...",
38//   expiresAt: "2022-01-01T08:00:0.000Z",
39//   refreshTokenExpiresAt: "2021-07-01T00:00:0.000Z",
40// }

createOAuthDeviceAuth(options)

The createOAuthDeviceAuth method accepts a single options parameter

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

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

auth(options)

The async auth() method returned by createOAuthDeviceAuth(options) accepts the following options

Authentication object

The async auth(options) method resolves to one of three possible objects

1. OAuth APP user authentication
2. GitHub APP user authentication with expiring tokens disabled
3. GitHub APP user authentication with expiring tokens 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 user authentication

GitHub APP user authentication with expiring tokens disabled

GitHub APP user authentication with expiring tokens 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  OAuthAppStrategyOptions,
3  OAuthAppAuthOptions,
4  OAuthAppAuthentication,
5  GitHubAppStrategyOptions,
6  GitHubAppAuthOptions,
7  GitHubAppAuthentication,
8  GitHubAppAuthenticationWithExpiration,
9} from "@octokit/auth-oauth-device";

How it works

GitHub's OAuth Device flow is different from the web flow in two ways

1. It does not require a URL redirect, which makes it great for devices and CLI apps
2. It does not require the OAuth client secret, which means there is no user-owned server component required.

The flow has 3 parts (see GitHub documentation)

1. @octokit/auth-oauth-device requests a device and user code
2. Then the user has to open https://github.com/login/device (or it's GitHub Enterprise Server equivalent) and enter the user code
3. While the user enters the code, @octokit/auth-oauth-device is sending requests in the background to retrieve the OAuth access token. Once the user completed step 2, the request will succeed and the token will be returned

Contributing

See CONTRIBUTING.md

License

MIT