github-email-authentication

User authentication based on a Github account's verified, primary email address using Github OAuth.

Each authentication process can be started for either a known email address or any Github account's email address (as long as it's the primary, verified email address). Upon successful authentication, the Github account's primary, verified email address and, optionally, the access token are passed to a given success handler. When authentication is started for a known email address, that address is expected to be the logged-in Github account's primary, verified email address, otherwise authentication fails.

Requirements

Node 14+
Express (or similar, it's up to you)
Your Github OAuth app providing Client ID and Client secret.
See: https://github.com/settings/developers

Security

Using signed values for the state parameter (HMAC-SHA256), unique for each started login process and verified before accepting any authorization code. Also, state expires after max. 2 minutes by using rotating secrets for signing.
Login processes started for a known email address will succeed only if that email address is really the Github account's primary, verified email.
Github accounts with no verified, primary email addresses are rejected in all cases.

Usage

import {GithubEmailAuthentication} from 'github-email-authentication';
import express from 'express';

import {CLIENT_ID, CLIENT_SECRET, PORT} from './app-config.js'; 

const app = express();

const githubAuth = new GithubEmailAuthentication({
        appOrRouter: app,
        routableCallbackUri: '/loginCallback',
        absoluteCallbackUrl: `https://my-domain.tld:${PORT}/loginCallback`,
        githubClientId: CLIENT_ID,
        githubClientSecret: CLIENT_SECRET,
        exposeAccessToken: false,
        maxLoginProcessDuration: 2 * 60 * 1000,
        onSuccess: (validatedPrimaryEmail, accessToken, req, res, next) => {
            // (1) `validatedPrimaryEmail` is never empty here
            // (2) `accessToken` is null here due to `exposeAccessToken: false`
            
            // TODO check who logged in & put customer into session or so
            
            res.redirect(302, '/account');
        },
        onError: (message, res, next) => {
            console.warn('Login failed, reason: %s', message);
            res.status(403).send('Login failed. Reason: ' + message);
        }
    });

app.post('/loginNewCustomer', (req, res) => {
    console.log('Initiating github login for any account');
    githubAuth.startLoginForUnknown(res);
});

app.post('loginExistingCustomer', (req, res) => {
    let {email} = req.query;
    console.log('Initiating github login for email %s', email);
    githubAuth.startLoginForEmail(email, res);
});

Options

Properties of the opts object for new GithubEmailAuthentication(opts):

Param	Type	Description
appOrRouter	`Express` \| `Router`	some Express app or router
routableCallbackUri	`string`	e.g. '/githubCallback', this route will be added to the given `appOrRouter` to receive authorization codes
absoluteCallbackUrl	`string`	the absolute URL for the redirect from Github OAuth login, so basically the absolute URL for the `routableCallbackUri`. (!) Must equal the "Authorization callback URL" defined in your OAuth App's settings on Github, see https://github.com/settings/developers.
githubClientId	`string`
githubClientSecret	`string`
[scopes]	`string[]`	scopes for the access token (default: `['user:email']`); If given, the scopes must allow read-access to the user's Github email addresses ('user:email'), otherwise authentication will fail.
[exposeAccessToken]	`boolean`	if true, the access token will be passed to the `onSuccess` callback, otherwise `null` is passed as token (default: false)
[maxLoginProcessDuration]	`number`	the max. time in millis from initiating a login and the time an authorization token is passed to the `routableCallbackUri` callback. Essentially the time users have to enter their Github credentials and authorize the app to access their email addresses. Technically, the time after which a `state` can no longer be verified since the secret used for signing it got rotated out. (default: 2601000, i.e. 2 minutes)
onSuccess	function	see `GithubEmailAuthentication_SuccessHandler`
onError	function	see `GithubEmailAuthentication_ErrorHandler`
[logEnabled]	`boolean`	if true, errors/warning will be logged to the console (default: false). (!) Logged messages may contain sensitive data like email addresses.

Notes

`exposeAccessToken` (default=false)

Set this true if you need the access token for anything beyond the authentication process.

`scopes` (default=`['user:email']`)

The default scope only allows read-access to Github accounts' email addresses. Add any scopes you want to use the access token for beyond authentication (requires exposeAccessToken set true). With custom scopes, make sure read-access to account email addresses remains possible, otherwise authentication will fail.