Methods #

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

string

string

string

string

string

string

string

string

string

Even though each strategy must declare its own set of properties, the same strategy method can be used by multiple strategies.

create #

The create function adds credentials to a user.

For security reasons, plugins are entirely responsible of how credentials are managed, storage included: Kuzzle does not read, modify, or store credentials.

If needed, Kuzzle exposes a secure and isolated storage space for each plugin. It can be accessed using the Repository constructor.

Arguments #

create(request, credentials, kuid, strategy);

object

string

string

Returned value #

The create function must return a promise, resolving to an object. The content of that object depends on this authentication strategy; usually a feedback about the created credentials is expected. That object can be left empty.

delete #

The delete function deletes a user's credentials.

Arguments #

delete (request, kuid, strategy);

string

string

Returned value #

The delete function must return a promise. The resolved value is not used.

exists #

The exists function checks whether a user is known to the authentication strategy.

Arguments #

exists(request, kuid, strategy);

string

string

Returned value #

The exists function must return a promise, resolving to a boolean representing the result of the user existence check.

update #

The update function updates a user's credentials.

Arguments #

update(request, credentials, kuid, strategy);

object

string

string

Returned value #

The update function must return a promise, resolving to an object. The content of that object depends on this authentication strategy; usually a feedback about the updated credentials is expected. That object can be left empty.

validate #

The validate function verifies that credentials are well-formed.

Arguments #

validate(request, credentials, kuid, strategy, isUpdate);

object

string

string

boolean

Returned value #

The function validate must return a promise. The resolved value, if there is one, is ignored.

verify #

The verify function authenticates a user.

The number of arguments taken by the verify function depends on the authentication strategy. For instance, a local authentication strategy requires that the verify function validates both a user name and a password, so these two arguments will have to be provided to the verify function.

Arguments #

verify(payload, ...)

object

*

payload #

The payload object has the following properties:

object

object

Returned value #

The verify function must return a promise, resolving to an object with the following properties:

string

string

(optional) afterRegister #

The afterRegister function is called when the Passport.js strategy is instantiated by Kuzzle.

Arguments #

afterRegister(strategyInstance);

object

(optional) getById #

The getById function returns credentials information using the authentication strategy's user identifier (which may not be the kuid).

If this function is not implemented, an empty object is returned by Kuzzle instead.

Arguments #

getById(request, id, strategy);

string

string

Returned value #

The getById function must return a promise, resolving to an object containing credentials information. It can be left empty.

(optional) getInfo #

The getInfo function returns information about a user's credentials.

If this function is not implemented, an empty object is returned by Kuzzle instead.

Arguments #

getInfo(request, kuid, strategy);

string

string

Returned value #

The getInfo function must return a promise, resolving to an object containing credentials information. It can be left empty.

Example #

module.exports = class AuthenticationPlugin {
  constructor() {}

  /**
    Required plugin initialization function
    (see the "Plugin prerequisites" section)
   */
  init (customConfig, context) {
    this.authenticators = {
      StrategyConstructor: require('some-passport-strategy')
    };

    this.strategies = {
      '<strategy name>': {
        config: {
          // Must be declared in this.authenticators
          authenticator: 'StrategyConstructor',

          // The list of fields that have to be provided in the credentials
          fields: ['login', 'password']
        },
        methods: {
          create: 'create',
          delete: 'delete',
          exists: 'exists',
          update: 'update',
          validate: 'validate',
          verify: 'verify'
        }
      }
    };
  }

  /**
   * Stores the provided credentials
   * Must keep a link between the persisted credentials
   * and the kuid
   */
  create (request, credentials, kuid) {
    // store credentials
    return Promise.resolve({/* non sensitive credentials info */});
  }

  /**
   * Removes the user's stored credentials from
   * the plugin persistence layer
   */
  delete (request, kuid) {
    // remove credentials
    return Promise.resolve();
  }

  /**
   * Checks if user's credentials exist in the persistence layer
   */
  exists (request, kuid) {
    // check credentials existence
    return Promise.resolve(/* boolean value *);
  }

  /**
   * Updates the user's credentials information in the
   * persistence layer
   *
   * @param {KuzzleRequest} request
   * @param {object} credentials
   * @param {string} kuid
   * @returns {Promise<object>}
   */
  update (request, credentials, kuid) {
    // update credentials
    return Promise.resolve(/* non sensitive credentials info *);
  }

  /**
   * Validates credentials against the strategy rules
   * (required fields, password strength, username uniqueness, ...)
   */
  validate (request, credentials, kuid, strategy, isUpdate) {
    // validate credentials
    return Promise.resolve(/* true|false *);
  }

  /**
   * Returns an object with the authenticated user id if successful,
   * and a reason if the authentication fails
   */
  verify (request, ...credentials) {
    const kuid = /* authentification */;

    if (kuid) {
      return Promise.resolve({kuid});
    }

    return Promise.resolve({
      kuid: null,
      message: 'Login failed - You shall not pass! Reason: ...'
    });
  }
}