What is @octokit/auth-oauth-user?
@octokit/auth-oauth-user is an npm package that provides OAuth user authentication for GitHub. It allows developers to authenticate users via OAuth and perform actions on behalf of the authenticated user.
What are @octokit/auth-oauth-user's main functionalities?
OAuth User Authentication
This feature allows you to authenticate a user via OAuth by providing the client ID, client secret, and authorization code. The code sample demonstrates how to obtain an OAuth token for the authenticated user.
const { createOAuthUserAuth } = require('@octokit/auth-oauth-user');
const auth = createOAuthUserAuth({
clientId: 'your-client-id',
clientSecret: 'your-client-secret',
code: 'authorization-code'
});
(async () => {
const { token } = await auth();
console.log('OAuth Token:', token);
})();
Token Authentication
This feature allows you to authenticate a user using an existing access token. The code sample demonstrates how to authenticate and retrieve the token.
const { createOAuthUserAuth } = require('@octokit/auth-oauth-user');
const auth = createOAuthUserAuth({
clientId: 'your-client-id',
clientSecret: 'your-client-secret',
token: 'user-access-token'
});
(async () => {
const { token } = await auth();
console.log('Authenticated Token:', token);
})();
Refresh Token
This feature allows you to refresh an OAuth token using a refresh token. The code sample demonstrates how to obtain a new access token using a refresh token.
const { createOAuthUserAuth } = require('@octokit/auth-oauth-user');
const auth = createOAuthUserAuth({
clientId: 'your-client-id',
clientSecret: 'your-client-secret',
refreshToken: 'user-refresh-token'
});
(async () => {
const { token } = await auth();
console.log('Refreshed Token:', token);
})();
Other packages similar to @octokit/auth-oauth-user
passport-github
passport-github is a Passport strategy for authenticating with GitHub using the OAuth 2.0 API. It is similar to @octokit/auth-oauth-user in that it provides OAuth authentication for GitHub, but it is designed to be used with the Passport.js authentication middleware.
simple-oauth2
simple-oauth2 is a library that provides a simple and consistent way to handle OAuth 2.0 authentication. It can be used to authenticate with various OAuth 2.0 providers, including GitHub. Unlike @octokit/auth-oauth-user, it is not specific to GitHub and can be used with other services as well.
node-oauth2-server
node-oauth2-server is a complete, framework-agnostic, OAuth2 server for Node.js. It allows you to implement OAuth 2.0 authorization and authentication in your application. While it provides more comprehensive OAuth 2.0 support, it requires more setup compared to @octokit/auth-oauth-user, which is specifically tailored for GitHub.
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.
Table of contents
Features
Standalone usage
Browsers
|
Load @octokit/auth-oauth-user directly from cdn.skypack.dev
<script type="module">
import { createOAuthUserAuth } from "https://cdn.skypack.dev/@octokit/auth-oauth-user";
</script>
|
---|
Node
|
Install with npm install @octokit/auth-oauth-user
const { createOAuthUserAuth } = require("@octokit/auth-oauth-user");
|
---|
Exchange code from OAuth web flow
const auth = createOAuthUserAuth({
clientId: "1234567890abcdef1234",
clientSecret: "1234567890abcdef1234567890abcdef12345678",
code: "code123",
state: "state123",
redirectUrl: "https://acme-inc.com/login",
});
const { token } = await auth();
About GitHub's OAuth web flow
OAuth Device flow
const auth = createOAuthUserAuth({
clientId: "1234567890abcdef1234",
clientSecret: "1234567890abcdef1234567890abcdef12345678",
onVerification(verification) {
console.log("Open %s", verification.verification_uri);
console.log("Enter code: %s", verification.user_code);
},
});
const { token } = await auth();
About GitHub's OAuth device flow
Use an existing authentication
const auth = createOAuthUserAuth({
clientId: "1234567890abcdef1234",
clientSecret: "1234567890abcdef1234567890abcdef12345678",
clientType: "oauth-app",
token: "token123",
});
const { token } = await auth();
See Authentication object.
Usage with Octokit
Browsers
|
@octokit/auth-oauth-user cannot be used in the browser. It requires clientSecret to be set which must not be exposed to clients, and some of the OAuth APIs it uses do not support CORS.
|
---|
Node
|
Install with npm install @octokit/core @octokit/auth-oauth-user . Optionally replace @octokit/core with a compatible module
const { Octokit } = require("@octokit/core");
const { createOAuthUserAuth } = require("@octokit/auth-oauth-user");
|
---|
const octokit = new Octokit({
authStrategy: createOAuthUserAuth,
auth: {
clientId: "1234567890abcdef1234",
clientSecret: "1234567890abcdef1234567890abcdef12345678",
code: "code123",
},
});
const {
data: { login },
} = await octokit.request("GET /user");
console.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
name
|
type
|
description
|
---|
clientId
|
string
|
Required. Client ID of your GitHub/OAuth App. Find it on your app's settings page.
|
---|
clientSecret
|
string
|
Required. Client Secret for your GitHub/OAuth App. Create one on your app's settings page.
|
---|
clientType
|
string
|
Either "oauth-app" or "github-app" . Defaults to "oauth-app" .
|
---|
code
|
string
|
Required. The authorization code which was passed as query parameter to the callback URL from GitHub's OAuth web application flow.
|
---|
state
|
string
|
The unguessable random string you provided in Step 1 of GitHub's OAuth web application flow.
|
---|
redirectUrl
|
string
|
The redirect_uri parameter you provided in Step 1 of GitHub's OAuth web application flow.
|
---|
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");
createOAuthAppAuth({
clientId: "1234567890abcdef1234",
clientSecret: "1234567890abcdef1234567890abcdef12345678",
request: request.defaults({
baseUrl: "https://ghe.my-company.com/api/v3",
}),
});
|
---|
When using GitHub's OAuth device flow
name
|
type
|
description
|
---|
clientId
|
string
|
Required. Client ID of your GitHub/OAuth App. Find it on your app's settings page.
|
---|
clientSecret
|
string
|
Required. Client Secret for your GitHub/OAuth App. The clientSecret is not needed for the OAuth device flow itself, but it is required for resetting, refreshing, and invalidating a token. Find the Client Secret on your app's settings page.
|
---|
clientType
|
string
|
Either "oauth-app" or "github-app" . Defaults to "oauth-app" .
|
---|
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 = createOAuthUserAuth({
clientId: "1234567890abcdef1234",
clientSecret: "1234567890abcdef1234567890abcdef12345678",
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");
},
});
|
---|
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");
createOAuthAppAuth({
clientId: "1234567890abcdef1234",
clientSecret: "1234567890abcdef1234567890abcdef12345678",
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");
},
request: request.defaults({
baseUrl: "https://ghe.my-company.com/api/v3",
}),
});
|
---|
When passing an existing authentication object
name
|
type
|
description
|
---|
clientType
|
string
|
Required. Either "oauth-app" or "github" .
|
---|
clientId
|
string
|
Required. Client ID of your GitHub/OAuth App. Find it on your app's settings page.
|
---|
clientSecret
|
string
|
Required. Client Secret for your GitHub/OAuth App. Create one on your app's settings page.
|
---|
token
|
string
|
Required. The user access token
|
---|
scopes
|
array of strings
|
Required if clientType is set to "oauth-app" . Array of OAuth scope names the token was granted
|
---|
refreshToken
|
string
|
Only relevant if clientType is set to "github-app" and token expiration is enabled.
|
---|
expiresAt
|
string
|
Only relevant if clientType is set to "github-app" and token expiration is enabled. Date timestamp in ISO 8601 standard. Example: 2022-01-01T08:00:0.000Z
|
---|
refreshTokenExpiresAt
|
string
|
Only relevant if clientType is set to "github-app" and token expiration is enabled. Date timestamp in ISO 8601 standard. Example: 2021-07-01T00:00:0.000Z
|
---|
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");
createOAuthAppAuth({
clientId: "1234567890abcdef1234",
clientSecret: "1234567890abcdef1234567890abcdef12345678",
request: request.defaults({
baseUrl: "https://ghe.my-company.com/api/v3",
}),
});
|
---|
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.
name
|
type
|
description
|
---|
type
|
string
|
Without setting type auth will return the current authentication object, or exchange the code from the strategy options on first call. If the current authentication token is expired, the tokens will be refreshed.
Possible values for type are
"get" : returns the token from internal state and creates it if none was created yet"check" : sends request to verify the validity of the current token"reset" : invalidates current token and replaces it with a new one"refresh" : GitHub Apps only, and only if expiring user tokens are enabled."delete" : invalidates current token"deleteAuthorization" : revokes OAuth access for application. All tokens for the current user created by the same app are invalidated. The user will be prompted to grant access again during the next OAuth web flow.
|
---|
Authentication object
There are three possible results
- OAuth APP authentication token
- GitHub APP user authentication token with expiring disabled
- GitHub APP user authentication token with expiring 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 authentication token
name
|
type
|
description
|
---|
type
|
string
|
"token"
|
---|
tokenType
|
string
|
"oauth"
|
---|
clientType
|
string
|
"oauth-app"
|
---|
clientId
|
string
|
The clientId from the strategy options
|
---|
clientSecret
|
string
|
The clientSecret from the strategy options
|
---|
token
|
string
|
The user access token
|
---|
scopes
|
array of strings
|
array of scope names enabled for the token
|
---|
onTokenCreated
|
function
|
callback invoked when a token is "reset" or "refreshed"
|
---|
invalid
|
boolean
|
Either undefined or true . Will be set to true if the token was invalided explicitly or found to be invalid
|
---|
GitHub APP user authentication token with expiring disabled
name
|
type
|
description
|
---|
type
|
string
|
"token"
|
---|
tokenType
|
string
|
"oauth"
|
---|
clientType
|
string
|
"github-app"
|
---|
clientId
|
string
|
The clientId from the strategy options
|
---|
clientSecret
|
string
|
The clientSecret from the strategy options
|
---|
token
|
string
|
The user access token
|
---|
onTokenCreated
|
function
|
callback invoked when a token is "reset" or "refreshed"
|
---|
invalid
|
boolean
|
Either undefined or true . Will be set to true if the token was invalided explicitly or found to be invalid
|
---|
GitHub APP user authentication token with expiring enabled
name
|
type
|
description
|
---|
type
|
string
|
"token"
|
---|
tokenType
|
string
|
"oauth"
|
---|
clientType
|
string
|
"github-app"
|
---|
clientId
|
string
|
The clientId from the strategy options
|
---|
clientSecret
|
string
|
The clientSecret from the strategy options
|
---|
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
|
---|
invalid
|
boolean
|
Either undefined or true . Will be set to true if the token was invalided explicitly or found to be invalid
|
---|
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 {
GitHubAppAuthentication,
GitHubAppAuthenticationWithExpiration,
GitHubAppAuthOptions,
GitHubAppStrategyOptions,
GitHubAppStrategyOptionsDeviceFlow,
GitHubAppStrategyOptionsExistingAuthentication,
GitHubAppStrategyOptionsExistingAuthenticationWithExpiration,
GitHubAppStrategyOptionsWebFlow,
OAuthAppAuthentication,
OAuthAppAuthOptions,
OAuthAppStrategyOptions,
OAuthAppStrategyOptionsDeviceFlow,
OAuthAppStrategyOptionsExistingAuthentication,
OAuthAppStrategyOptionsWebFlow,
} from "@octokit/auth-oauth-user";
Contributing
See CONTRIBUTING.md
License
MIT