JWT Authentication

createJwtAuthInterceptor verifies JSON Web Tokens from the Authorization: Bearer <token> header. It supports three key resolution strategies: JWKS, HMAC secret, and public key.

JWKS (Recommended for Production)

JWKS (JSON Web Key Set) is the recommended approach. The interceptor fetches and caches signing keys from the identity provider automatically:

import { createJwtAuthInterceptor } from '@connectum/auth';

const jwtAuth = createJwtAuthInterceptor({
  jwksUri: 'https://auth.example.com/.well-known/jwks.json',
  issuer: 'https://auth.example.com/',
  audience: 'my-api',
  maxTokenAge: '1h',
  claimsMapping: {
    roles: 'realm_access.roles',
    scopes: 'scope',
  },
});

Options

Option	Type	Required	Description
jwksUri	string	Yes (if no publicKey/secret)	URL to the JWKS endpoint
issuer	string	No	Expected iss claim
audience	string	No	Expected aud claim
maxTokenAge	string | number	No	Maximum acceptable token age (e.g. '1h', '30m', or seconds)
algorithms	string[]	No	Allowed signature algorithms (e.g. ['RS256'])
claimsMapping	object	No	Map JWT claims to AuthContext fields
skipMethods	string[]	No	Methods to skip authentication for (e.g. 'Service/Method', 'Service/*')
propagateHeaders	boolean	No	Forward auth context as x-auth-* headers to downstream services (default false)

HMAC Secret

For simple setups and testing environments where tokens are signed with a shared secret:

const jwtAuth = createJwtAuthInterceptor({
  secret: process.env.JWT_SECRET,
  issuer: 'my-service',
});

WARNING

HMAC secrets require both the issuer and the verifier to know the secret. Use JWKS in production to avoid sharing signing keys.

Public Key

For asymmetric verification with a pre-loaded public key:

const publicKey = await crypto.subtle.importKey(
  'spki', keyData, { name: 'RSASSA-PKCS1-v1_5', hash: 'SHA-256' }, true, ['verify'],
);

const jwtAuth = createJwtAuthInterceptor({ publicKey });

Key Resolution Priority

When multiple key sources are provided, resolution follows this priority:

jwksUri > publicKey > secret

At least one must be provided. If jwksUri is set, publicKey and secret are ignored.

Full Example

import { createServer } from '@connectum/core';
import { createDefaultInterceptors } from '@connectum/interceptors';
import { createJwtAuthInterceptor, createAuthzInterceptor } from '@connectum/auth';

const jwtAuth = createJwtAuthInterceptor({
  jwksUri: 'https://auth.example.com/.well-known/jwks.json',
  issuer: 'https://auth.example.com/',
  audience: 'my-api',
  maxTokenAge: '1h',
  claimsMapping: {
    roles: 'realm_access.roles',
    scopes: 'scope',
  },
});

const server = createServer({
  services: [routes],
  interceptors: [...createDefaultInterceptors(), jwtAuth],
});

await server.start();

Related

• Auth Overview -- all authentication strategies
• Authorization -- RBAC rules and programmatic authorization
• Auth Context -- accessing identity in handlers
• @connectum/auth -- Package Guide
• @connectum/auth API -- Full API Reference