Skip to main content

Authentication

RapidREST offers built-in authentication support for all popular authentication protocols including:

  • BasicStrategy - Simple id and password authentication [@rapidrest/auth]
  • FIDO2Strategy - FIDO2/WebAuthn hardware based authentication (e.g. YubiKey) [@rapidrest/auth]
  • JWTStrategy - JSON Web Token (JWT) protocol for secure, portable, inter-service authentication [@rapidrest/service-core]
  • MFAStrategy - Simple id and password + 2FA authentication [fido2|otp|totp] [@rapidrest/auth]
  • OIDCStrategy - OAuth 2.0 & OpenID Connect authentication [@rapidrest/auth]
  • OTPStrategy - One-Time Password (OTP) authentication (e.g. email, sms) [@rapidrest/auth]
  • PasskeyStrategy - WebAuthn based passkey authentication [@rapidrest/auth]
  • TOTPStrategy - RFC 6238 Time-Based One Time Password authentication (e.g. Google Authenticator, etc.) [@rapidrest/auth]

The JWTStrategy ships as part of the @rapidrest/service-core library, everything else lives in the separate @rapidrest/auth package. If you need a real login flow, see Auth Server after reading this page.

Setting up the default strategy​

The framework allows for a single strategy to be designated as the global default. The global default strategy is used to optionally authenticate every request that is handled by the server. Typically, this is a token based strategy such as JWTStrategy. RapidREST projects that have been scaffolded using the CLI are pre-configured to use the JWTStrategy by default.

The global default strategy can be changed by modifying the auth.strategy coonfig key (see Configuration).

// src/config.ts
auth: {
  // The default authentication strategy to use
  strategy: "auth.JWTStrategy",
}

Requiring auth for API endpoints​

While the framework automatically performs authentication for every request processed, auth is optional. If no auth header is provided by a client request, the API endpoint will still execute. When it is desired to require auth for a given endpoint the @Auth() decorator is used.

The @Auth decorator takes a single argument of type Array with a list of auth strategies to use when attempting to authenticate the request. At least one strategy needs to succeed in order for the request to be considered authenticated.

For example, take for example the API endpoint GET /api/path, you may require auth using the global default JWTStrategy strategy by decoratoring the endpoint function with @Auth as shown below.

@Auth(['jwt'])
@Get()
public endpointFunc() {
  // ...
}

JWT (the default strategy)​

JWTStrategy looks for a token in three places, in this order. The last one found wins:

  1. Query parameter (auth_token): only if allowQueryParam is enabled, since passing tokens in URLs is discouraged by default
  2. Authorization header - matching jwt or bearer schemes, case-insensitive
  3. Cookie (jwt by default; signed cookies if cookieSecure is set)
class JWTStrategyOptions {
  headerKey = 'authorization';
  headerScheme = '(jwt|bearer)';
  cookieName = 'jwt';
  cookieSecure = false;
  queryKey = 'auth_token';
  allowQueryParam = false;
}

Configure the secret and token options under the auth config key (see Configuration):

conf.defaults({
  auth: {
    strategy: 'auth.JWTStrategy',
    secret: 'change-me-in-production',
    options: {
      expiresIn: '1 hour',
      audience: 'my-api.example.com',
      issuer: 'api.example.com',
    },
  },
});

A real login flow​

Since service-core only ships JWTStrategy, a real login flow (verify a password once, issue a JWT for every request after) comes from @rapidrest/auth. Its BaseAuthBasicRoute wraps BasicStrategy, verifies against a stored password Secret, and returns a signed JWT — no manual AuthMiddleware.register() wiring needed:

import { RouteDecorators } from '@rapidrest/service-core';
import { BaseAuthBasicRouteMongo } from '@rapidrest/auth/mongo';
const { Route } = RouteDecorators;

@Route('/auth/password')
export class AuthBasicRoute extends BaseAuthBasicRouteMongo {}

The client sends Authorization: Basic <base64(name:password)> once to /auth/password, gets a token back, then sends Authorization: Bearer <token> on every subsequent request. See Auth Server → Strategies and Auth Server → Base Routes for the full set of login methods (TOTP, WebAuthn, MFA, OIDC, and more).