Authentication Configuration

Configure JWT authentication, local authentication, and OAuth providers in Feathers

Authentication configuration controls how users authenticate with your Feathers application. It supports JWT tokens, local authentication (email/password), and OAuth providers.

Configuration Location

Authentication settings are stored in config/default.json and generated when you run the authentication generator:

feathers generate authentication

Authentication Schema

The authentication configuration can be validated using schemas:

TypeBox

import { Type } from '@feathersjs/typebox'

export const authenticationSettingsSchema = Type.Object({
  secret: Type.String({ description: 'The JWT signing secret' }),
  entity: Type.Optional(
    Type.Union([
      Type.String({ description: 'The name of the authentication entity (e.g. user)' }),
      Type.Null()
    ])
  ),
  entityId: Type.Optional(Type.String()),
  service: Type.Optional(Type.String()),
  authStrategies: Type.Array(Type.String()),
  jwtOptions: Type.Optional(Type.Object({})),
  local: Type.Optional(
    Type.Object({
      usernameField: Type.String(),
      passwordField: Type.String()
    })
  )
})

export const authenticationSettingsSchema = {
  type: 'object',
  required: ['secret', 'entity', 'authStrategies'],
  properties: {
    secret: {
      type: 'string',
      description: 'The JWT signing secret'
    },
    entity: {
      oneOf: [
        { type: 'null' },
        { type: 'string' }
      ],
      description: 'The name of the authentication entity (e.g. user)'
    },
    authStrategies: {
      type: 'array',
      items: { type: 'string' }
    }
  }
} as const

Core Settings

authentication.secret · string · required

The secret key used to sign and verify JWT tokens. This should be a long, random string.

Environment Variable: FEATHERS_SECRET

Security: Never commit this to version control. Always use environment variables in production.

Example: Generated automatically as a 32-character base64 string

authentication.entity · string | null

The name of the entity (e.g., ‘user’) that is authenticated. Set to null for no entity.

Default: The service name (e.g., user)

authentication.entityId · string

The name of the id property on the entity.

Default: id (or _id for MongoDB)

authentication.service · string

The path of the service that provides the authentication entity.

Example: users

authentication.authStrategies · string[] · required

List of authentication strategy names that are allowed to create JWT access tokens.

Default: ['jwt', 'local']

Common values: jwt, local, google, github, facebook, twitter, auth0

authentication.parseStrategies · string[]

List of strategy names that should parse HTTP headers for authentication information.

Default: Same as authStrategies

JWT Settings

authentication.jwtOptions · object

Options passed to the JWT library for token generation and verification.

Show properties

authentication.jwtOptions.header · object

Header claims for the JWT token.

Show properties

authentication.jwtOptions.header.typ · string

Token type.

Default: access

authentication.jwtOptions.audience · string

The intended audience for the token.

Example: https://yourdomain.com

authentication.jwtOptions.algorithm · string

The signing algorithm to use.

Default: HS256

Options: HS256, HS384, HS512, RS256, etc.

authentication.jwtOptions.expiresIn · string

How long the token is valid.

Default: 1d (1 day)

Format: Use strings like 2h, 7d, 30m

authentication.jwt · object

Configuration for JWT parsing from HTTP headers.

Show properties

authentication.jwt.header · string

The HTTP header containing the JWT.

Default: Authorization

authentication.jwt.schemes · string[]

Array of authentication schemes to support.

Default: ['Bearer', 'JWT']

Local Authentication Settings

authentication.local · object

Configuration for email/password authentication.

Show properties

authentication.local.usernameField · string · required

The field name for the username (typically email).

Default: email

authentication.local.passwordField · string · required

The field name for the password.

Default: password

authentication.local.hashSize · number

The BCrypt salt length for password hashing.

Default: 10

authentication.local.errorMessage · string

The error message returned on authentication failure.

Default: Invalid login

authentication.local.entityUsernameField · string

Name of the username field on the entity if different from the request field.

Use case: When the entity stores email but authentication expects username

authentication.local.entityPasswordField · string

Name of the password field on the entity if different from the request field.

OAuth Settings

authentication.oauth · object

Configuration for OAuth providers (Google, GitHub, Facebook, etc.).

Show properties

authentication.oauth.redirect · string

The URL to redirect to after successful OAuth authentication.

