@makerx/express-bearer NPM

Express bearer

An express middleware to decode and verify JWTs from bearer authorization headers.

What does this do?

loads signing keys from a JWKS endpoint using jwks-rsa
verifies and decodes a JWT from a Bearer authorization header using jsonwebtoken
sets req.user to the verified decoded JWT payload (claims)

Usage

import { bearerTokenMiddleware, BearerConfig } from '@makerxstudio/express-bearer'

const app = express()
const config: BearerConfig = {
  jwksUri: 'https://login.microsoftonline.com/<tenant ID>/discovery/v2.0/keys',
  verifyOptions: {
    issuer: 'https://login.microsoftonline.com/<tenant ID>/v2.0',
    audience: '<audience ID>',
  },
}

// add the bearer token middleware (to all routes)
app.use(bearerTokenMiddleware({ config }))
// or... add to a specific route
app.post('/api/admin/*', bearerTokenMiddleware({ config }))
// or... add to a specific route + make authentication mandatory
app.post('/api/admin/*', bearerTokenMiddleware({ config, tokenIsRequired: true }))

// access the user, check the roles claim
app.post('/api/admin/*', (req, res, next) => {
  const roles = (req.user?.roles as string[]) ?? []
  if (!roles.includes('Admin')) throw new Error('Authorization failed')
  next()
})

The middleware will:

Return 401 Unauthorized when the JWT fails decoding / verification
Return 401 Unauthorized if there is no Bearer {token} authorization header and tokenIsRequired is set to true (default is false)

Options

BearerAuthOptions:

Option	Description
`config`	The JWT handling config `BearerConfig` (or `BearerConfigCallback` for per-host config).
`tokenIsRequired`	Controls whether requests with no `Bearer {token}` authorization header are rejected, default: `false`.
`logger`	Optional logger implementation to log token validation errors, handler setup info entry etc.

JWT handling config:

Option	Description
`jwksUri`	The endpoint to load signing keys via jwks-rsa
`verifyOptions`	The options passed into jwt.verify
`unauthorizedResponse`	Optional. Callback of type `(req: Request, res: Response) => Response)` which provides a way to customise the HTTP response when the bearer token is required and not present, or the validation fails.If not provided, a plain text 401 Unauthorized response is returned.
`explicitNoIssuerValidation`	Optional. The default behaviour is to enforce issuer validation through `verifyOptions.issuer` to avoid security issues through misconfiguration.If it's intentional to not validate the issuer of incoming tokens, set this property to `true`.
`explicitNoAudienceValidation`	Optional. The default behaviour is to enforce audience validation through `verifyOptions.audience` to avoid security issues through misconfiguration.If it's intentional to not validate the audience of incoming tokens, set this property to `true`.

Multitenant apps

To specify per-host config, provide a *BearerConfigCallback in the form of (host: string) => BearerConfig.

Note: the callback will only be called once per host (config is cached).

Logging

Set the logger implementation to an object that fulfills the Logger definition:

type Logger = {
  error(message: string, ...optionalParams: unknown[]): void
  warn(message: string, ...optionalParams: unknown[]): void
  info(message: string, ...optionalParams: unknown[]): void
  verbose(message: string, ...optionalParams: unknown[]): void
  debug(message: string, ...optionalParams: unknown[]): void
}

Note: this type is compatible with winston loggers.

The following example uses console logging:

const logger: Logger = {
  error: (message: string, ...params: unknown[]) => console.error
  warn: (message: string, ...params: unknown[]) => console.warn
  info: (message: string, ...params: unknown[]) => console.info
  verbose: (message: string, ...params: unknown[]) => console.trace
  debug: (message: string, ...params: unknown[]) => console.debug
}

const config: BearerConfig = {
  jwksUri: ...,
  verifyOptions: { ... },
  logger,
}

@makerx/node-common jsonwebtoken jwks-rsa

@everything-registry/sub-chunk-573

1.1.0

10 months ago

1.0.0

10 months ago