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:

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
`config`	object	Authentication strategy configuration
`methods`	object	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:

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
`authenticator`	string	One of the exposed authenticators name
`constructor`	object	Deprecated since 1.4.0 (use the `authenticator` property instead) The constructor of the Passport.js strategy. Does not support dynamic strategy registration
`authenticateOptions`	object	(optional) Additional options to be provided to the Passport's authenticate method
`fields`	string[]	(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
`strategyOptions`	object	(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

Edit this page on Github