Socket
Socket
Sign inDemoInstall

@octokit/auth-oauth-device

Package Overview
Dependencies
8
Maintainers
4
Versions
25
Alerts
File Explorer

Advanced tools

Install Socket

Protect your apps from supply chain attacks

Install

@octokit/auth-oauth-device

GitHub OAuth Device authentication strategy for JavaScript

    7.0.1latest
    GitHub
    npm

Version published
Maintainers
4
Weekly downloads
1,203,607
increased by4.85%

Weekly downloads

Readme

Source

auth-oauth-device.js

GitHub OAuth Device authentication strategy for JavaScript

@latest Build Status

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

Usage

Browsers

Load @octokit/auth-oauth-device directly from esm.sh

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

Node

Install with npm install @octokit/core @octokit/auth-oauth-device

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

For OAuth Apps

const auth = createOAuthDeviceAuth({
  clientType: "oauth-app",
  clientId: "1234567890abcdef1234",
  scopes: ["public_repo"],
  onVerification(verification) {
    // verification example
    // {
    //   device_code: "3584d83530557fdd1f46af8289938c8ef79f9dc5",
    //   user_code: "WDJB-MJHT",
    //   verification_uri: "https://github.com/login/device",
    //   expires_in: 900,
    //   interval: 5,
    // };

    console.log("Open %s", verification.verification_uri);
    console.log("Enter code: %s", verification.user_code);
  },
});

const tokenAuthentication = await auth({
  type: "oauth",
});
// resolves with
// {
//   type: "token",
//   tokenType: "oauth",
//   clientType: "oauth-app",
//   clientId: "1234567890abcdef1234",
//   token: "...", /* the created oauth token */
//   scopes: [] /* depend on request scopes by OAuth app */
// }

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.

const auth = createOAuthDeviceAuth({
  clientType: "github-app",
  clientId: "lv1.1234567890abcdef",
  onVerification(verification) {
    // verification example
    // {
    //   device_code: "3584d83530557fdd1f46af8289938c8ef79f9dc5",
    //   user_code: "WDJB-MJHT",
    //   verification_uri: "https://github.com/login/device",
    //   expires_in: 900,
    //   interval: 5,
    // };

    console.log("Open %s", verification.verification_uri);
    console.log("Enter code: %s", verification.user_code);
  },
});

const tokenAuthentication = await auth({
  type: "oauth",
});
// resolves with
// {
//   type: "token",
//   tokenType: "oauth",
//   clientType: "github-app",
//   clientId: "lv1.1234567890abcdef",
//   token: "...", /* the created oauth token */
// }
// or if expiring user tokens are enabled
// {
//   type: "token",
//   tokenType: "oauth",
//   clientType: "github-app",
//   clientId: "lv1.1234567890abcdef",
//   token: "...", /* the created oauth token */
//   refreshToken: "...",
//   expiresAt: "2022-01-01T08:00:0.000Z",
//   refreshTokenExpiresAt: "2021-07-01T00:00:0.000Z",
// }

createOAuthDeviceAuth(options)

The createOAuthDeviceAuth method accepts a single options parameter

name type description
clientId string Required. Find your OAuth app’s Client ID in your account’s developer settings.
onVerification function Required. A function that is called once the device and user codes were retrieved

The onVerification() callback can be used to pause until the user completes step 2, which might result in a better user experience.

const auth = createOAuthDeviceAuth({
  clientId: "1234567890abcdef1234",
  onVerification(verification) {
    console.log("Open %s", verification.verification_uri);
    console.log("Enter code: %s", verification.user_code);

    await prompt("press enter when you are ready to continue");
  },
});
clientType string

Must be either oauth-app or github-app. Defaults to oauth-app.

request function You can pass in your own @octokit/request instance. For usage with enterprise, set baseUrl to the API root endpoint. Example:
import { request } from "@octokit/request";
createOAuthDeviceAuth({
  clientId: "1234567890abcdef1234",
  clientSecret: "secret",
  request: request.defaults({
    baseUrl: "https://ghe.my-company.com/api/v3",
  }),
});
scopes array of strings

Only relavant if clientType is set to "oauth-app".

Array of scope names enabled for the token. Defaults to []. See available scopes.

auth(options)

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

name type description
type string Required. Must be set to "oauth"
scopes array of strings

Only relevant if the clientType strategy options was set to "oauth-app"

Array of scope names enabled for the token. Defaults to what was set in the strategy options. See available scopes

refresh boolean

Defaults to false. When set to false, calling auth(options) will resolve with a token that was previously created for the same scopes if it exists. If set to true a new token will always be created.

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

name type description
type string "token"
tokenType string "oauth"
clientType string "github-app"
clientId string The app's Client ID
token string The personal access token
scopes array of strings array of scope names enabled for the token

GitHub APP user authentication with expiring tokens disabled

name type description
type string "token"
tokenType string "oauth"
clientType string "github-app"
clientId string The app's Client ID
token string The personal access token

GitHub APP user authentication with expiring tokens enabled

name type description
type string "token"
tokenType string "oauth"
clientType string "github-app"
clientId string The app's Client ID
token string The user access token
refreshToken string The refresh token
expiresAt string Date timestamp in ISO 8601 standard. Example: 2022-01-01T08:00:0.000Z
refreshTokenExpiresAt string Date timestamp in ISO 8601 standard. Example: 2021-07-01T00:00:0.000Z

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");

Types

import {
  OAuthAppStrategyOptions,
  OAuthAppAuthOptions,
  OAuthAppAuthentication,
  GitHubAppStrategyOptions,
  GitHubAppAuthOptions,
  GitHubAppAuthentication,
  GitHubAppAuthenticationWithExpiration,
} 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

Keywords

FAQs

Last updated on 27 Feb 2024

Did you know?

Socket installs a GitHub app to automatically flag issues on every pull request and report the health of your dependencies. Find out what is inside your node modules and prevent malicious activity before you update the dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc