@tygr/auth-server

This package has moved to @taylorgrinn/auth-server

Tygr Auth Server Middleware

This is an express middleware and router to be used with the @tygr/auth react component.

Installation

npm i --save @tygr/auth-server
yarn add @tygr/auth-server

Add the middleware and router to your app

import bodyParser from 'body-parser';
import express from 'express';
import useAuth from '@tygr/auth-server';

const [authMiddleware, authRouter] = useAuth({
  // Provide a secret key or list of keys to use for creating sessions.
  secret: 'ssshhh',
  // In order to implement the reset password form, use this option to send
  // an email using nodemailer or another email solution. Must return a promise
  async sendCode(email, code) {
    console.log(`Emailing code: ${code} to ${email}`);
    /* Implementation not shown */
  },
  delay: 1000, // Add an optional delay to all authentication requests. Useful for preventing brute force attacks from a single IP or just letting users appreciate your loading screens.
});

const app = express();
export default app;

app.use(
  bodyParser.json(), // JSON necessary to parse requests from the @tygr/auth react component
  authMiddleware
);

app.use('/auth', authRouter);

This is all the setup you need for a minimal working example with local login, register, and reset password functionality.

Setup the external providers (Google, Github, Facebook)

Create API keys for each or any of the services:

• Google
• Github
• Facebook

Add the keys, as well as the external location of your authentication server, to the useAuth options:

const [authMiddleware, authRouter] = useAuth({
  ...,
  authBaseUrl: 'https://tygr.info/api/auth', // Used for callbacks after authentication
  google: {
    clientId: 'blahblahblah',
    clientSecret: 'blahblahblah',
    scope: [], // Optional: scopes allow you to get more user information
  },
  github: {
    clientId: 'blahblahblah',
    clientSecret: 'blahblahblah',
    scope: [], // Optional: scopes allow you to get more user information
  },
  facebook: {
    clientId: 'blahblahblah',
    clientSecret: 'blahblahblah',
    scope: [], // Optional: scopes allow you to get more user information
    profileFields: [] // Optional: profile fields need to be specified for user object
  }
});

...

/**
 * Make sure to include the pathname you decide to use here ('/auth')
 * in the `authBaseUrl` option above.
 */
app.use('/auth', authRouter)

For the scope options, the email scope is already included in all authentication requests by default for both github and google.

When creating the keys for each provider, you'll also have to specify the callback urls in this format:

• Google: `${authBaseUrl}/google/callback`
• Github: `${authBaseUrl}/github/callback`
• Facebook: `${authBaseUrl}/facebook/callback`

Setup better storage options

By default, the sessions and user data are stored in-memory. This is volatile and not recommended for production use. You may pass in a store for the sessions and a Users model for storing users.

The store interface is described here in the express-session library.

The Users interface defines what will probably be static methods on your Users' model class. I designed it specifically to work with sequelize right out of the gate, but it can be adapted for any storage mechanism you'd like. There are five methods to implement and four required fields on the User object.

---

BaseUser (You may add any other properties you'd like)

property	type	description
id	string	Unique identifier generated by uuid. This should be the 'primary key'
email	string	Unique email address for each user.
password	string (or undefined)	Hashed password for the user if they signed in locally
provider	string	The authentication method (either 'local', 'google', or 'github')

---

BaseUsers

method	param	returns	description
create	User	Promise<User>	Create a new user. No need to check if the user already exists. For sequelize, no setup is necessary as the base model includes this method with the correct signature, given that the model extends the BaseUser interface correctly
findByEmail	string	Promise<User | null>	Find a user account by an email address
findAndUpdate	User	Promise<any>	Find a user using the id, which will not change, and update the rest of the user properties
findAndDestroy	User	Promise<any>	Find a user using either the id or email then delete them
sanitize	User	Partial<User>	Synchronously create a user object that is safe to be sent back to the user. The password hash should be removed at least

All Options

Order of precedence: env var > option > default
Array environment variables are comma separated: MY_VAR=thing1,thing2

option	required	env var	type	description
secret	required	AUTH_SECRET	string | string[]	Provide a secret key or list of keys to use for creating sessions
sendCode	required		(emailAddress: string, code: string) => Promise<any>	Send a reset code to a specified email address. The user can then copy this code into the reset password form to recover access to their account
store	recommended		See here	Provide a store to use for session data. Defaults to an in memory store which is not recommended for a production environment
Users	recommended		See above	Provide a Users model to store user data. Defaults to an in memory Users model which is not recommended for a production environment
delay	optional	AUTH_DELAY	number	Milliseconds to delay each request to the auth server.
cors	optional	CORS	boolean (string[] if using env var)	Set the cookie properties: sameSite: true, secure: true. This will allow cookies to be loaded from any domain and requires the authentication server to be served over https. See the demo folder for an example of serving https://localhost using custom certificates. See below for more info
httpOnly	optional	HTTP_ONLY	boolean	Whether the cookie willl have the httpOnly flag. True, by default.
authBaseUrl	optional	AUTH_BASE_URL	string	The external address of your authentication server. This option is required for an identity provider like google or github to redirect users back after signing in but not for local sign in, register or reset password
google.clientID	required for google	GOOGLE_CLIENT_ID	string	Client ID given by Google.
google.clientSecret	required for google	GOOGLE_CLIENT_SECRET	string	Client secret given by Google.
google.scope	optional	GOOGLE_SCOPE	string[]	Scope of information or abilities to be requested by you to the user for their Google account. The 'email' scope is added to all requests in addition to any you specify here
github.clientID	required for github	GITHUB_CLIENT_ID	string	Client ID given by Github.
github.clientSecret	required for github	GITHUB_CLIENT_SECRET	string	Client secret given by Github.
github.scope	optional	GITHUB_SCOPE	string[]	Scope of information or abilities to be requested by you to the user for their Github account. The 'user:email' scope is added to all requests in addition to any you specify here
facebook.clientID	required for facebook	FACEBOOK_CLIENT_ID	string	Client ID given by Facebook.
facebook.clientSecret	required for facebook	FACEBOOK_CLIENT_SECRET	string	Client secret given by Facebook.
facebook.scope	optional	FACEBOOK_SCOPE	string[]	Scope of information or abilities to be requested by you to the user for their Facebook account. The 'email' scope is added to all requests in addition to any you specify here
facebook.profileFields	optional	FACEBOOK_PROFILE_FIELDS	string[]	Profile fields to include when authenticating. The 'email' field is added to all requests in addition to any you specify here

Setup cors for cross-domain authentication

If your authentication server is on a different domain than your client, or you have multiple clients logging in to the same authentication server, you can use the cors middleware and the cors option:

import useAuth, { cors } from '@tygr/auth-server';


const [authMiddleware, authRouter] = useAuth({
  ...,
  cors: true,
});

app.use(cors('https://tygr.info', 'http://localhost:8081'));

The cors middleware takes in any number of whitelisted domains and adds the relevant headers to all requests from each of them.

The cors option changes the way cookies are set. Specifically, it makes them available on any domain and makes them secure, only available when the authentication server is served over https. Check out the demo folder to see an example of serving https://localhost with a self-signed certificate.

If the CORS environment variable is set, the cors options will be set to true and the whitelist will be set to the comma-separated list value of the CORS environment variable:

# .env file (or however you set env vars)
CORS=https://tygr.info,http://localhost:8081

/**
 * You still have to use the cors middleware but the whitelist
 * will be supplied by the environment variable
 */
app.use(cors());