Example: http://localhost:3030/

authentication.oauth.origins · string[]

Allowed origins for OAuth redirects.

Example: ['http://localhost:3030']

authentication.oauth.defaults · object

Default configuration for all OAuth providers.

Show properties

authentication.oauth.defaults.key · string

Default OAuth client ID (can be overridden per provider).

authentication.oauth.defaults.secret · string

Default OAuth client secret (can be overridden per provider).

Provider-Specific Settings

Each OAuth provider (google, github, facebook, twitter, auth0) has the same configuration structure:

authentication.oauth.<provider> · object

Configuration for a specific OAuth provider.

Show properties

authentication.oauth.<provider>.key · string · required

The OAuth client ID from the provider.

Example: <Client ID>

authentication.oauth.<provider>.secret · string · required

The OAuth client secret from the provider.

Example: <Client secret>

Configuration Examples

JWT + Local Authentication

{
  "authentication": {
    "entity": "user",
    "service": "users",
    "secret": "your-secret-here",
    "authStrategies": ["jwt", "local"],
    "jwtOptions": {
      "header": {
        "typ": "access"
      },
      "audience": "https://yourdomain.com",
      "algorithm": "HS256",
      "expiresIn": "1d"
    },
    "local": {
      "usernameField": "email",
      "passwordField": "password"
    }
  }
}

{
  "authentication": {
    "entity": "user",
    "service": "users",
    "secret": "your-secret-here",
    "authStrategies": ["jwt", "google", "github"],
    "jwtOptions": {
      "header": {
        "typ": "access"
      },
      "audience": "https://yourdomain.com",
      "algorithm": "HS256",
      "expiresIn": "7d"
    },
    "oauth": {
      "redirect": "https://yourdomain.com/",
      "google": {
        "key": "<Google Client ID>",
        "secret": "<Google Client Secret>"
      },
      "github": {
        "key": "<GitHub Client ID>",
        "secret": "<GitHub Client Secret>"
      }
    }
  }
}

{
  "authentication": {
    "secret": "FEATHERS_SECRET",
    "oauth": {
      "google": {
        "key": "GOOGLE_CLIENT_ID",
        "secret": "GOOGLE_CLIENT_SECRET"
      },
      "github": {
        "key": "GITHUB_CLIENT_ID",
        "secret": "GITHUB_CLIENT_SECRET"
      }
    }
  }
}

Usage in Application

The authentication service is automatically configured:

src/authentication.ts

import { AuthenticationService, JWTStrategy } from '@feathersjs/authentication'
import { LocalStrategy } from '@feathersjs/authentication-local'
import { oauth, OAuthStrategy } from '@feathersjs/authentication-oauth'
import type { Application } from './declarations'

declare module './declarations' {
  interface ServiceTypes {
    authentication: AuthenticationService
  }
}

export const authentication = (app: Application) => {
  const authentication = new AuthenticationService(app)

  authentication.register('jwt', new JWTStrategy())
  authentication.register('local', new LocalStrategy())
  authentication.register('google', new OAuthStrategy())
  authentication.register('github', new OAuthStrategy())

  app.use('authentication', authentication)
  app.configure(oauth())
}

Testing Authentication

Test your authentication configuration:

// Local authentication
const { accessToken } = await app.service('authentication').create({
  strategy: 'local',
  email: '[e-mail]',
  password: 'password123'
})

// JWT authentication
const { user } = await app.service('authentication').create({
  strategy: 'jwt',
  accessToken
})

Best Practices

Use strong secrets

Generate strong, random secrets for JWT signing. Use at least 32 characters and store them in environment variables.

Set appropriate token expiration

Balance security and user experience. Short-lived tokens (1-7 days) are more secure but may require more frequent logins.

Secure OAuth credentials

Never commit OAuth client IDs and secrets. Use environment variables and restrict access to production credentials.

Use HTTPS in production

Always use HTTPS for authentication endpoints in production to prevent token interception.

Validate token audience

Set the audience field in JWT options to your application’s domain to prevent token misuse.

Hash passwords properly

Use BCrypt with appropriate salt rounds (10-12). Never store plain-text passwords.

Related Resources

• @feathersjs/authentication
• @feathersjs/authentication-local
• @feathersjs/authentication-oauth