octokit/auth-oauth-device.jsPublic

NotificationsYou must be signed in to change notification settings
Fork7
Star13

GitHub OAuth Device authentication strategy for JavaScript

License

MIT license

13 stars 7 forks Branches Tags Activity

Star

Notifications

You must be signed in to change notification settings

Branches Tags

Folders and files

Name		Name	Last commit message	Last commit date
Latest commit History 363 Commits
.github		.github
scripts		scripts
src		src
test		test
.gitignore		.gitignore
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vite.config.js		vite.config.js

Repository files navigation

auth-oauth-device.js

GitHub OAuth Device authentication strategy for JavaScript

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

Usage

Browsers	Load`@octokit/auth-oauth-device` directly fromesm.sh <scripttype="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";

Important

As we useconditional exports, you will need to adapt yourtsconfig.json by setting"moduleResolution": "node16", "module": "node16".

See the TypeScript docs onpackage.json "exports".
See thishelpful guide on transitioning to ESM from@sindresorhus

For OAuth Apps

constauth=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);},});consttokenAuthentication=awaitauth({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 supportscopes. Client IDs of GitHub Apps have alv1. prefix. If the GitHub App has expiring user tokens enabled, the resultingauthentication object has extra properties related to expiration and refreshing the token.

constauth=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);},});consttokenAuthentication=awaitauth({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)`

ThecreateOAuthDeviceAuth method accepts a singleoptions 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. constauth=createOAuthDeviceAuth({clientId:"1234567890abcdef1234",onVerification(verification){console.log("Open %s",verification.verification_uri);console.log("Enter code: %s",verification.user_code);awaitprompt("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 relevant if`clientType` is set to`"oauth-app"`. Array of scope names enabled for the token. Defaults to`[]`. Seeavailable scopes.

`auth(options)`

The asyncauth() method returned bycreateOAuthDeviceAuth(options) accepts the following options

name type description

type string Required. Must be set to"oauth"

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 thestrategy options. Seeavailable 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.

scopes

array of strings

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

Array of scope names enabled for the token. Defaults to what was set in thestrategy options. Seeavailable scopes

refresh

boolean

Defaults tofalse. When set tofalse, callingauth(options) will resolve with a token that was previously created for the same scopes if it exists. If set totrue a new token will always be created.

Authentication object

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

OAuth APP user authentication
GitHub APP user authentication with expiring tokens disabled
GitHub APP user authentication with expiring tokens enabled

The differences are

scopes is only present for OAuth Apps
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 inISO 8601 standard. Example:`2022-01-01T08:00:0.000Z`
`refreshTokenExpiresAt`	`string`	Date timestamp inISO 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.

Therequest option is an instance of@octokit/request. Theroute/options parameters are the same as for therequest() method.

auth.hook() can be called directly to send an authenticated request

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

Or it can be passed as option torequest().

constrequestWithAuth=request.defaults({request:{hook:auth.hook,},});const{data:user}=awaitrequestWithAuth("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

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

The flow has 3 parts (seeGitHub documentation)

@octokit/auth-oauth-device requests a device and user code
Then the user has to openhttps://github.com/login/device (or it's GitHub Enterprise Server equivalent) and enter the user code
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