oauth-client-github

🔐 OAuth 2.0 client for GitHub

Give a ⭐️ if this project helped you!

Preview 🎉

https://oauth-client-github-demo.vercel.app/

💡 Source code of this app in demo/ directory.

Installation

npm install oauth-client-github

Usage

// server.js
const oauthClientGitHub = require("oauth-client-github");

const githubAuth = oauthClientGitHub.init({
  client_id: "",
  client_secret: "",
  redirect_uri: "<host>/auth/callback",
  scope: "", // user, repo, gist, notifications, read:org, etc.
});

app.get("/auth", async (req, res) => {
  const state = req.headers.referer;
  const url = await githubAuth.buildTemporaryTokenUrl({ state });
  // Redirect to GitHub OAuth page to authorize a user
  res.redirect(url);
});

app.get("/auth/callback", async (req, res) => {
  const { code, state } = req.query;
  const response = await githubAuth.requestAccessToken({ code });
  // Create a cookie to use it on the client-side
  res.cookie("token", response.access_token);
  res.redirect(state ? String(state) : "/");
});

// client.js
const access_token = document.cookie.split("=")[1];

const response = await fetch("https://api.github.com/user", {
  headers: {
    Authorization: `Bearer ${access_token}`,
  },
});
const user = await response.json();
console.log({ user }); // A user with private data! 🎉

Specification

Sequence diagram with the OAuth 2.0 flow for GitHub is defined in docs/ directory.

Prerequisites: Create new OAuth App

1. Open a page: https://github.com/settings/developers and click on the "New OAuth App"
2. Fill the form:

• Application name (required)
  • eg. oauth-client-github
  • TIP: it will be visible only for you
• Homepage URL (required)
  • eg. https://example.com
  • TIP: it will be visible only for you
• Application description (optional)
• Authorization callback URL (required)
  • eg. http://localhost:3000/auth/callback
  • TIP: you need to put real URL to your app
  • ⚠️ This field will be cross-checked with your param redirect_uri
• Enable Device Flow (optional)

3. Generate a new client secret by clicking on the "Generate a new client secret"
4. Copy secret and save to config file (like .env):
   • Client ID
   • Client Secret

Parameters

• client_id - GitHub App Client ID
• client_secret - GitHub App Client Secret
• redirect_uri - URL to redirect after authorization
• scope - List of scopes separated by comma
• state - Random string to prevent CSRF attacks (optional)
  • Or it could be a referer to redirect user to the same page after authorization
• code - Temporary code to exchange to the access token
• access_token - Access token to make requests to GitHub API

Development

# to rebuild dist/ & types/
npm run watch # or `npm run build` to build once

# to rebuild demo/dist/
cd demo/
npm run dev

Resources

• GitHub Docs: App creation guide
• GitHub Docs: Scopes definition

License

The MIT License @ 2024