Have ideas to improve npm?Join in the discussion! »


    1.1.0 • Public • Published

    github-email-authentication NPM Version Node.js Version

    User authentication based on verified, primary Github account email addresses using Github OAuth.

    Allows the authentication process for either a known or any 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.


    • 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.


    const {GithubEmailAuthentication} = require('github-email-authentication');
    const {express} = require('express');
    const {CLIENT_ID, CLIENT_SECRET, PORT} = require('../some-config');
    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,
            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');
    app.post('loginExistingCustomer', (req, res) => {
        let {email} = req.query;
        console.log('Initiating github login for email %s', email);
        githubAuth.startLoginForEmail(email, res);


    Mandatory options see index.js.


    exposeAccessToken (default=false)

    Set this true if you need the access token for anything beyond the authentication process. Notice that the default scopes only allow read-access to the account email addresses.

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

    Define all scopes you'll want to use the access token for. Make sure read-access to the account email addresses is possible, otherwise authentication will fail.

    maxLoginProcessDuration (default=2 * 60 * 1000)

    The maximum duration (in millis) for which the state of a user returning from the login/authorization form at Github will be accepted. (Technically, the time after which a state can no longer be verified since the secret used for signing it got rotated out).

    logEnabled (default=false)

    Enable for local development only, since logged messages will contain email addresses and access tokens.





    npm i github-email-authentication

    DownloadsWeekly Downloads






    Unpacked Size

    24.1 kB

    Total Files


    Last publish


    • avatar