# Local

npm version Changelog

npm install @feathersjs/authentication-local --save

@feathersjs/authentication-local provides a LocalStrategy for authenticating with a username/email and password combination, e.g.

  "strategy": "local",
  "email": "hello@feathersjs.com",
  "password": "supersecret"

# Configuration

The following settings are available:

  • usernameField: Name of the username field (e.g. 'email')
  • passwordField: Name of the password field (e.g. 'password')
  • hashSize (default: 10): The BCrypt salt length
  • errorMessage (default: 'Invalid login'): The error message to return on errors
  • entityUsernameField (default: usernameField): Name of the username field on the entity if authentication request data and entity field names are different
  • entityPasswordField (default: passwordField): Name of the password field on the entity if authentication request data and entity field names are different

Standard local authentication can be configured with those options in config/default.json like this:

  "authentication": {
    "local": {
      "usernameField": "email",
      "passwordField": "password"

Important: If you want to set the value of usernameField to username in your configuration file under Windows or running the node process manager PM2 in Ubuntu/Linux, the value has to be escaped as \\username (otherwise the username environment variable will be used).

# LocalStrategy

Note: The methods described in this section are intended for customization purposes and internal calls. They usually do not need to be called directly.

# getEntityQuery(query, params)

localStrategy.getEntityQuery(query, params) -> Promise returns the query for finding the entity. query includes the usernameField or entityUsernameField as { [field]: username } and by default returns a promise that resolves with { $limit: 1 } combined with query.

# findEntity(username, params)

localStrategy.findEntity(username, params) -> Promise return the entity for a given username and service call parameters. It will use the query returned by getEntityQuery and call .find on the entity (usually /users) service. It will return a promise that resolves with the first result of the .find call or throw an error if nothing was found.

# getEntity(entity, params)

localStrategy.getEntity(authResult, params) -> Promise returns the external representation for entity that will be sent back to the client.

# hashPassword(password)

localStrategy.hashPassword(password) -> Promise creates a safe one-way hash of the given plain password string. By default bCryptJS is used.

# comparePassword(entity, password)

localStrategy.comparePassword(entity, password) -> Promise compares a plain text password with the hashed password of the entity returned by findEntity. Returns the entity or throws an error if the passwords don't match.

# authenticate(authentication, params)

localStrategy.authenticate(authentication, params) is the main endpoint implemented by any authentication strategy. It is usually called for authentication requests for this strategy by the AuthenticationService.

# Customization

The LocalStrategy can be customized like any ES6 class and then registered on the AuthenticationService:

    # Hooks

    # hashPassword(field)

    The hashPassword(field [, options]) hook should be used as a before hook for create, patch or update. It will replace the plain text field on data with a hashed password using LocalStrategy.hashPassword before storing it in the database.

    options is optional and may contain the following settings:

    • authentication (default: app.get('defaultAuthentication')): The name of the AuthenticationService the hook should use.
    • strategy (default: 'local'): The name of the LocalStrategy to use on the authentication service.

    # protect(...fields)

    The protect(...fields) hook removes fields from the data that is sent to the user by setting hook.dispatch.