Koas Security

Koas security checks if a request matches the security requirement of an operation. For example, given the following partial OpenAPI document:

components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
    cookieAuth:
      type: apiKey
      in: cookie
      name: key
    oauth2:
      type: oauth2
      scopes:
        email: Read the user’s email address.
        profile: Get the user’s profile.
paths:
  /me:
    get:
      security:
        - basicAuth: []
          cookieAuth: []
        - oauth2:
            - profile

Koas security will make sure the user is either authenticated using HTTP basic authentication and a cookie named key, or using OAuth2. The first authentication requirement specified in the document wins.

Installation

npm install koa koas-core koas-security

Usage

const Koa = require('koa');
const { koas } = require('koas-core');
const { security } = require('koas-security');

const api = require('./api.json');

const app = new Koa();
app.use(
  koas(api, [
    security({
      // User getters
    }),
  ]),
);

This middleware sets the users and clients variables in the Koa context. These are mappings of security requirements to authenticated users and OAuth2 clients respectively. Also user and client are set to match a single user and client. Since most API calls only require a single authentication method at a time, this can be used for convenience.

Options

Koas security takes a mapping of security requirement keys to user get functions. The signature depends on the type of authentication.

apiKey

The function accepts the API key, and should return the user that is authenticated using that key.

http

| scheme | Description | | -------- | ---------------------------------------------------------------------------------------------------------- | | basic | The function accepts the username and password, and should return the user that matches these credentials. | | bearer | The function accepts the bearer access token, and should return the user that matches these credentials. |

oauth2 / openIdConnect

The function accepts the access token, and should return a tuple which consists of the user and the authenticated OAuth2 client.

Declaring clients and users

When using TypeScript, the Clients and Users interfaces can be augmented to map security scheme to custom types. For example:

declare module 'koas-security' {
  interface Users {
    basicAuth: User;
    cookieAuth: User;
    oauth2: User;
  }

  interface Clients {
    oauth2: {
      type: 'oauth2';
      scopes: ('email' | 'profile')[];
    };
  }
}