Authorization Specification

Overview

Authorization plugins add a security layer to Koop. There are few important facts to understand when using an authorization plugin:

  • An authorization plugin is only effective for securing routes generated by output service plugins (a.k.a., plugin-routes). Custom routes defined by the provider will not be secured by registering an authorization plugin.

  • Successfully securing your plugin-routes depends on authorization support from any output-plugins you may be using. By default, Koop includes koop-output-geoservices (a.k.a. feature service output), which supports securing services with authorization plugins.

  • Authoriztion plugins should be registered after output-services plugins and before providers. Any providers registered before an authorization plugin will not have its plugin routes secured.

Dive into the docs below or check out an existing auth plugin as well as its interface in Koop’s default geoservices output plugin.

Usage

Usage of an authorization-plugin can be conceptually divided into three parts: (1) configuration, (2) registration with Koop, and (3) use in output-services. An example using koop-auth-direct-file provides the best illustration of usage.

// Initialize Koop
const Koop = require('koop')
const koop = new Koop()

// Koop has already added koop-output-geoservices (i.e. FeatureServer routes) by default
// Add any other output plugins here

// Configure the auth plugin by executing its exported function with requried args
const auth = require('@koopjs/auth-direct-file')('pass-in-your-secret', `path/to/identity-store`)

// Register any providers you want to omit from koop auth
const github = require('@koopjs/provider-github')
koop.register(github)

// Register the auth plugin
koop.register(auth)

// Register any providers you want secured by koop auth
const s3Select = require('@koopjs/provider-s3-select')
koop.register(s3Select)

In the above implementation, the authorization plugin would be applied to feature server routes for the S3 Select provider. Note that the routes for the Github provider would not be protected because the auth plugin registration occurs after the Github provider registration.

Authorization plugin specification

index.js and the registration object

Each authorization plugin must have a file called index.js. index.js must be able to deliver a a Koop registration object. This object should have the following minimum content:

{
    type: 'auth',
    authenticationSpecification: Function,
    authenticate: Function,
    authorize: Function
}

The object above may be assigned to module.exports directly; alternatively, module.exports may be assigned an initialization function that returns the registration object on execution. This approach is useful if you need to pass options into the authentication plugin (see an example).

The table below contains a brief description of the registration object. Note that the listed functions make up authorization plugin’s API. Koop adds these functions to each provider’s Model prototype, which makes them available in output plugins.

property type description
type String Must be set to auth; identifies the plugin as an authorization plugin during registration
authenticationSpecification Function Returns an object with data useful for configuring the authorization plugin with output plugins.
authorize Function Verfies a user has authorization to make a requests (e.g., a token is validated)
authenticate Function Authenticates a user’s requests based on submitted input (credentials, key, etc)

Details about each of the API functions are found below.

authenticationSpecification function() ⇒ object

Authorization plugins must include a function called “authenticationSpecification”. Its purpose is delivery of an object (i.e., the authentication specification) that provides options to the output-plugin. The object returned need only contain data for properly configuring your output plugins of choice. For example, Koop’s default geoservices uses a useHttp option when generating the authentication endpoint. An example of authenticationSpecification is available here.

authenticate authenticate(req) ⇒ Promise

Param Type Description
req object Express request object. Credentials for authentication should be found in the query object.

Authorization plugins must include a function called authenticate that returns a promise. Its purpose is to validate credentials and, if successful, issue a token for authorizing subsequent resource requests. If the authentication is unsuccessful the promise should reject with an error object. The error should have a code property with value 401. If the authentication is successful, the promise should resolve an object with the following properties:

{
  token: String, // token that can be added to resource requests, and decoded and verified by the "authorization" function
  expires: Number, // number seconds until token expires
}

Authorization plugins are free to validate credentials in any manner. For example, you might check a database for a match of the submitted username and password, or forward the credentials on to a third-party identity-store. koop-auth-direct-file provides an example of a very basic credential validation using a simple JSON file-store.

authorize function authorize(req) ⇒ Promise

Param Type Description
req object Express request object. Query parameter or header should include input (e.g., token) that can be used to prove previously successful authentication

Authorization plugins are required to implement a function called authorize. It should accept the Express request object as an argument, which that can be used to verify the request is being made by an authenticated user (e.g., validate a token in the authorization header). If the authorization is unsuccessful, the promise should reject with an error object that contains a 401 code. Successful authorization should allow the promise to resolve. An example of an authorize function can be viewed here.


Improve this page