https://github.com/octokit/auth-oauth-user.js
Octokit authentication strategy for OAuth clients
https://github.com/octokit/auth-oauth-user.js
hacktoberfest oauth octokit-js plugin
Last synced: 7 months ago
JSON representation
Octokit authentication strategy for OAuth clients
- Host: GitHub
- URL: https://github.com/octokit/auth-oauth-user.js
- Owner: octokit
- License: mit
- Created: 2021-03-10T19:25:06.000Z (almost 5 years ago)
- Default Branch: main
- Last Pushed: 2025-05-26T02:56:22.000Z (8 months ago)
- Last Synced: 2025-06-02T21:15:04.464Z (8 months ago)
- Topics: hacktoberfest, oauth, octokit-js, plugin
- Language: TypeScript
- Homepage:
- Size: 2.02 MB
- Stars: 18
- Watchers: 5
- Forks: 7
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# auth-oauth-user.js
> Octokit authentication strategy for OAuth user authentication
[](https://www.npmjs.com/package/@octokit/auth-oauth-user)
[](https://github.com/octokit/auth-oauth-user.js/actions?query=workflow%3ATest+branch%3Amain)
**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`](https://github.com/octokit/auth-oauth-user-client.js#readme). Note that `@octokit/auth-oauth-user-client` requires a backend. The only exception is [`@octokit/auth-oauth-device`](https://github.com/octokit/auth-oauth-device.js#readme) which does not require the `client_secret`, but does not work in browsers due to CORS constraints.
Table of contents
- [Features](#features)
- [Standalone usage](#standalone-usage)
- [Exchange code from OAuth web flow](#exchange-code-from-oauth-web-flow)
- [OAuth Device flow](#oauth-device-flow)
- [Use an existing authentication](#use-an-existing-authentication)
- [Usage with Octokit](#usage-with-octokit)
- [`createOAuthUserAuth(options)` or `new Octokit({ auth })`](#createoauthuserauthoptions-or-new-octokit-auth-)
- [When using GitHub's OAuth web flow](#when-using-githubs-oauth-web-flow)
- [When using GitHub's OAuth device flow](#when-using-githubs-oauth-device-flow)
- [When passing an existing authentication object](#when-passing-an-existing-authentication-object)
- [`auth(options)` or `octokit.auth(options)`](#authoptions-or-octokitauthoptions)
- [Authentication object](#authentication-object)
- [OAuth APP authentication token](#oauth-app-authentication-token)
- [GitHub APP user authentication token with expiring disabled](#github-app-user-authentication-token-with-expiring-disabled)
- [GitHub APP user authentication token with expiring enabled](#github-app-user-authentication-token-with-expiring-enabled)
- [`auth.hook(request, route, parameters)` or `auth.hook(request, options)`](#authhookrequest-route-parameters-or-authhookrequest-options)
- [Types](#types)
- [Contributing](#contributing)
- [License](#license)
## Features
- Code for token exchange from [GitHub's OAuth web flow](https://docs.github.com/en/developers/apps/authorizing-oauth-apps#web-application-flow)
- [GitHub's OAuth device flow](https://docs.github.com/en/developers/apps/authorizing-oauth-apps#device-flow)
- Caches token for succesive calls
- Auto-refreshing for [expiring user access tokens](https://docs.github.com/en/developers/apps/refreshing-user-to-server-access-tokens)
- Applies the correct authentication strategy based on the request URL when using with `Octokit`
- Token verification
- Token reset
- Token invalidation
- Application grant revocation
## Standalone usage
Browsers
Load `@octokit/auth-oauth-user` directly from [esm.sh](https://esm.sh)
```html
import { createOAuthUserAuth } from "https://esm.sh/@octokit/auth-oauth-user";
```
Node
Install with `npm install @octokit/auth-oauth-user`
```js
import { createOAuthUserAuth } from "@octokit/auth-oauth-user";
```
### Exchange code from OAuth web flow
```js
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](https://docs.github.com/en/developers/apps/authorizing-oauth-apps#web-application-flow)
### OAuth Device flow
```js
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](https://docs.github.com/en/developers/apps/authorizing-oauth-apps#device-flow)
### Use an existing authentication
```js
const auth = createOAuthUserAuth({
clientId: "1234567890abcdef1234",
clientSecret: "1234567890abcdef1234567890abcdef12345678",
clientType: "oauth-app",
token: "token123",
});
// will return the passed authentication
const { token } = await auth();
```
See [Authentication object](#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
```js
import { Octokit } from "@octokit/core";
import { createOAuthUserAuth } from "@octokit/auth-oauth-user";
```
```js
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`
### 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](https://docs.github.com/en/developers/apps/authorizing-oauth-apps#web-application-flow).
state
string
The unguessable random string you provided in [Step 1 of GitHub's OAuth web application flow](https://docs.github.com/en/developers/apps/authorizing-oauth-apps#1-request-a-users-github-identity).
redirectUrl
string
The redirect_uri parameter you provided in [Step 1 of GitHub's OAuth web application flow](https://docs.github.com/en/developers/apps/authorizing-oauth-apps#1-request-a-users-github-identity).
request
function
You can pass in your own @octokit/request instance. For usage with enterprise, set baseUrl to the API root endpoint. Example:
```js
import { request } from "@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.
```js
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:
```js
import { request } from "@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:
```js
import { request } from "@octokit/request";
createOAuthAppAuth({
clientId: "1234567890abcdef1234",
clientSecret: "1234567890abcdef1234567890abcdef12345678",
request: request.defaults({
baseUrl: "https://ghe.my-company.com/api/v3",
}),
});
```
> [!IMPORTANT]
> As we use [conditional exports](https://nodejs.org/api/packages.html#conditional-exports), you will need to adapt your `tsconfig.json` by setting `"moduleResolution": "node16", "module": "node16"`.
>
> See the TypeScript docs on [package.json "exports"](https://www.typescriptlang.org/docs/handbook/modules/reference.html#packagejson-exports).
> See this [helpful guide on transitioning to ESM](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c) from [@sindresorhus](https://github.com/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](#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
1. [OAuth APP authentication token](#oauth-app-authentication-token)
1. [GitHub APP user authentication token with expiring disabled](#github-app-user-authentication-token-with-expiring-disabled)
1. [GitHub APP user authentication token with expiring enabled](#github-app-user-authentication-token-with-expiring-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 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`](https://github.com/octokit/request.js#readme). The `route`/`options` parameters are the same as for the [`request()` method](https://github.com/octokit/request.js#request).
`auth.hook()` can be called directly to send an authenticated request
```js
const { data: user } = await auth.hook(request, "GET /user");
```
Or it can be passed as option to [`request()`](https://github.com/octokit/request.js#request).
```js
const requestWithAuth = request.defaults({
request: {
hook: auth.hook,
},
});
const { data: user } = await requestWithAuth("GET /user");
```
## Types
```ts
import {
GitHubAppAuthentication,
GitHubAppAuthenticationWithExpiration,
GitHubAppAuthOptions,
GitHubAppStrategyOptions,
GitHubAppStrategyOptionsDeviceFlow,
GitHubAppStrategyOptionsExistingAuthentication,
GitHubAppStrategyOptionsExistingAuthenticationWithExpiration,
GitHubAppStrategyOptionsWebFlow,
OAuthAppAuthentication,
OAuthAppAuthOptions,
OAuthAppStrategyOptions,
OAuthAppStrategyOptionsDeviceFlow,
OAuthAppStrategyOptionsExistingAuthentication,
OAuthAppStrategyOptionsWebFlow,
} from "@octokit/auth-oauth-user";
```
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md)
## License
[MIT](LICENSE)