GitHub OAuth App authentication for JavaScript
@octokit/auth-oauth-app
is implementing one of GitHub’s authentication strategies.
It implements authentication using an OAuth app’s client ID and secret as well as creating user access tokens GitHub's OAuth web application flow and device flow.
- Standalone Usage
- Usage with Octokit
createOAuthAppAuth(options)
ornew Octokit({ auth })
auth(options)
oroctokit.auth(options)
- Authentication object
auth.hook(request, route, parameters)
orauth.hook(request, options)
- Types
- Implementation details
- License
Browsers |
If you know what you are doing, load <script type="module">
import { createOAuthAppAuth } from "https://esm.sh/@octokit/auth-oauth-app";
</script> |
---|---|
Node |
Install with import { createOAuthAppAuth } from "@octokit/auth-oauth-app"; |
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
const auth = createOAuthAppAuth({
clientType: "oauth-app",
clientId: "1234567890abcdef1234",
clientSecret: "1234567890abcdef1234567890abcdef12345678",
});
const appAuthentication = await auth({
type: "oauth-app",
});
resolves with
{
"type": "oauth-app",
"clientId": "1234567890abcdef1234",
"clientSecret": "1234567890abcdef1234567890abcdef12345678",
"headers": {
"authorization": "basic MTIzNDU2Nzg5MGFiY2RlZjEyMzQ6MTIzNDU2Nzg5MGFiY2RlZjEyMzQ1Njc4OTBhYmNkZWYxMjM0NTY3OA=="
}
}
Exchange code from GitHub's OAuth web flow, see https://docs.github.com/en/developers/apps/authorizing-oauth-apps#2-users-are-redirected-back-to-your-site-by-github
const auth = createOAuthAppAuth({
clientType: "oauth-app",
clientId: "1234567890abcdef1234",
clientSecret: "1234567890abcdef1234567890abcdef12345678",
});
const userAuthenticationFromWebFlow = await auth({
type: "oauth-user",
code: "random123",
state: "mystate123",
});
resolves with
{
"clientType": "oauth-app",
"clientId": "1234567890abcdef1234",
"clientSecret": "1234567890abcdef1234567890abcdef12345678",
"type": "token",
"tokenType": "oauth",
"token": "useraccesstoken123",
"scopes": []
}
Pass an asynchronous onVerification()
method which will be called with the response from step 1 of the device flow. In that function you have to prompt the user to enter the user code at the provided verification URL.
auth()
will not resolve until the user entered the code and granted access to the app.
const auth = createOAuthAppAuth({
clientType: "oauth-app",
clientId: "1234567890abcdef1234",
clientSecret: "1234567890abcdef1234567890abcdef12345678",
});
const userAuthenticationFromDeviceFlow = await auth({
async 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 with
{
"clientType": "oauth-app",
"clientId": "1234567890abcdef1234",
"clientSecret": "1234567890abcdef1234567890abcdef12345678",
"type": "token",
"tokenType": "oauth",
"token": "useraccesstoken123",
"scopes": []
}
Browsers |
If you know what you are doing, load <script type="module">
import { createOAuthAppAuth } from "https://esm.sh/@octokit/auth-oauth-app";
import { Octokit } from "https://esm.sh/@octokit/core";
</script> |
---|---|
Node |
Install with import { Octokit } from "@octokit/core";
import {
createOAuthAppAuth,
createOAuthUserAuth,
} from "@octokit/auth-oauth-app"; |
const appOctokit = new Octokit({
authStrategy: createOAuthAppAuth,
auth: {
clientId: "1234567890abcdef1234",
clientSecret: "1234567890abcdef1234567890abcdef12345678",
},
});
// Send requests as app
await appOctokit.request("POST /application/{client_id}/token", {
client_id: "1234567890abcdef1234",
access_token: "existingtoken123",
});
console.log("token is valid");
// create a new octokit instance that is authenticated as the user
const userOctokit = await appOctokit.auth({
type: "oauth-user",
code: "code123",
factory: (options) => {
return new Octokit({
authStrategy: createOAuthUserAuth,
auth: options,
});
},
});
// Exchanges the code for the user access token authentication on first request
// and caches the authentication for successive requests
const {
data: { login },
} = await userOctokit.request("GET /user");
console.log("Hello, %s!", login);
The createOAuthAppAuth
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: createOAuthAppAuth
name | type | description |
---|---|---|
clientId
|
string
|
Required. Find your OAuth app’s Client ID in your account’s developer settings.
|
clientSecret
|
string
|
Required. Find your OAuth app’s Client Secret in your account’s developer settings.
|
clientType
|
string
|
Must be set to 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";
createOAuthAppAuth({
clientId: "1234567890abcdef1234",
clientSecret: "1234567890abcdef1234567890abcdef12345678",
request: request.defaults({
baseUrl: "https://ghe.my-company.com/api/v3",
}),
}); |
The async auth()
method returned by createOAuthAppAuth(options)
accepts different options depending on your use case
All REST API routes starting with /applications/{client_id}
need to be authenticated using the OAuth/GitHub App's Client ID and a client secret.
name | type | description |
---|---|---|
type
|
string
|
Required. Must be set to "oauth-app"
|
Exchange code
for a user access token. See Web application flow.
name | type | description |
---|---|---|
type
|
string
|
Required. Must be set to "oauth-user" .
|
code
|
string
|
Required. The authorization code which was passed as query parameter to the callback URL from the OAuth web application flow.
|
redirectUrl
|
string
|
The URL in your application where users are sent after authorization. See redirect urls. |
state
|
string
|
The unguessable random string you provided in Step 1 of the OAuth web application flow. |
factory
|
function
|
When the For example, you can create a new import {
createOAuthAppAuth,
createOAuthUserAuth,
} from "@octokit/auth-oauth-app";
const appAuth = createOAuthAppAuth({
clientType: "github-app",
clientId: "lv1.1234567890abcdef",
clientSecret: "1234567890abcdef1234567890abcdef12345678",
});
const userAuth = await appAuth({
type: "oauth-user",
code,
factory: createOAuthUserAuth,
});
// will create token upon first call, then cache authentication for successive calls,
// until token needs to be refreshed (if enabled for the GitHub App)
const authentication = await userAuth(); |
Create a user access token without an http redirect. See Device flow.
The device flow does not require a client secret, but it is required as strategy option for @octokit/auth-oauth-app
, even for the device flow. If you want to implement the device flow without requiring a client secret, use @octokit/auth-oauth-device
.
name | type | description |
---|---|---|
type
|
string
|
Required. Must be set to "oauth-user" .
|
onVerification
|
function
|
Required. A function that is called once the device and user codes were retrieved. The const auth = auth({
type: "oauth-user",
async 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");
},
}); |
scopes
|
array of strings
|
Only relevant if the clientType strategy option is set to "oauth-app" .Array of OAuth scope names that the user access token should be granted. Defaults to no scopes ([] ).
|
factory
|
function
|
When the For example, you can create a new import {
createOAuthAppAuth,
createOAuthUserAuth,
} from "@octokit/auth-oauth-app";
const appAuth = createOAuthAppAuth({
clientType: "github-app",
clientId: "lv1.1234567890abcdef",
clientSecret: "1234567890abcdef1234567890abcdef12345678",
});
const userAuth = await appAuth({
type: "oauth-user",
onVerification,
factory: createOAuthUserAuth,
});
// will create token upon first call, then cache authentication for successive calls,
// until token needs to be refreshed (if enabled for the GitHub App)
const authentication = await userAuth(); |
The async auth(options)
method to one of four possible authentication objects
- OAuth App authentication for
auth({ type: "oauth-app" })
- OAuth user access token authentication for
auth({ type: "oauth-app" })
and App is an OAuth App (OAuth user access token) - GitHub APP user authentication token with expiring disabled for
auth({ type: "oauth-app" })
and App is a GitHub App (user-to-server token) - GitHub APP user authentication token with expiring enabled for
auth({ type: "oauth-app" })
and App is a GitHub App (user-to-server token)
name | type | description |
---|---|---|
type
|
string
|
"oauth-app"
|
clientType
|
string
|
"oauth-app" or "github-app"
|
clientId
|
string
|
The client ID as passed to the constructor. |
clientSecret
|
string
|
The client secret as passed to the constructor. |
headers
|
object
|
{ authorization } .
|
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 |
name | type | description |
---|---|---|
type
|
string
|
"token"
|
tokenType
|
string
|
"oauth"
|
clientType
|
string
|
"github-app"
|
clientId
|
string
|
The app's Client ID
|
clientSecret
|
string
|
One of the app's client secrets |
token
|
string
|
The user access token |
name | type | description |
---|---|---|
type
|
string
|
"token"
|
tokenType
|
string
|
"oauth"
|
clientType
|
string
|
"github-app"
|
clientId
|
string
|
The app's Client ID
|
clientSecret
|
string
|
One of the app's client secrets |
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()
hooks directly into the request life cycle. It amends the request to authenticate correctly using clientId
and clientSecret
as basic auth for the API endpoints that support it. It throws an error in other cases.
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,
"POST /applications/{client_id}/token",
{
client_id: "1234567890abcdef1234",
access_token: "token123",
},
);
Or it can be passed as option to request()
.
const requestWithAuth = request.defaults({
request: {
hook: auth.hook,
},
});
const { data: user } = await requestWithAuth(
"POST /applications/{client_id}/token",
{
client_id: "1234567890abcdef1234",
access_token: "token123",
},
);
import {
// strategy options
OAuthAppStrategyOptions,
GitHubAppStrategyOptions,
// auth options
AppAuthOptions,
WebFlowAuthOptions,
OAuthAppDeviceFlowAuthOptions,
GitHubAppDeviceFlowAuthOptions,
// auth interfaces
OAuthAppAuthInterface,
GitHubAuthInterface,
// authentication object
AppAuthentication,
OAuthAppUserAuthentication,
GitHubAppUserAuthentication,
GitHubAppUserAuthenticationWithExpiration,
} from "@octokit/auth-oauth-app";
Client ID and secret can be passed as Basic auth in the Authorization
header in order to get a higher rate limit compared to unauthenticated requests. This is meant for the use on servers only: never expose an OAuth client secret on a client such as a web application!
auth.hook
will set the correct authentication header automatically based on the request URL. For all OAuth Application endpoints, the Authorization
header is set to basic auth. For all other endpoints and token is retrieved and used in the Authorization
header. The token is cached and used for succeeding requests.
To reset the cached access token, you can do this
const { token } = await auth({ type: "oauth-user" });
await auth.hook(request, "POST /applications/{client_id}/token", {
client_id: "1234567890abcdef1234",
access_token: token,
});
The internally cached token will be replaced and used for succeeding requests. See also "the REST API documentation".
See also: octokit/oauth-authorization-url.js.