Authorization

Overview

Authorization plugins or provider methods add a security layer to Koop. There are some important facts to understand when working with authorization on a Koop instance:

• Authorization can be implemented on individual providers or across multiple providers with a Koop authorization plugin. Plugin implementation is useful if authorization rules do not vary by provider.

• Providers may implement authorization by defining authorize and authenticate methods on the model class. These methods will override those (authorize and authenticate methods) defined by any authorization plugin.

• Authorization plugin define authorize and authenticate methods which are bound to a provider’s model class if that class does have such methods already defined. Therefore, registration order is important. For a provider to use a authorization plugins methods, it must be registered after the auth-plugin registration.

• An authorization method (whether provider or plugin) is only effective for securing routes generated by output service plugins (a.k.a., plugin-routes) that leverage a provider-model’s “pull” methods (pull, pullLayer, pullCatalog, or pullStream). Custom routes defined by the provider will only be secured if the (1) use a model’s pull method or (2) invoke the model’s authorization modelnot be secured by registering an authorization plugin.

Authorization-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('@koopjs/koop-core')
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 required 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)

Plugin registration order

The order in which you register your providers and authorization plugins will affect functionality. The key points are:

• Providers registered before the authorization plugin will not be secured unless they define their own authorize method
• Providers registered after the authorization plugin will be secured by (1) their own authorize method if defined on model class or (2) the authorization plugin’s authorize method.

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 and its model does not define an authorize method..