Security News
Research
Data Theft Repackaged: A Case Study in Malicious Wrapper Packages on npm
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
@octokit/auth-oauth-user
Advanced tools
@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.
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);
})();
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 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 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.
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.
Octokit
Browsers |
Load
|
---|---|
Node |
Install with
|
const auth = createOAuthUserAuth({
clientId: "1234567890abcdef1234",
clientSecret: "1234567890abcdef1234567890abcdef12345678",
code: "code123",
// optional
state: "state123",
redirectUrl: "https://acme-inc.com/login",
});
// Exchanges the code for the user access token authentication on first call
// and caches the authentication for successive calls
const { token } = await auth();
About GitHub's OAuth web flow
const auth = createOAuthUserAuth({
clientId: "1234567890abcdef1234",
clientSecret: "1234567890abcdef1234567890abcdef12345678",
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);
},
});
// resolves once the user entered the `user_code` on `verification_uri`
const { token } = await auth();
About GitHub's OAuth device flow
const auth = createOAuthUserAuth({
clientId: "1234567890abcdef1234",
clientSecret: "1234567890abcdef1234567890abcdef12345678",
clientType: "oauth-app",
token: "token123",
});
// will return the passed authentication
const { token } = await auth();
Browsers |
|
---|---|
Node |
Install with
|
const octokit = new Octokit({
authStrategy: createOAuthUserAuth,
auth: {
clientId: "1234567890abcdef1234",
clientSecret: "1234567890abcdef1234567890abcdef12345678",
code: "code123",
},
});
// Exchanges the code for the user access token authentication on first request
// and caches the authentication for successive requests
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
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 |
request
|
function
|
You can pass in your own @octokit/request instance. For usage with enterprise, set baseUrl to the API root endpoint. Example:
|
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
|
request
|
function
|
You can pass in your own @octokit/request instance. For usage with enterprise, set baseUrl to the API root endpoint. Example:
|
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:
|
[!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
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 Possible values for
|
There are three possible results
The differences are
scopes
is only present for OAuth AppsrefreshToken
, expiresAt
, refreshTokenExpiresAt
are only present for GitHub Apps, and only if token expiration is enabledname | 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 |
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 |
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 |
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");
import {
GitHubAppAuthentication,
GitHubAppAuthenticationWithExpiration,
GitHubAppAuthOptions,
GitHubAppStrategyOptions,
GitHubAppStrategyOptionsDeviceFlow,
GitHubAppStrategyOptionsExistingAuthentication,
GitHubAppStrategyOptionsExistingAuthenticationWithExpiration,
GitHubAppStrategyOptionsWebFlow,
OAuthAppAuthentication,
OAuthAppAuthOptions,
OAuthAppStrategyOptions,
OAuthAppStrategyOptionsDeviceFlow,
OAuthAppStrategyOptionsExistingAuthentication,
OAuthAppStrategyOptionsWebFlow,
} from "@octokit/auth-oauth-user";
See CONTRIBUTING.md
FAQs
Octokit authentication strategy for OAuth clients
The npm package @octokit/auth-oauth-user receives a total of 796,010 weekly downloads. As such, @octokit/auth-oauth-user popularity was classified as popular.
We found that @octokit/auth-oauth-user demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 4 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.
Security News
The Ultralytics' PyPI Package was compromised four times in one weekend through GitHub Actions cache poisoning and failure to rotate previously compromised API tokens.