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')

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

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.


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

Arguments Type Description
One of the exposed authenticators name
(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