octokit-auth-oauth-user-client.js
Authentication strategy for Octokit without exposing client secret.
Backend Service
octokit-auth-oauth-user-client.js
requires a backend service to function.
@octokit/oauth-app
provides the
compatible Node.js/Express.js/Cloudflare Worker/Deno middlewares to interact
with octokit-auth-oauth-user-client.js
.
NPM
npm install octokit-auth-oauth-user-client
Browsers
Load directly from CDNs:
https://esm.sh/octokit-auth-oauth-user-client@0.1.6
https://cdn.skypack.dev/octokit-auth-oauth-user-client@0.1.6
https://cdn.jsdelivr.net/npm/octokit-auth-oauth-user-client@0.1.6
https://unpkg.com/octokit-auth-oauth-user-client@0.1.6
<script type="module">
import { createOAuthUserClientAuth } from "https://esm.sh/octokit-auth-oauth-user-client@0.1.6";
</script>
Create An Authenticator Instance
const authenticator = createOAuthUserClientAuth({
clientId: "client_id", // get client id from https://github.com/settings/apps
clientType: "github-app", // "github-app" | "oauth-app"
expirationEnabled: true, // true | false
});
Get Token
Use { type: "getToken" }
method to get authentication object from
localStorage
.
Returns null
when there is no authentication object found in localStorage
.
When both code
and state
search parameters are present (user being
redirected from GitHub login url), "getToken"
method will automatically
exchange the code
search parameter for an authentication object using the
backend service.
const auth = await authenticator(); // ≡ ({ type: "getToken" })
Sign In
Use signIn
method to clear authentication object from localStorage
and
redirect user to GitHub login url.
if (!auth) await authenticator({ type: "signIn" });
All Methods
{ type: ? } |
Meaning | Note |
---|---|---|
"getToken" |
Get token | See Get token. |
"signIn" |
Sign in | See Sign in. |
"createToken" |
Exchange code in url parameters for token |
Normally the getToken method will exchange code for an access token automatically when both code and state search parameters are present (user being redirected from GitHub login url). |
"checkToken" |
Check a token | — |
"createScopedToken" |
Create a scoped access token | For OAuth app only. Specify extra parameters like { type: "createScopedToken", target: ... } . |
"resetToken" |
Reset a token | — |
"renewToken" |
Renewing a user token with a refresh token | The app should enable token expiration in settings (GitHub App only currently) |
"deleteToken" |
Delete an app token | Use { type = "deleteToken", offline: true } to delete authentication from localStorage without calling GitHub API via backend service. |
"deleteAuthorization" |
Delete an app authorization |
Usage with Octokit
To use octokit-auth-oauth-user-client
with
@octokit/core
-compatible
modules, specify the authentication strategy and authentication strategy
options.
<script type="module">
import { Octokit } from "https://cdn.skypack.dev/octokit";
import { createOAuthUserClientAuth } from "https://esm.sh/octokit-auth-oauth-user-client@0.1.6";
const octokit = new Octokit({
authStrategy: createOAuthUserClientAuth,
auth: {
clientId: "client_id", // get client id from https://github.com/settings/apps
clientType: "github-app", // "github-app" | "oauth-app"
expirationEnabled: true, // true | false
},
});
const auth = await octokit.auth();
if (!auth) await octokit.auth({ type: "signIn" });
else console.log(await octokit.rest.users.getAuthenticated());
</script>
Or
<script type="module">
import { Octokit } from "https://cdn.skypack.dev/@octokit/core";
import { createOAuthUserClientAuth } from "https://esm.sh/octokit-auth-oauth-user-client@0.1.6";
const octokit = new Octokit({
authStrategy: createOAuthUserClientAuth,
auth: {
clientId: "client_id", // get client id from https://github.com/settings/apps
clientType: "github-app", // "github-app" | "oauth-app"
expirationEnabled: true, // true | false
},
});
const auth = await octokit.auth();
if (!auth) await octokit.auth({ type: "signIn" });
else console.log(await octokit.request("GET /user"));
</script>
createOAuthUserClientAuth(options)
or new Octokit({auth})
The createOAuthUserClientAuth
method accepts a single options
object as argument:
name | type | description |
---|---|---|
clientId |
string |
Required . Find Client ID on the app’s about page in settings. |
clientType |
string |
Required . Either "oauth-app" or "github-app" . |
expirationEnabled |
boolean |
Required . true or false for GitHub App. false for OAuth App. Set according to app settings. |
auth |
object |
Initial authentication object, defaults to null . See authentication object. |
defaultScopes |
string |
Only relevant for OAuth App. See available scopes. |
serviceOrigin |
string |
Defaults to location.origin . Required only when the @octokit/oauth-app Node.js/Express.js/Cloudflare middleware is deployed at a different origin. |
servicePathPrefix |
string |
Defaults to "/api/github/oauth" . Required only when the @octokit/oauth-app Node.js/Express.js/Cloudflare middleware is created with custom pathPrefix . |
authStore |
object or false
|
Custom store to get/set authentication object, false to disable persistence of authentication object. See custom store. |
stateStore |
object or false
|
Custom store to get/set state string, false to disable persistence of state string. |
request |
function |
You can pass in your own @octokit/request instance. For usage with enterprise, set baseUrl to the API root endpoint. See custom request
|
Custom Store
By default, octokit-auth-oauth-user-client.js
uses localStorage
to store JSON
serialized authentication object and state
string.
Pass authStore
or stateStore
in createOAuthUserClientAuth(options)
(or
new Octokit({auth})
) to use your custom code to persist authentication object
or state
string.
For example:
const authStore = {
get: async() => {
// return persisted authentication object when user is signed in;
// returns `null` when user is signed out
}
set: async(auth) => {
if (auth == null) { /* delete persisted authentication object */ }
else { /* create or update persisted authentication object */ }
}
}
const auth = createOAuthUserClientAuth({
clientId: "client_id",
authStore
});
Authentication Object
The async auth(options)
method returns to an authentication object. There are
three possible types of authentication object:
- 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 Apps -
refreshToken
,expiresAt
,refreshTokenExpiresAt
are only present for GitHub Apps, and only if token expiration is enabled
OAuth APP Authentication Object
name | type | description |
---|---|---|
type |
string |
"token" |
tokenType |
string |
"oauth" |
clientType |
string |
"oauth-app" |
clientId |
string |
Client id of the app |
token |
string |
The user access token |
scopes |
array of strings |
Array of scope names enabled for the token |
GitHub APP Authentication Object (Expiring Disabled)
name | type | description |
---|---|---|
type |
string |
"token" |
tokenType |
string |
"oauth" |
clientType |
string |
"github-app" |
clientId |
string |
Client id of the app |
token |
string |
The user access token |
GitHub APP Authentication Object (Expiring Enabled)
name | type | description |
---|---|---|
type |
string |
"token" |
tokenType |
string |
"oauth" |
clientType |
string |
"github-app" |
clientId |
string |
Client id of the app |
token |
string |
The user access token |
refreshToken |
string |
The refresh token |
expiresAt |
string |
Date in ISO 8601 format, e.g: 2011-10-05T14:48:00.000Z
|
refreshTokenExpiresAt |
string |
Date in ISO 8601 format, e.g: 2011-10-05T14:48:00.000Z
|
Development
Although targeting browsers, this module is written, tested, and bundled using Deno for its simplicity.
- test:
deno task test
- show coverage:
deno task coverage
- create npm package:
deno task build_npm x.x.x
- bundle using deno:
deno bundle mod.ts index.bundle.js
Contributing
See CONTRIBUTING.md