@codealpha/oauth2

AuthN

Faux IAM.

reference material:

• OAuth2 Authorization framework.
• PAR Auth flow: Pushed Authorization Request
• PKCE Additional security: Proof-Key for Code Exchange.
• Authorization Code Auth Grant Type.
• Bearer Token Authentication usage mechanism.

Installation

npm i @codealpha/oauth2 --save

Example

import {oauth} from '@codealpha/oauth2'
const oauthConfig = {...}

const Server = async () => {
  const { authN, authZ } = await oauth(oauthConfig);

  app
    .use(express.static(path.join(__dirname, "public")))
    .use("/auth", authN)
    .use("/private/stuff", [
      authZ,
      (req, res) => {
        res.send({ message: "welcome VIP", data: ["a", 2, { b: true }] });
      },
    ])
    .listen(5000, () => {
      console.log(`OAuth2 Server started at http://localhost:5000`);
    });
};

Usage

authN

.use("/auth", authN)

"/ui":

• AS User Interface

"/client":

• data about the website using the AS

"/user/whoami":

• user object

authZ

.use("/private/stuff",
      authZ,
      (req, res) => {
        res.send({ message: "welcome VIP", data: ["a", 2, { b: true }] });
      },
    )

ClientSide Callback workflow

Post login:

1. client website recieves authCode.
2. client website exchanges authCode for authToken.
3. client website uses authToken to make API requests.

Configuration

const oauthConfig = {
  database: {
    type: "postgres",
    config: {
      user: "DATABASE_USERNAME",
      host: "DATABASE_HOST",
      password: "DATABASE_PASSWORD",
      port: 5432,
    },
  },
};

key	Description	Default
awsCredentialsPath	the absolute file path to the AWS credentials.json file
mfaRequired	a SMS code is required on login in addition to a username/password.	false
emailSalt	a bcrypt salt used to encrypt data at rest	no encryption
database *
database.type	type of database	[string]
database.config	configuration object specific to a database	[Object]
client
client.name	name of website using OAuth2	'OAuth2Placeholder'
client.website	fqdn of website using OAuth2	'OAuth2Placeholder'
client.badgeUrl	url of brand image used to customize OAuth2 pages
registrationWhitelist	only allow a defined list of usernames to register	any

Running Example (dev mode)

Authentication Server UI

1. Start client
   1. cd to /client
   2. run:

      npm start

Build server & end-user functions

2. Setup initial builds and watch for changes.
   1. from project root
   2. run:

      npm run cli start

Example end-user application

3. Start Example
   • make sure your postgres database is up and running.
   • fill in correct environment variables
   1. from project root
   2. run:

      npm run cli example

Publishing npm module.

1. Create NPM granular access token. StackOverflow ref
   1. run:

      npm config set _authToken=GRANULAR_ACCESS_TOKEN

      • if you get an error like Invalid auth configuration found: '_authToken' must be renamed to '//registry.npmjs.org/:_authToken' in user config.
      1. run:

         npm config fix

2. Publish to NPM.
   1. from project root
   2. run:

      npm run publishit