@memberjunction/auth-providers

Authentication provider interfaces, base classes, and ready-made implementations for validating JWTs from any OAuth 2.0 / OIDC compliant identity provider in MemberJunction.

This package gives the MJ server (and any other Node.js consumer) a uniform, pluggable way to:

• Resolve a JWT's signing key from a remote JWKS endpoint
• Verify the issuer and audience of incoming tokens
• Extract a normalized AuthUserInfo from provider-specific claim shapes
• Register additional providers at runtime via the MJ class-factory system

It ships with first-class support for Auth0, Microsoft Entra ID / MSAL, Okta, AWS Cognito, Google Identity Platform, and WorkOS (AuthKit), and is the extension point used to plug custom providers into @memberjunction/server.

Integrating WorkOS? See the dedicated end-to-end guide: WORKOS.md — it covers the browser + server setup and the two WorkOS-specific gotchas (the required email JWT Template and matching the aud claim).

When to use this package

Use @memberjunction/auth-providers when you are:

• Running an MJ GraphQL server and need to validate user JWTs (this is wired up automatically by @memberjunction/server)
• Building a custom Node.js service that needs to validate tokens issued for an MJ tenant
• Adding support for a new identity provider that is not in the built-in list above
• Implementing an MCP server or other backend that participates in MJ's auth flow (see @memberjunction/ai-mcp-server)

You generally do not need this package directly in browser / Angular code — the front-end auth flow is handled by provider SDKs (MSAL.js, Auth0 SPA SDK, etc.) and the resulting access token is sent to MJ APIs, where this package validates it server-side.

Installation

npm install @memberjunction/auth-providers
Copy

This package is a Node.js / server-side package. It depends on:

• @memberjunction/core — provides AuthProviderConfig and AuthUserInfo types
• @memberjunction/global — provides BaseSingleton, MJGlobal, and @RegisterClass
• jsonwebtoken — JWT primitives
• jwks-rsa — JWKS key retrieval with caching
• graphql — used by TokenExpiredError to surface a typed GraphQL error

Architecture

┌──────────────────────────────────────────────────────────────────┐
│                         @memberjunction/server                    │
│                                                                  │
│   incoming request ──▶ JWT extracted ──▶ getSigningKeys(issuer)  │
│                                              │                   │
└──────────────────────────────────────────────┼───────────────────┘
                                               ▼
┌──────────────────────────────────────────────────────────────────┐
│                  @memberjunction/auth-providers                   │
│                                                                  │
│   AuthProviderFactory (singleton)                                │
│        │                                                         │
│        ├── getByIssuer(iss) ──▶ IAuthProvider                    │
│        │                            │                            │
│        │                            ├── getSigningKey()          │
│        │                            │     (jwks-rsa + retry)     │
│        │                            │                            │
│        │                            └── extractUserInfo()        │
│        │                                                         │
│        └── createProvider(config)                                │
│                  │                                               │
│                  ▼                                               │
│           MJGlobal.ClassFactory                                  │
│           ├─ @RegisterClass(BaseAuthProvider, 'auth0')           │
│           ├─ @RegisterClass(BaseAuthProvider, 'msal')            │
│           ├─ @RegisterClass(BaseAuthProvider, 'okta')            │
│           ├─ @RegisterClass(BaseAuthProvider, 'cognito')         │
│           ├─ @RegisterClass(BaseAuthProvider, 'google')          │
│           ├─ @RegisterClass(BaseAuthProvider, 'workos')          │
│           └─ @RegisterClass(BaseAuthProvider, 'your-custom')     │
└──────────────────────────────────────────────────────────────────┘
Copy

Key pieces

AuthProviderFactory extends BaseSingleton<T> — the global object store guarantees a single instance even if the bundler duplicates the module across execution paths.

Built-in providers

Each built-in provider is registered with the MJ class factory under a lowercase type key. Set type in your config to one of these values to instantiate the matching provider.

Every provider also requires the base fields: name, type, issuer, audience, jwksUri. See AuthProviderConfig for the full shape.

The list above is not a closed set — it is what MJ happens to ship. type is resolved through the class factory, so any @RegisterClass(BaseAuthProvider, 'your-key') subclass is instantiable the same way, with no change to this package. Nothing validates type against an enum.

Where provider configuration comes from

A provider config can reach the factory from three places. They layer rather than compete, and none is mandatory:

Config and environment remain the bootstrap path: you cannot configure authentication through a UI you must first authenticate to reach.

Environment-variable configuration (ConfigFromEnvironment)

A provider class declares its own environment mapping by implementing the optional IEnvironmentConfigurableProvider static. AuthProviderFactory.DiscoverFromEnvironment() walks the class-factory registry and collects every provider that finds its variables — so a third-party provider gets the same "set two variables and you're done" experience as a built-in, without touching MJ core.

Implementing it on your own provider:

