Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/feathersjs/feathers/llms.txt

Use this file to discover all available pages before exploring further.

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: 
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()
    })
  )
})

​
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_SECRETSecurity: 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.
​
authentication.jwt
object
Configuration for JWT parsing from HTTP headers.

​
Local Authentication Settings

​
authentication.local
object
Configuration for email/password authentication.

​
OAuth Settings

​
authentication.oauth
object
Configuration for OAuth providers (Google, GitHub, Facebook, etc.).

​
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.

​
Configuration Examples

{
  "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"
    }
  }
}

​
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: 'user@example.com',
  password: 'password123'
})

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

​
Best Practices

Generate strong, random secrets for JWT signing. Use at least 32 characters and store them in environment variables.
Balance security and user experience. Short-lived tokens (1-7 days) are more secure but may require more frequent logins.
Never commit OAuth client IDs and secrets. Use environment variables and restrict access to production credentials.
Always use HTTPS for authentication endpoints in production to prevent token interception.
Set the audience field in JWT options to your application’s domain to prevent token misuse.
Use BCrypt with appropriate salt rounds (10-12). Never store plain-text passwords.