What is @octokit/auth-oauth-device?
@octokit/auth-oauth-device is an npm package that provides OAuth device flow authentication for GitHub. It allows users to authenticate with GitHub using a device code, which is particularly useful for applications running on devices with limited input capabilities.
What are @octokit/auth-oauth-device's main functionalities?
Device Code Authentication
This feature allows you to authenticate a user via the OAuth device flow. The code sample demonstrates how to create an OAuth device authentication instance and use it to authenticate a user.
const { createOAuthDeviceAuth } = require('@octokit/auth-oauth-device');
const auth = createOAuthDeviceAuth({
clientType: 'oauth-app',
clientId: 'your-client-id',
clientSecret: 'your-client-secret'
});
(async () => {
const { authentication } = await auth({ type: 'oauth' });
console.log(authentication);
})();
Generate Device Code
This feature generates a device code and provides the user with a URL and code to authenticate. The code sample shows how to generate the device code and display the verification URL and user code.
const { createOAuthDeviceAuth } = require('@octokit/auth-oauth-device');
const auth = createOAuthDeviceAuth({
clientType: 'oauth-app',
clientId: 'your-client-id',
clientSecret: 'your-client-secret'
});
(async () => {
const { device_code, user_code, verification_uri } = await auth({ type: 'oauth', onVerification: ({ device_code, user_code, verification_uri }) => {
console.log(`Open ${verification_uri} and enter code: ${user_code}`);
}});
})();
Other packages similar to @octokit/auth-oauth-device
passport-oauth2
passport-oauth2 is a strategy for the Passport authentication middleware that supports OAuth 2.0. It provides a comprehensive set of features for OAuth 2.0 authentication but does not specifically focus on device flow like @octokit/auth-oauth-device.
simple-oauth2
simple-oauth2 is a library that provides a simple and consistent way to handle OAuth 2.0 authentication. It supports various OAuth 2.0 flows, including the device flow, but is more general-purpose compared to the GitHub-specific @octokit/auth-oauth-device.
client-oauth2
client-oauth2 is a library for creating OAuth 2.0 clients in JavaScript. It supports multiple OAuth 2.0 flows, including the device flow, and is designed to be flexible and easy to use. However, it is not specifically tailored for GitHub authentication.
auth-oauth-device.js
GitHub OAuth Device authentication strategy for JavaScript
![Build Status](https://github.com/octokit/auth-oauth-device.js/workflows/Test/badge.svg)
@octokit/auth-oauth-device
is implementing one of GitHub’s OAuth Device Flow.
Usage
Browsers
|
Load @octokit/auth-oauth-device directly from cdn.pika.dev
<script type="module">
import { createOAuthDeviceAuth } from "https://cdn.pika.dev/@octokit/auth-oauth-device";
</script>
|
---|
Node
|
Install with npm install @octokit/core @octokit/auth-oauth-device
const { createOAuthDeviceAuth } = require("@octokit/auth-oauth-device");
|
---|
For OAuth Apps
const auth = createOAuthDeviceAuth({
clientType: "oauth-app",
clientId: "1234567890abcdef1234",
scopes: ["public_repo"],
onVerification(verification) {
console.log("Open %s", verification.verification_uri);
console.log("Enter code: %s", verification.user_code);
},
});
const tokenAuthentication = await auth({
type: "oauth",
});
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) {
console.log("Open %s", verification.verification_uri);
console.log("Enter code: %s", verification.user_code);
},
});
const tokenAuthentication = await auth({
type: "oauth",
});
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:
const { request } = require("@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
- 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 AppsrefreshToken
, 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
- 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 (see GitHub documentation)
@octokit/auth-oauth-device
requests a device and user code- Then the user has to open https://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
Contributing
See CONTRIBUTING.md
License
MIT