https://github.com/justlep/github-email-authentication
User authentication based on verified, primary Github account email addresses using Github OAuth
https://github.com/justlep/github-email-authentication
authentication email github oauth
Last synced: about 1 year ago
JSON representation
User authentication based on verified, primary Github account email addresses using Github OAuth
- Host: GitHub
- URL: https://github.com/justlep/github-email-authentication
- Owner: justlep
- License: mit
- Created: 2018-10-26T16:05:00.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2024-10-24T06:57:28.000Z (over 1 year ago)
- Last Synced: 2024-10-25T02:18:24.017Z (over 1 year ago)
- Topics: authentication, email, github, oauth
- Language: JavaScript
- Size: 149 KB
- Stars: 2
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# github-email-authentication [![NPM Version][npm-image]][npm-url] [![Node.js Version][node-version-image]][node-version-url]
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 16+
* 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](https://github.com/justlep/keygrip-autorotate)
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
```javascript
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: 2\*60\*1000, i.e. 2 minutes) |
| onSuccess | function | see [GithubEmailAuthentication\_SuccessHandler](#GithubEmailAuthentication_SuccessHandler) |
| onError | function | see [GithubEmailAuthentication\_ErrorHandler](#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.
### GithubEmailAuthentication\_ErrorHandler : function
| Param | Type |
| --- | --- |
| errorMessage | string |
| response | Response |
| [next] | function |
### GithubEmailAuthentication\_SuccessHandler : function
| Param | Type |
| --- | --- |
| validatedPrimaryEmail | string |
| accessToken | ?string |
| request | Request |
| response | Response |
| [next] | function |
## Credits
* [github-oauth](https://github.com/maxogden/github-oauth) for the inspiration
## License
[MIT](./LICENSE)
[npm-image]: https://img.shields.io/npm/v/github-email-authentication.svg
[npm-url]: https://npmjs.org/package/github-email-authentication
[node-version-image]: https://img.shields.io/node/v/github-email-authentication.svg
[node-version-url]: https://nodejs.org/en/download/