@RegisterClass(BaseAuthProvider, 'my-idp')
export class MyIdpProvider extends BaseAuthProvider {
  static ConfigFromEnvironment(env: NodeJS.ProcessEnv): AuthProviderConfig | null {
    // MUST return null — never a partial config — when the variables are absent, or the
    // half-populated result fails validateConfig() and errors on every deployment that
    // simply does not use this provider.
    if (!env.MY_IDP_DOMAIN || !env.MY_IDP_CLIENT_ID) return null;
    return {
      name: 'my-idp',
      type: 'my-idp',
      issuer: `https://${env.MY_IDP_DOMAIN}/`,
      audience: env.MY_IDP_CLIENT_ID,
      jwksUri: `https://${env.MY_IDP_DOMAIN}/.well-known/jwks.json`,
      clientId: env.MY_IDP_CLIENT_ID
    };
  }
  // ...extractUserInfo, etc.
}
Copy

Metadata configuration

MJ: Authentication Providers rows name a DriverClass — the same key as @RegisterClass — plus the non-secret OIDC fields, and are resolved at runtime through the class factory. Two configuration blobs are split by trust boundary: AdditionalConfiguration is server-only and never published, while ClientConfiguration is published verbatim to the unauthenticated pre-auth catalog endpoint that the browser reads before login. Real secrets belong behind CredentialID, which points at an encrypted MJ: Credentials record.

MJ ships seed rows for its providers (all Inactive, connection fields blank) — see metadata/authentication-providers/.

Configuration

In an MJ server, providers are configured under authProviders in mj.config.cjs. Multiple providers can be registered concurrently — the factory dispatches incoming tokens to the right one based on the iss claim.

// mj.config.cjs
module.exports = {
  authProviders: [
    {
      name: 'corporate-azure-ad',
      type: 'msal',
      clientId: process.env.AZURE_CLIENT_ID,
      tenantId: process.env.AZURE_TENANT_ID,
      issuer: `https://login.microsoftonline.com/${process.env.AZURE_TENANT_ID}/v2.0`,
      audience: process.env.AZURE_CLIENT_ID,
      jwksUri: `https://login.microsoftonline.com/${process.env.AZURE_TENANT_ID}/discovery/v2.0/keys`,
    },
    {
      name: 'customer-auth0',
      type: 'auth0',
      clientId: process.env.AUTH0_CLIENT_ID,
      domain: 'tenant.auth0.com',
      issuer: 'https://tenant.auth0.com/',
      audience: 'https://api.example.com',
      jwksUri: 'https://tenant.auth0.com/.well-known/jwks.json',
    },
    {
      name: 'workos-prod',
      type: 'workos',
      clientId: process.env.WORKOS_CLIENT_ID, // client_01H...
      issuer: `https://api.workos.com/user_management/${process.env.WORKOS_CLIENT_ID}`,
      jwksUri: `https://api.workos.com/sso/jwks/${process.env.WORKOS_CLIENT_ID}`,
      audience: process.env.WORKOS_CLIENT_ID, // must match the token's `aud` — see WORKOS.md
    },
    // ...add more providers here
  ],
};
Copy

WorkOS needs two extra steps beyond this config — an email JWT Template (its access tokens omit email, which MJ keys users on) and matching the aud claim. The full walkthrough is in WORKOS.md.

Multiple audiences on the same issuer. When two MJ apps share an Auth0 domain but use different client IDs, register both as separate entries — AuthProviderFactory.getAllByIssuer() returns every match so the validator can try each audience.

Usage

In MJServer (the typical case)

You do not call this package directly when using @memberjunction/server. The server runs initializeAuthProviders() at startup, which reads authProviders from your config and registers each one with the factory. The GraphQL middleware then uses the factory automatically.

Direct programmatic use

import {
  AuthProviderFactory,
  TokenExpiredError,
} from '@memberjunction/auth-providers';
import jwt, { JwtHeader, SigningKeyCallback } from 'jsonwebtoken';

// One-time setup at app boot
const factory = AuthProviderFactory.Instance;

const provider = AuthProviderFactory.createProvider({
  name: 'main-auth0',
  type: 'auth0',
  clientId: process.env.AUTH0_CLIENT_ID!,
  domain: 'tenant.auth0.com',
  issuer: 'https://tenant.auth0.com/',
  audience: 'https://api.example.com',
  jwksUri: 'https://tenant.auth0.com/.well-known/jwks.json',
});
factory.register(provider);

// Per-request token validation
function validate(token: string) {
  return new Promise((resolve, reject) => {
    // First decode (without verifying) to read the issuer claim
    const decoded = jwt.decode(token, { complete: true });
    const issuer = decoded?.payload && typeof decoded.payload === 'object'
      ? (decoded.payload as jwt.JwtPayload).iss
      : undefined;
    if (!issuer) return reject(new Error('Token missing iss claim'));

    const matched = factory.getByIssuer(issuer);
    if (!matched) return reject(new Error(`Unknown issuer: ${issuer}`));

    jwt.verify(
      token,
      (header: JwtHeader, cb: SigningKeyCallback) => matched.getSigningKey(header, cb),
      { issuer: matched.issuer, audience: matched.audience },
      (err, payload) => {
        if (err?.name === 'TokenExpiredError') {
          return reject(new TokenExpiredError(new Date((err as jwt.TokenExpiredError).expiredAt)));
        }
        if (err || !payload || typeof payload !== 'object') return reject(err);
        resolve({
          payload,
          user: matched.extractUserInfo(payload as jwt.JwtPayload),
        });
      },
    );
  });
}
Copy

