Get unlimited public & private packages + package-based permissions with npm Pro.Get started »

koa-cognito-middleware

1.4.2 • Public • Published

koa-cognito-middleware

Dependencies devDependencies NPM version

The Koa middleware to authenticate and authorized users using AWS Cognito user pools. It validates a JWT token (either an id or access token) and populates ctx.state.user with its deciphered content. Simple helpers are provided to make decisions on accessibility of API endpoints for a given user.

Examples

const Koa = require('koa');
const Router = require('koa-router');
const getUser = require('koa-cognito-middleware');
 
const {isAuthenticated, hasScope, hasGroup, isAllowed} = getUser;
 
const app = new Koa();
 
// run getUser() on every request
app.use(getUser({
  region: 'us-east-1',
  userPoolId: 'us-east-1_MY_USER_POOL'
}));
 
// populate router1 with custom authorization rules
 
const router1 = new Router();
 
router1.get('/a',
  async ctx => (ctx.body = 'all allowed'));
 
router1.get('/b', isAuthenticated,
  async ctx => (ctx.body = 'all authenticated'));
 
router1.post('/c', hasGroup('user-type/writers'),
  async ctx => (ctx.body = 'only a writers group'));
 
router1.post('/d', hasScope('writers'),
  async ctx => (ctx.body = 'only with a writers scope'));
 
app
  .use(router1.routes())
  .use(router1.allowedMethods());
 
// protect all routes with a single validator
 
const router2 = new Router();
// populate router2
 
const readMethods = {GET: 1, HEAD: 1, OPTIONS: 1};
 
const validator = async (ctx, groups, scopes) => {
  if (readMethods(ctx.method.toUpperCase()) === 1) return true;
  // only writers can use other methods (POST, PUT, PATCH, DELETE...)
  if (groups.some(g => g === 'user-type/writers')) return true;
  if (scopes.some(s => s === 'writers')) return true;
  return false;
};
 
app
  .use(isAllowed(validator))
  .get('/lift', async ctx => {
    const user = ctx.state.user;
    if (user) {
      user.setAuthCookie(ctx, {domain: 'api.my-domain.com'});
    }
    ctx.status = 204;
  })
  .use(router2.routes())
  .use(router2.allowedMethods());
 
// now all routes of router2 are protected by our validator

How to install

npm install --save koa-cognito-middleware
# yarn add koa-cognito-middleware

Documentation

All provided functions are explained below. See the examples above for usage patterns.

getUser(options)

This is the main function directly returned from the module. It populates ctx.state.user with a decoded JWT or assigns it to null (cannot positively authenticate). Other helpers or a user's code uses it to authorize or reject the user for a given route.

Additionally if an authenticated user it adds the following properties:

  • _token — the original JWT.
  • setAuthCookie(ctx, options) — a function, which when called with ctx argument sets a cookie specified by authCookie (see below) to _token. The optional options argument is an object compatible with options for cookie.set(). By default the cookie is set with following options:
    • expires — an expiration time of a JWT.
    • domain — a value of ctx.host.
    • overwritetrue. options will overwrite/augment those values.

getUser(options) takes one argument options, which is an object with the following properties:

  • regionrequired string, which specifies an AWS region, such as 'us-east-1'. Default: none.
  • userPoolIdrequired string, which specifies a user pool ID, such as 'us-east-1_MY_USER_POOL'. Default: none.
  • authHeader — optional string. Default: 'Authorization'. It specifies an HTTP request header name. Its value should be a JWT supplied by AWS Cognito (id_token or access_token).
  • authCookie — optional string. Default: 'auth'. It specifies an HTTP request cookie name. Its value should be a JWT supplied by AWS Cognito (id_token or access_token).
  • source — optional function. Default: reads authHeader header and returns it, if it is not falsy, otherwise reads authCookie cookie and returns it, if it is not false, otherwise returns null. If it is a function, it is called with ctx argument, and can inspect a request to produce a JWT token as a string.
    • Examples:
      const getToken1 = ctx => ctx.headers['x-auth-header'];
      const getToken2 = ctx => ctx.cookies.get('auth-token');
  • setAuthCookieOptions — optional object compatible with options for cookie.set(). If it is null (the default), a cookie is not set automatically. Otherwise, it is set every time it is not set or has a different value. When a cookie is set, setAuthCookieOptions is used to overwrite/augment the default options described above in setAuthCookie().

This function should be used before any other helpers.

getUser.isAuthenticated

This is a helper function, which checks if ctx.state.user is set. If not it rejects a request with 401 (unauthorized).

getUser.hasGroup(group)

This is a helper function, which checks if ctx.state.user has 'cognito:groups' array that includes a given group (as a string). If not it rejects a request with 403 (forbidden) for valid users and 401 (unauthorized) for non-authenticated users.

getUser.hasScope(scope)

This is a helper function, which checks if ctx.state.user has 'scope' string that includes a given scope (as a string). If not it rejects a request with 403 (forbidden) for valid users and 401 (unauthorized) for non-authenticated users.

getUser.isAllowed(validator)

This is a helper function, which checks runs a validator. If not it rejects a request with 403 (forbidden) for valid users and 401 (unauthorized) for non-authenticated users.

validator is an asynchronous function, which is called with three parameters: the original ctx, groups and scopes. The latter two parameters are arrays of strings listing cognito:groups and scope items respectively. validator should return a truthy value, if a user is allowed to perform an action, and a falsy value otherwise.

Versions

  • 1.4.2 — More bugfixes
  • 1.4.1 — Bugfixes
  • 1.4.0 — Added support for an auth cookie
  • 1.3.0 — Split off the common functionality to cognito-toolkit
  • 1.2.0 — Added a utility to lazily retrieve an access token by client ID and a secret
  • 1.1.0 — Added a utility to auto-retrieve an access token by client ID and a secret
  • 1.0.0 — The initial public release

License

The 3-Clause BSD License

Install

npm i koa-cognito-middleware

DownloadsWeekly Downloads

24

Version

1.4.2

License

BSD-3-Clause

Unpacked Size

10.9 kB

Total Files

6

Last publish

Collaborators

  • avatar