# Local

npm version (opens new window) Changelog (opens new window)

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 (opens new window) 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.

    Anything unclear or missing? Get help (opens new window) or Edit this page (opens new window)

    Last Updated: 3/10/2021, 8:14:11 PM