Building a custom provider

Custom providers extend BaseAuthProvider and register themselves with the MJ class factory. Once registered, they're instantiable by type like any built-in provider.

import { JwtPayload } from 'jsonwebtoken';
import { RegisterClass } from '@memberjunction/global';
import { AuthProviderConfig, AuthUserInfo } from '@memberjunction/core';
import { BaseAuthProvider } from '@memberjunction/auth-providers';

@RegisterClass(BaseAuthProvider, 'keycloak')
export class KeycloakProvider extends BaseAuthProvider {
  constructor(config: AuthProviderConfig) {
    super(config);
  }

  extractUserInfo(payload: JwtPayload): AuthUserInfo {
    return {
      email: payload.email as string | undefined,
      firstName: payload.given_name as string | undefined,
      lastName: payload.family_name as string | undefined,
      fullName: payload.name as string | undefined,
      preferredUsername: payload.preferred_username as string | undefined,
      roles: (payload.realm_access as { roles?: string[] } | undefined)?.roles,
    };
  }

  validateConfig(): boolean {
    return super.validateConfig() && !!this.config.clientId;
  }
}

// Then in mj.config.cjs use type: 'keycloak'
Copy

Important: because the provider is loaded via class-factory metadata and not by direct reference, your bundler may tree-shake it out. Make sure the file containing the @RegisterClass decorator is imported (directly or transitively) before AuthProviderFactory.createProvider() runs. The built-in providers achieve this by being exported from this package's index.ts — importing anything from @memberjunction/auth-providers loads and registers all of them. (AuthProviderFactory.ts used to carry a literal roster of side-effect imports for this; it was removed because it made the built-ins look like a closed set you had to append to, and index.ts already covered it.) For your own provider, export it from your package entry point and make sure that package is reachable from a class-registration manifest — see the discussion in packages/CodeGenLib/CLAUDE.md.

API reference

IAuthProvider

interface IAuthProvider {
  name: string;
  issuer: string;
  audience: string;
  jwksUri: string;
  clientId?: string;
  validateConfig(): boolean;
  getSigningKey(header: JwtHeader, callback: SigningKeyCallback): void;
  extractUserInfo(payload: JwtPayload): AuthUserInfo;
  matchesIssuer(issuer: string): boolean;
}
Copy

BaseAuthProvider

Abstract class that implements all of IAuthProvider except extractUserInfo. It also handles:

• A keep-alive HTTP(S) agent for the JWKS client (50 max sockets, 60s timeout)
• JWKS response caching (5 entries, 10 minute TTL)
• Up to 3 retries with exponential backoff for JWKS fetches on common transient errors (socket hang up, ECONNRESET, ETIMEDOUT, ENOTFOUND, EAI_AGAIN)
• Case-insensitive, trailing-slash-tolerant issuer matching

Subclasses must implement extractUserInfo(payload) and may override validateConfig() to enforce provider-specific required fields.

AuthProviderFactory

Singleton registry/factory. All instance methods are on AuthProviderFactory.Instance; createProvider, getRegisteredProviderTypes, and isProviderTypeRegistered are static helpers.

TokenExpiredError

new TokenExpiredError(expiryDate: Date, message?: string)
Copy

A GraphQLError with extensions.code = 'JWT_EXPIRED' and extensions.expiryDate set to the ISO string of the expiry. Throw this from GraphQL resolvers when you detect an expired token so clients can branch on the error code and trigger a silent refresh.

Related packages

• @memberjunction/core — defines AuthProviderConfig, AuthUserInfo, AuthTokenInfo, AuthJwtPayload and the AUTH_PROVIDER_TYPES constants
• @memberjunction/global — provides BaseSingleton, @RegisterClass, and the MJGlobal.ClassFactory that drives provider instantiation
• @memberjunction/server — primary consumer; wires this package into the GraphQL request pipeline
• @memberjunction/ai-mcp-server — uses this package to validate tokens on MCP transport endpoints (see MCP OAuth spec)
• @memberjunction/api-keys-base and @memberjunction/api-keys-engine — complementary auth path for non-interactive (machine-to-machine) callers

Project guidelines

• Class registration & tree-shaking caveats: see the manifest section of packages/CodeGenLib/CLAUDE.md
• Singleton best practices: see the BaseSingleton rules in .claude/rules/typescript-style.md

License

Business Source License 1.1 — see LICENSE for details.