Write Plugins v1.x

You are currently looking at the documentation of a previous version of Kuzzle. We strongly recommend that you use the latest version. You can also use the version selector in the top menu.

Strategies #

Plugins can add new authentication strategies to Kuzzle. For example, our official OAUTH2 Authentication plugin adds OAUTH2 support to Kuzzle.

All authentication strategies supported by Passport.js can be integrated to Kuzzle.

Exposing authenticators #

Passport.js provides a wide range of authentication strategies. Custom authentication strategies can also be implemented by subclassing the abstract Passport Strategy class.

To register strategies to Kuzzle, a authenticators object property must be exposed by the plugin, for instance:

Copied to clipboard!
this.authenticators = {
  Local: require('passport-local'),
  Oauth2: require('passport-oauth2')

Register a new strategy #

There are two ways of registering new strategies:

  • statically, by exposing a strategies object
  • dynamically, by using the dedicated strategy accessors

Whether strategies are added statically or dynamically, the registered strategy must expose the following properties:

Arguments Type Description
Authentication strategy configuration
List of exposed methods

statically register strategies #

Plugins can declare a strategies object which contains the authentication strategies to register.
This object will be interpreted by Kuzzle only once, immediately after this plugin's init function has resolved.
Each key of this object is the name of the strategy to register and the value is the strategy object containing config and methods properties.

For example, to register a strategy named local with the Local authenticator:

Copied to clipboard!
this.authenticators = {
  Local: require('passport-local')

this.strategies = {
  local: {
    config: {
      authenticator: 'Local'
    // these methods must be exposed by the plugin 
    methods: {
      create: 'create',
      delete: 'delete',
      exists: 'exists',
      getById: 'getById',
      getInfo: 'getInfo',
      update: 'update',
      validate: 'validate',
      verify: 'verify'

dynamically register strategies #

Strategies can be register at runtime with the strategies.add method.

Strategies added dynamically in the plugin's init method are added to the static strategies object and loaded by Kuzzle after the plugin initialization.

config #

The config part of the strategies object can contain the following properties:

Arguments Type Description
One of the exposed authenticators name
Deprecated since 1.4.0
(use the authenticator property instead)
The constructor of the Passport.js strategy. Does not support dynamic strategy registration
(optional) Additional options to be provided to the Passport's authenticate method
(optional) The list of accepted field names by the strategy credentials.
The list is informative only, meant to be used by the getAllCredentialFields and the getCredentialFields API methods
(optional) Options provided to the Passport.js strategy constructor

Credentials security #

User credentials are very sensitive data, and these must be properly isolated to prevent security vulnerabilities. To do so, Kuzzle guarantees that it never interprets, modifies, or stores credentials information.

Instead, Kuzzle:

  • provides a global user unique identifier (referred from now on as the user's kuid), giving the possibility to a user to authenticate with multiple strategies
  • entrusts implemented strategies with credentials protection, validation, verification and storage