@memberjunction/auth-providers 5.43.0 → 5.44.0

package/.turbo/turbo-build.log

@@ -1,4 +1,4 @@
 
-> @memberjunction/auth-providers@5.43.0 build
+> @memberjunction/auth-providers@5.44.0 build
 > tsc && tsc-alias -f
 

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @memberjunction/auth-providers
 
+## 5.44.0
+
+### Minor Changes
+
+- 2f9b863: Add WorkOS (AuthKit) as a first-class authentication provider — end to end, server-side JWT validation and browser-side login. A deployment can now set `type: 'workos'` (server) / `AUTH_TYPE: 'workos'` (browser) and authenticate users through WorkOS just like Auth0, Okta, MSAL, Cognito, or Google.
+  - **Server** (`@memberjunction/auth-providers`): `WorkOSProvider` extends `BaseAuthProvider`, registered via `@RegisterClass(BaseAuthProvider, 'workos')`. Maps AuthKit JWT claims to `AuthUserInfo` (with graceful fallbacks) and validates `clientId`; issuer matching, JWKS caching, and retry/backoff are inherited. Wired into `AuthProviderFactory`.
+  - **Client** (`@memberjunction/ng-auth-services`): `MJWorkOSProvider` extends `MJAuthBase`, registered via `@RegisterClass(MJAuthBase, 'workos')`. Wraps the `@workos-inc/authkit-js` SDK (`createClient`/`signIn`/`signOut`/`getUser`/`getAccessToken`) behind the standardized provider contract with semantic error classification.
+  - **Core** (`@memberjunction/core`): `AUTH_PROVIDER_TYPES` gains `WORKOS: 'workos'`.
+  - **Env typing** (`@memberjunction/ng-bootstrap`): the `AUTH_TYPE` union gains `'workos'`, plus `WORKOS_CLIENTID` / `WORKOS_REDIRECT_URI` / `WORKOS_API_HOSTNAME` / `WORKOS_DEV_MODE` keys.
+
+  Includes a full end-to-end integration guide (`packages/AuthProviders/WORKOS.md`) covering the two WorkOS-specific gotchas: the required `email` JWT Template (AuthKit access tokens omit email, which MJ keys users on) and matching the enforced `aud` claim. Additive only.
+
+### Patch Changes
+
+- Updated dependencies [5396d90]
+- Updated dependencies [7279819]
+- Updated dependencies [d44e430]
+- Updated dependencies [6f74b17]
+- Updated dependencies [2f9b863]
+  - @memberjunction/core@5.44.0
+  - @memberjunction/global@5.44.0
+
 ## 5.43.0
 
 ### Patch Changes

package/README.md

@@ -9,7 +9,9 @@ This package gives the MJ server (and any other Node.js consumer) a uniform, plu
 - 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**, and **Google Identity Platform**, and is the extension point used to plug custom providers into [`@memberjunction/server`](../MJServer/README.md).
+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`](../MJServer/README.md).
+
+> **Integrating WorkOS?** See the dedicated end-to-end guide: **[WORKOS.md](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
 
@@ -67,6 +69,7 @@ This package is a Node.js / server-side package. It depends on:
 │           ├─ @RegisterClass(BaseAuthProvider, 'okta')            │
 │           ├─ @RegisterClass(BaseAuthProvider, 'cognito')         │
 │           ├─ @RegisterClass(BaseAuthProvider, 'google')          │
+│           ├─ @RegisterClass(BaseAuthProvider, 'workos')          │
 │           └─ @RegisterClass(BaseAuthProvider, 'your-custom')     │
 └──────────────────────────────────────────────────────────────────┘
 ```
@@ -95,6 +98,7 @@ Each built-in provider is registered with the MJ class factory under a lowercase
 | `okta`     | `OktaProvider`    | `clientId`, `domain`                                     |
 | `cognito`  | `CognitoProvider` | `clientId`, `region`, `userPoolId`                       |
 | `google`   | `GoogleProvider`  | `clientId`                                               |
+| `workos`   | `WorkOSProvider`  | `clientId` (see [WORKOS.md](WORKOS.md) for the required `email` JWT Template + `aud`) |
 
 Every provider also requires the base fields: `name`, `type`, `issuer`, `audience`, `jwksUri`. See [`AuthProviderConfig`](../MJCore/src/generic/authTypes.ts) for the full shape.
 
@@ -124,11 +128,23 @@ module.exports = {
       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
   ],
 };
 ```
 
+> **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](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

package/WORKOS.md

@@ -0,0 +1,256 @@
+# WorkOS (AuthKit) Integration Guide
+
+This guide walks you through wiring **WorkOS AuthKit** into MemberJunction end to end —
+browser login and server-side token validation — so users sign in through WorkOS exactly like
+they would through Auth0, Okta, MSAL, Cognito, or Google.
+
+WorkOS is consumed as an OIDC/JWT identity provider. MemberJunction does **not** replace WorkOS;
+WorkOS handles authentication (hosted login, SSO, MFA, Directory Sync) and MJ handles everything
+after the user is identified (entities, permissions, agents, audit).
+
+> **TL;DR — the one thing that trips everyone up:** a WorkOS AuthKit **access token does not
+> include the user's email by default**, and MemberJunction resolves users by email. You must add
+> an `email` claim with a [WorkOS **JWT Template**](#step-3--add-an-email-claim-jwt-template).
+> Skip this and every login will fail user lookup on the server. See
+> [Step 3](#step-3--add-an-email-claim-jwt-template).
+
+---
+
+## Table of contents
+
+1. [How it fits together](#how-it-fits-together)
+2. [What's in this package](#whats-in-this-package)
+3. [Prerequisites](#prerequisites)
+4. [Step 1 — Configure the WorkOS dashboard](#step-1--configure-the-workos-dashboard)
+5. [Step 2 — Configure the MJ server (`mj.config.cjs`)](#step-2--configure-the-mj-server-mjconfigcjs)
+6. [Step 3 — Add an `email` claim (JWT Template)](#step-3--add-an-email-claim-jwt-template)
+7. [Step 4 — Configure the browser (MJExplorer)](#step-4--configure-the-browser-mjexplorer)
+8. [Token claims reference](#token-claims-reference)
+9. [How validation works under the hood](#how-validation-works-under-the-hood)
+10. [Troubleshooting](#troubleshooting)
+11. [Scope & non-goals](#scope--non-goals)
+
+---
+
+## How it fits together
+
+```
+┌─ Browser (MJExplorer) ─────────────────┐        ┌─ MJ GraphQL Server ─────────────────────┐
+│                                         │        │                                          │
+│  MJWorkOSProvider (extends MJAuthBase)  │        │  WorkOSProvider (extends BaseAuthProvider)│
+│   @RegisterClass(MJAuthBase,'workos')   │        │   @RegisterClass(BaseAuthProvider,'workos')│
+│        │                                │        │        ▲                                 │
+│   @workos-inc/authkit-js                │        │        │ jwks-rsa + jsonwebtoken         │
+│        │  signIn → hosted login         │        │        │ (verify signature, iss, aud)    │
+│        │  getUser()  (email for display)│        │        │                                 │
+│        └─ getAccessToken() ── Bearer ───┼────────┼──▶ AuthProviderFactory.getByIssuer(iss)  │
+│                                         │        │      → WorkOSProvider.extractUserInfo()  │
+│                                         │        │      → verifyUserRecord(email)           │
+└─────────────────────────────────────────┘        └──────────────────────────────────────────┘
+```
+
+Both ends register under the same lowercase key, `workos`, through MJ's class factory. The server
+trusts the issuer/JWKS to verify the signature; the browser SDK manages the session and silent
+token refresh.
+
+## What's in this package
+
+| Side | Class | File | Registers as |
+|---|---|---|---|
+| Server | `WorkOSProvider` | [`src/providers/WorkOSProvider.ts`](src/providers/WorkOSProvider.ts) | `@RegisterClass(BaseAuthProvider, 'workos')` |
+| Browser | `MJWorkOSProvider` | `@memberjunction/ng-auth-services` → `src/lib/providers/mjexplorer-workos-provider.service.ts` | `@RegisterClass(MJAuthBase, 'workos')` |
+
+The server provider is registered automatically (it's imported by
+[`AuthProviderFactory.ts`](src/AuthProviderFactory.ts)); you only need to add a config entry.
+
+## Prerequisites
+
+- A [WorkOS](https://workos.com) account with **AuthKit / User Management** enabled.
+- Your **Client ID** (looks like `client_01H...`) from the WorkOS dashboard.
+- The browser app must depend on `@workos-inc/authkit-js` (already declared as a peer dependency
+  of `@memberjunction/ng-auth-services`, and a direct dependency of MJExplorer).
+
+---
+
+## Step 1 — Configure the WorkOS dashboard
+
+1. In the WorkOS dashboard, go to **Authentication → AuthKit** and enable it.
+2. Under **Redirects**, add your app's redirect URI (e.g. `http://localhost:4200` for local
+   development, plus your production origin). This is where WorkOS returns the user after login.
+3. Set a **Logout URI** (the page WorkOS returns to after sign-out — typically the same origin).
+4. Note your **Client ID**. You'll use it in three places: the server `issuer`/`jwksUri`, the
+   server `clientId`, and the browser `WORKOS_CLIENTID`.
+
+## Step 2 — Configure the MJ server (`mj.config.cjs`)
+
+Add a `workos` entry to `authProviders`. The `issuer` and `jwksUri` are derived from your Client
+ID:
+
+```javascript
+// mj.config.cjs
+module.exports = {
+  authProviders: [
+    {
+      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}`,
+      // The audience MUST match the token's `aud` claim — see the note below.
+      audience: process.env.WORKOS_CLIENT_ID,
+    },
+    // ...other providers can coexist; the factory routes by the token's `iss` claim
+  ],
+};
+```
+
+### Getting `audience` right
+
+MemberJunction **always enforces the `aud` claim** during verification. WorkOS sets `aud`
+automatically (you cannot override it via a JWT Template — it's a reserved claim):
+
+- **No Resource Indicators configured (default):** WorkOS uses a default audience unique to your
+  WorkOS environment. Decode a real access token (e.g. at [jwt.io](https://jwt.io)) and copy the
+  exact `aud` value into your `audience` config.
+- **Resource Indicators configured:** the `aud` matches the requested resource — set `audience`
+  to that resource identifier.
+
+> If `audience` does not match the token's `aud`, verification fails with
+> `jwt audience invalid`. This is the second most common misconfiguration after the missing email
+> claim.
+
+## Step 3 — Add an `email` claim (JWT Template)
+
+**This step is required.** A WorkOS AuthKit access token carries identity/session claims
+(`sub`, `sid`, `org_id`, `role`, `permissions`) but **not** the user's email. MemberJunction
+looks the user up by email server-side, so you must add it.
+
+In the WorkOS dashboard, go to **Authentication → Sessions → JWT Template** (or
+**JWT Templates**) and add:
+
+```json
+{
+  "email": "{{user.email}}",
+  "given_name": "{{user.first_name}}",
+  "family_name": "{{user.last_name}}"
+}
+```
+
+- `email` is what MJ matches against the `User.Email` column — **required**.
+- `given_name` / `family_name` are optional but recommended: they let MJ
+  [auto-provision new users](../MJServer/README.md) with proper names when
+  `userHandling.autoCreateNewUsers` is enabled.
+- WorkOS JWT Templates drop any claim whose value renders to `null`, so users missing a first/last
+  name simply won't have those claims — the provider handles that gracefully (it falls back to
+  splitting a `name` claim, or to the email).
+
+> **Why not just read email from the ID token?** The browser SDK's `getUser()` always has the
+> email (used for display), but the **server** only sees the bearer **access token**. The JWT
+> Template is what puts the email into that access token.
+
+## Step 4 — Configure the browser (MJExplorer)
+
+Set `AUTH_TYPE` to `workos` and provide the WorkOS environment keys. These flow into the provider
+through `AuthServicesModule.forRoot(environment)`:
+
+```typescript
+// environment.ts
+export const environment = {
+  // ...
+  AUTH_TYPE: 'workos',
+  WORKOS_CLIENTID: 'client_01H...',          // required
+  WORKOS_REDIRECT_URI: window.location.origin, // optional; defaults to window.location.origin
+  WORKOS_API_HOSTNAME: undefined,             // optional; only for custom domains / proxies
+  WORKOS_DEV_MODE: false,                      // optional; localStorage session for local dev
+};
+```
+
+| Env key | Required | Purpose |
+|---|---|---|
+| `AUTH_TYPE` | ✅ | Must be `'workos'` to select this provider |
+| `WORKOS_CLIENTID` | ✅ | Your AuthKit Client ID |
+| `WORKOS_REDIRECT_URI` | — | Redirect target after login (default: `window.location.origin`) |
+| `WORKOS_API_HOSTNAME` | — | Override the WorkOS API hostname (custom domains / proxy) |
+| `WORKOS_DEV_MODE` | — | AuthKit dev mode — localStorage-backed session for local development |
+
+That's it. On startup, `MJWorkOSProvider.initialize()` constructs the AuthKit client (which also
+processes any pending redirect callback), establishes the session, and the rest of MJ works
+unchanged — `getIdToken()` hands the access token to the GraphQL client as a Bearer token.
+
+---
+
+## Token claims reference
+
+A WorkOS AuthKit **access token** (what `getAccessToken()` returns and the server validates),
+**after** adding the recommended JWT Template:
+
+```jsonc
+{
+  "iss": "https://api.workos.com/user_management/client_01H...",
+  "sub": "user_01HXYZ...",       // WorkOS user id → AuthUserInfo.userId
+  "sid": "session_01H...",       // session id
+  "jti": "01H...",
+  "aud": "<environment default or resource indicator>",  // MJ enforces this
+  "org_id": "org_01H...",        // present for organization-scoped sessions
+  "role": "admin",               // organization-membership role
+  "permissions": ["posts:read"], // role permissions
+  "exp": 1717000000,
+  "iat": 1716996400,
+
+  // ── added by your JWT Template ──
+  "email": "ada@example.com",    // REQUIRED for MJ user resolution
+  "given_name": "Ada",
+  "family_name": "Lovelace"
+}
+```
+
+`WorkOSProvider.extractUserInfo()` maps this to MJ's `AuthUserInfo`:
+
+| `AuthUserInfo` field | Source claim | Fallback |
+|---|---|---|
+| `email` | `email` | — (undefined if no JWT Template) |
+| `firstName` | `given_name` | first word of `name` |
+| `lastName` | `family_name` | second word of `name`, else first word |
+| `fullName` | `name` | — |
+| `preferredUsername` | `preferred_username` | `email` |
+| `userId` | `sub` | — |
+
+## How validation works under the hood
+
+1. The browser sends `Authorization: Bearer <accessToken>` to the MJ GraphQL API.
+2. MJServer decodes the token (without verifying) to read the `iss` claim.
+3. `AuthProviderFactory.getByIssuer(iss)` resolves the `WorkOSProvider` instance (issuer matching
+   is case-insensitive and trailing-slash tolerant).
+4. `jwt.verify()` validates the RS256 signature against the JWKS at
+   `https://api.workos.com/sso/jwks/<clientId>` (cached, with retry/backoff handled by
+   `BaseAuthProvider`), and checks `iss` + `aud`.
+5. `WorkOSProvider.extractUserInfo(payload)` produces the normalized identity.
+6. MJServer resolves/creates the `User` record by **email** and builds the request context.
+
+See [`@memberjunction/auth-providers` README](README.md) and
+[`@memberjunction/server`](../MJServer/README.md) for the shared validation pipeline.
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| Server logs "user not found" / login bounces | Access token has no `email` claim | [Add the JWT Template](#step-3--add-an-email-claim-jwt-template) |
+| `jwt audience invalid` | `audience` config ≠ token `aud` | Decode a real token, copy its `aud` into `audience` ([Step 2](#getting-audience-right)) |
+| `No authentication provider found for issuer` | `issuer` config doesn't match the token | Ensure `issuer` is `https://api.workos.com/user_management/<clientId>` with your real Client ID |
+| `jwt expired` right after login | Clock skew or stale token | The browser SDK auto-refreshes; ensure server time is correct |
+| Login redirect loops | Redirect URI not registered | Add your exact origin under WorkOS dashboard → Redirects |
+| New users not auto-created | Missing `given_name`/`family_name` or `autoCreateNewUsers` off | Add name claims to the JWT Template; check `userHandling` config |
+
+## Scope & non-goals
+
+- **In scope:** WorkOS **AuthKit / User Management** (OIDC/JWT bearer login + validation). This is
+  the same OIDC/JWT model every other MJ provider uses.
+- **Out of scope (today):** WorkOS **SSO via SAML assertions** and **Directory Sync (SCIM)**
+  user provisioning as distinct flows. AuthKit can itself broker SSO connections behind its hosted
+  login, so SSO end-users still authenticate through the `workos` provider — but MJ does not parse
+  raw SAML assertions or run SCIM provisioning. Those would be a separate, larger effort.
+
+---
+
+*Part of [`@memberjunction/auth-providers`](README.md) in the
+[MemberJunction](https://github.com/MemberJunction/MJ) monorepo.*

package/dist/AuthProviderFactory.d.ts

@@ -6,6 +6,7 @@ import './providers/MSALProvider.js';
 import './providers/OktaProvider.js';
 import './providers/CognitoProvider.js';
 import './providers/GoogleProvider.js';
+import './providers/WorkOSProvider.js';
 import './providers/MagicLinkProvider.js';
 /**
  * Factory and registry for managing authentication providers

package/dist/AuthProviderFactory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AuthProviderFactory.d.ts","sourceRoot":"","sources":["../src/AuthProviderFactory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAe,MAAM,sBAAsB,CAAC;AACvE,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD,OAAO,EAAY,aAAa,EAAc,MAAM,wBAAwB,CAAC;AAG7E,OAAO,8BAA8B,CAAC;AACtC,OAAO,6BAA6B,CAAC;AACrC,OAAO,6BAA6B,CAAC;AACrC,OAAO,gCAAgC,CAAC;AACxC,OAAO,+BAA+B,CAAC;AACvC,OAAO,kCAAkC,CAAC;AAE1C;;;GAGG;AACH,qBAAa,mBAAoB,SAAQ,aAAa,CAAC,mBAAmB,CAAC;IACzE,OAAO,CAAC,SAAS,CAAyC;IAC1D;;;;;;OAMG;IACH,OAAO,CAAC,WAAW,CAA6F;IAChH;;OAEG;IACH,OAAO,CAAC,gBAAgB,CAAiG;;IAMzH;;OAEG;IACH,WAAkB,QAAQ,IAAI,mBAAmB,CAEhD;IAED;;;OAGG;IACH,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,kBAAkB,GAAG,aAAa;IAsBhE;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI;IAiBvC;;OAEG;IACH,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS;IAmBtD;;;;;;OAMG;IACH,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,EAAE;IAqB/C;;OAEG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS;IAIlD;;OAEG;IACH,eAAe,IAAI,aAAa,EAAE;IAIlC;;OAEG;IACH,YAAY,IAAI,OAAO;IAIvB;;OAEG;IACH,KAAK,IAAI,IAAI;IAMb;;OAEG;IACH,MAAM,CAAC,0BAA0B,IAAI,MAAM,EAAE;IAW7C;;OAEG;IACH,MAAM,CAAC,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;CASvD"}
+{"version":3,"file":"AuthProviderFactory.d.ts","sourceRoot":"","sources":["../src/AuthProviderFactory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAe,MAAM,sBAAsB,CAAC;AACvE,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD,OAAO,EAAY,aAAa,EAAc,MAAM,wBAAwB,CAAC;AAG7E,OAAO,8BAA8B,CAAC;AACtC,OAAO,6BAA6B,CAAC;AACrC,OAAO,6BAA6B,CAAC;AACrC,OAAO,gCAAgC,CAAC;AACxC,OAAO,+BAA+B,CAAC;AACvC,OAAO,+BAA+B,CAAC;AACvC,OAAO,kCAAkC,CAAC;AAE1C;;;GAGG;AACH,qBAAa,mBAAoB,SAAQ,aAAa,CAAC,mBAAmB,CAAC;IACzE,OAAO,CAAC,SAAS,CAAyC;IAC1D;;;;;;OAMG;IACH,OAAO,CAAC,WAAW,CAA6F;IAChH;;OAEG;IACH,OAAO,CAAC,gBAAgB,CAAiG;;IAMzH;;OAEG;IACH,WAAkB,QAAQ,IAAI,mBAAmB,CAEhD;IAED;;;OAGG;IACH,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,kBAAkB,GAAG,aAAa;IAsBhE;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI;IAiBvC;;OAEG;IACH,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS;IAmBtD;;;;;;OAMG;IACH,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,EAAE;IAqB/C;;OAEG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS;IAIlD;;OAEG;IACH,eAAe,IAAI,aAAa,EAAE;IAIlC;;OAEG;IACH,YAAY,IAAI,OAAO;IAIvB;;OAEG;IACH,KAAK,IAAI,IAAI;IAMb;;OAEG;IACH,MAAM,CAAC,0BAA0B,IAAI,MAAM,EAAE;IAW7C;;OAEG;IACH,MAAM,CAAC,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;CASvD"}

package/dist/AuthProviderFactory.js

@@ -7,6 +7,7 @@ import './providers/MSALProvider.js';
 import './providers/OktaProvider.js';
 import './providers/CognitoProvider.js';
 import './providers/GoogleProvider.js';
+import './providers/WorkOSProvider.js';
 import './providers/MagicLinkProvider.js';
 /**
  * Factory and registry for managing authentication providers

package/dist/AuthProviderFactory.js.map

@@ -1 +1 @@
-{"version":3,"file":"AuthProviderFactory.js","sourceRoot":"","sources":["../src/AuthProviderFactory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAEvE,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAE7E,gDAAgD;AAChD,OAAO,8BAA8B,CAAC;AACtC,OAAO,6BAA6B,CAAC;AACrC,OAAO,6BAA6B,CAAC;AACrC,OAAO,gCAAgC,CAAC;AACxC,OAAO,+BAA+B,CAAC;AACvC,OAAO,kCAAkC,CAAC;AAE1C;;;GAGG;AACH,MAAM,OAAO,mBAAoB,SAAQ,aAAkC;IAezE;QACE,KAAK,EAAE,CAAC;QAfF,cAAS,GAA+B,IAAI,GAAG,EAAE,CAAC;QAC1D;;;;;;WAMG;QACK,gBAAW,GAAsC,IAAI,UAAU,CAAwB,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,CAAC;QAChH;;WAEG;QACK,qBAAgB,GAAwC,IAAI,UAAU,CAA0B,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,CAAC;IAIzH,CAAC;IAED;;OAEG;IACI,MAAM,KAAK,QAAQ;QACxB,OAAO,mBAAmB,CAAC,WAAW,EAAuB,CAAC;IAChE,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,cAAc,CAAC,MAA0B;QAC9C,IAAI,CAAC;YACH,4DAA4D;YAC5D,0EAA0E;YAC1E,0EAA0E;YAC1E,MAAM,QAAQ,GAAG,QAAQ,CAAC,QAAQ,CAAC,YAAY,CAAC,cAAc,CAC5D,gBAAgB,EAChB,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,EACzB,MAAM,CACP,CAAC;YAEF,IAAI,CAAC,QAAQ,EAAE,CAAC;gBACd,MAAM,IAAI,KAAK,CAAC,oCAAoC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;YACrE,CAAC;YAED,OAAO,QAAQ,CAAC;QAClB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACvE,MAAM,IAAI,KAAK,CAAC,sDAAsD,MAAM,CAAC,IAAI,MAAM,OAAO,EAAE,CAAC,CAAC;QACpG,CAAC;IACH,CAAC;IAED;;OAEG;IACH,QAAQ,CAAC,QAAuB;QAC9B,IAAI,CAAC,QAAQ,CAAC,cAAc,EAAE,EAAE,CAAC;YAC/B,MAAM,IAAI,KAAK,CAAC,uCAAuC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;QAC1E,CAAC;QAED,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QAE5C,oDAAoD;QACpD,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,CAAC;QACzB,IAAI,CAAC,gBAAgB,CAAC,KAAK,EAAE,CAAC;QAE9B,oFAAoF;QACpF,sFAAsF;QACtF,sFAAsF;QACtF,WAAW,CAAC,EAAE,OAAO,EAAE,6BAA6B,QAAQ,CAAC,IAAI,iBAAiB,QAAQ,CAAC,MAAM,EAAE,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC;IAC5H,CAAC;IAED;;OAEG;IACH,WAAW,CAAC,MAAc;QACxB,oBAAoB;QACpB,MAAM,MAAM,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QAC5C,IAAI,MAAM,EAAE,CAAC;YACX,OAAO,MAAM,CAAC;QAChB,CAAC;QAED,2BAA2B;QAC3B,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,EAAE,CAAC;YAC/C,IAAI,QAAQ,CAAC,aAAa,CAAC,MAAM,CAAC,EAAE,CAAC;gBACnC,2BAA2B;gBAC3B,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;gBACvC,OAAO,QAAQ,CAAC;YAClB,CAAC;QACH,CAAC;QAED,OAAO,SAAS,CAAC;IACnB,CAAC;IAED;;;;;;OAMG;IACH,cAAc,CAAC,MAAc;QAC3B,mCAAmC;QACnC,MAAM,MAAM,GAAG,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACjD,IAAI,MAAM,EAAE,CAAC;YACX,OAAO,MAAM,CAAC;QAChB,CAAC;QAED,MAAM,OAAO,GAAoB,EAAE,CAAC;QACpC,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,EAAE,CAAC;YAC/C,IAAI,QAAQ,CAAC,aAAa,CAAC,MAAM,CAAC,EAAE,CAAC;gBACnC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YACzB,CAAC;QACH,CAAC;QAED,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACvB,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAC7C,CAAC;QAED,OAAO,OAAO,CAAC;IACjB,CAAC;IAED;;OAEG;IACH,SAAS,CAAC,IAAY;QACpB,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAClC,CAAC;IAED;;OAEG;IACH,eAAe;QACb,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC,CAAC;IAC7C,CAAC;IAED;;OAEG;IACH,YAAY;QACV,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,GAAG,CAAC,CAAC;IACjC,CAAC;IAED;;OAEG;IACH,KAAK;QACH,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;QACvB,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,CAAC;QACzB,IAAI,CAAC,gBAAgB,CAAC,KAAK,EAAE,CAAC;IAChC,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,0BAA0B;QAC/B,+DAA+D;QAC/D,MAAM,aAAa,GAAG,QAAQ,CAAC,QAAQ,CAAC,YAAY,CAAC,mBAAmB,CAAC,gBAAgB,CAAC,CAAC;QAC3F,0DAA0D;QAC1D,MAAM,aAAa,GAAG,aAAa;aAChC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC;aACnB,MAAM,CAAC,CAAC,GAAG,EAAiB,EAAE,CAAC,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,SAAS,CAAC,CAAC;QACrE,+BAA+B;QAC/B,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC;IAC5C,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,wBAAwB,CAAC,IAAY;QAC1C,IAAI,CAAC;YACH,qDAAqD;YACrD,MAAM,YAAY,GAAG,QAAQ,CAAC,QAAQ,CAAC,YAAY,CAAC,eAAe,CAAC,gBAAgB,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC;YAC1G,OAAO,YAAY,KAAK,IAAI,IAAI,YAAY,KAAK,SAAS,CAAC;QAC7D,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;CACF"}
+{"version":3,"file":"AuthProviderFactory.js","sourceRoot":"","sources":["../src/AuthProviderFactory.ts"],"names":[],"mappings":"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"}

package/dist/providers/WorkOSProvider.d.ts

@@ -0,0 +1,48 @@
+import { JwtPayload } from 'jsonwebtoken';
+import { AuthProviderConfig, AuthUserInfo } from '@memberjunction/core';
+import { BaseAuthProvider } from '../BaseAuthProvider.js';
+/**
+ * WorkOS (AuthKit) authentication provider implementation.
+ *
+ * Validates JWT access tokens minted by WorkOS AuthKit / User Management. These tokens are
+ * signed with RS256 and verified against the per-environment JWKS endpoint
+ * (`https://api.workos.com/sso/jwks/<clientId>`); their `iss` claim is
+ * `https://api.workos.com/user_management/<clientId>`.
+ *
+ * ## Email is required — and is NOT in a WorkOS token by default
+ * MemberJunction resolves the signed-in user by **email**, but a WorkOS AuthKit access token
+ * only carries identity/session claims (`sub`, `sid`, `org_id`, `role`, `permissions`) out of
+ * the box — it does **not** include `email`. To use WorkOS with MJ you must add the email (and
+ * ideally the name) to the token via a WorkOS **JWT Template**:
+ *
+ * ```json
+ * {
+ *   "email": "{{user.email}}",
+ *   "given_name": "{{user.first_name}}",
+ *   "family_name": "{{user.last_name}}"
+ * }
+ * ```
+ *
+ * See `WORKOS.md` in this package for the full, step-by-step integration guide.
+ */
+export declare class WorkOSProvider extends BaseAuthProvider {
+    constructor(config: AuthProviderConfig);
+    /**
+     * Extracts user information from a WorkOS AuthKit JWT payload.
+     *
+     * `email`, `given_name`, and `family_name` are expected to be supplied by a WorkOS JWT
+     * Template (see class docs). `sub` is the stable WorkOS user id (`user_...`). We fall back
+     * through standard OIDC claim names so a token shaped by a custom template (e.g. one that
+     * only sets `name`) still resolves a usable identity.
+     */
+    extractUserInfo(payload: JwtPayload): AuthUserInfo;
+    /**
+     * Validates WorkOS-specific configuration.
+     *
+     * Beyond the base requirements (`name`, `issuer`, `audience`, `jwksUri`), WorkOS needs a
+     * `clientId` — it appears in both the issuer and JWKS URLs and identifies the AuthKit
+     * environment.
+     */
+    validateConfig(): boolean;
+}
+//# sourceMappingURL=WorkOSProvider.d.ts.map

package/dist/providers/WorkOSProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WorkOSProvider.d.ts","sourceRoot":"","sources":["../../src/providers/WorkOSProvider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE1C,OAAO,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACxE,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAG1D;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBACa,cAAe,SAAQ,gBAAgB;gBACtC,MAAM,EAAE,kBAAkB;IAItC;;;;;;;OAOG;IACH,eAAe,CAAC,OAAO,EAAE,UAAU,GAAG,YAAY;IAoBlD;;;;;;OAMG;IACH,cAAc,IAAI,OAAO;CAM1B"}

package/dist/providers/WorkOSProvider.js

@@ -0,0 +1,84 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+import { RegisterClass } from '@memberjunction/global';
+import { BaseAuthProvider } from '../BaseAuthProvider.js';
+/**
+ * WorkOS (AuthKit) authentication provider implementation.
+ *
+ * Validates JWT access tokens minted by WorkOS AuthKit / User Management. These tokens are
+ * signed with RS256 and verified against the per-environment JWKS endpoint
+ * (`https://api.workos.com/sso/jwks/<clientId>`); their `iss` claim is
+ * `https://api.workos.com/user_management/<clientId>`.
+ *
+ * ## Email is required — and is NOT in a WorkOS token by default
+ * MemberJunction resolves the signed-in user by **email**, but a WorkOS AuthKit access token
+ * only carries identity/session claims (`sub`, `sid`, `org_id`, `role`, `permissions`) out of
+ * the box — it does **not** include `email`. To use WorkOS with MJ you must add the email (and
+ * ideally the name) to the token via a WorkOS **JWT Template**:
+ *
+ * ```json
+ * {
+ *   "email": "{{user.email}}",
+ *   "given_name": "{{user.first_name}}",
+ *   "family_name": "{{user.last_name}}"
+ * }
+ * ```
+ *
+ * See `WORKOS.md` in this package for the full, step-by-step integration guide.
+ */
+let WorkOSProvider = class WorkOSProvider extends BaseAuthProvider {
+    constructor(config) {
+        super(config);
+    }
+    /**
+     * Extracts user information from a WorkOS AuthKit JWT payload.
+     *
+     * `email`, `given_name`, and `family_name` are expected to be supplied by a WorkOS JWT
+     * Template (see class docs). `sub` is the stable WorkOS user id (`user_...`). We fall back
+     * through standard OIDC claim names so a token shaped by a custom template (e.g. one that
+     * only sets `name`) still resolves a usable identity.
+     */
+    extractUserInfo(payload) {
+        const email = payload.email;
+        const fullName = payload.name;
+        const firstName = payload.given_name;
+        const lastName = payload.family_name;
+        // WorkOS access tokens have no `preferred_username`; email is the natural handle.
+        const preferredUsername = payload.preferred_username || email;
+        // `sub` is the WorkOS user identifier (e.g. "user_01H...").
+        const userId = payload.sub;
+        return {
+            email,
+            firstName: firstName || fullName?.split(' ')[0],
+            lastName: lastName || fullName?.split(' ')[1] || fullName?.split(' ')[0],
+            fullName,
+            preferredUsername,
+            userId
+        };
+    }
+    /**
+     * Validates WorkOS-specific configuration.
+     *
+     * Beyond the base requirements (`name`, `issuer`, `audience`, `jwksUri`), WorkOS needs a
+     * `clientId` — it appears in both the issuer and JWKS URLs and identifies the AuthKit
+     * environment.
+     */
+    validateConfig() {
+        const baseValid = super.validateConfig();
+        const hasClientId = !!this.config.clientId;
+        return baseValid && hasClientId;
+    }
+};
+WorkOSProvider = __decorate([
+    RegisterClass(BaseAuthProvider, 'workos'),
+    __metadata("design:paramtypes", [Object])
+], WorkOSProvider);
+export { WorkOSProvider };
+//# sourceMappingURL=WorkOSProvider.js.map

package/dist/providers/WorkOSProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"WorkOSProvider.js","sourceRoot":"","sources":["../../src/providers/WorkOSProvider.ts"],"names":[],"mappings":";;;;;;;;;AACA,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAEvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAG1D;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEI,IAAM,cAAc,GAApB,MAAM,cAAe,SAAQ,gBAAgB;IAClD,YAAY,MAA0B;QACpC,KAAK,CAAC,MAAM,CAAC,CAAC;IAChB,CAAC;IAED;;;;;;;OAOG;IACH,eAAe,CAAC,OAAmB;QACjC,MAAM,KAAK,GAAG,OAAO,CAAC,KAA2B,CAAC;QAClD,MAAM,QAAQ,GAAG,OAAO,CAAC,IAA0B,CAAC;QACpD,MAAM,SAAS,GAAG,OAAO,CAAC,UAAgC,CAAC;QAC3D,MAAM,QAAQ,GAAG,OAAO,CAAC,WAAiC,CAAC;QAC3D,kFAAkF;QAClF,MAAM,iBAAiB,GAAG,OAAO,CAAC,kBAAwC,IAAI,KAAK,CAAC;QACpF,4DAA4D;QAC5D,MAAM,MAAM,GAAG,OAAO,CAAC,GAAyB,CAAC;QAEjD,OAAO;YACL,KAAK;YACL,SAAS,EAAE,SAAS,IAAI,QAAQ,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;YAC/C,QAAQ,EAAE,QAAQ,IAAI,QAAQ,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,QAAQ,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;YACxE,QAAQ;YACR,iBAAiB;YACjB,MAAM;SACP,CAAC;IACJ,CAAC;IAED;;;;;;OAMG;IACH,cAAc;QACZ,MAAM,SAAS,GAAG,KAAK,CAAC,cAAc,EAAE,CAAC;QACzC,MAAM,WAAW,GAAG,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC;QAE3C,OAAO,SAAS,IAAI,WAAW,CAAC;IAClC,CAAC;CACF,CAAA;AA9CY,cAAc;IAD1B,aAAa,CAAC,gBAAgB,EAAE,QAAQ,CAAC;;GAC7B,cAAc,CA8C1B"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memberjunction/auth-providers",
-  "version": "5.43.0",
+  "version": "5.44.0",
   "description": "Authentication provider interfaces, base classes, and implementations for MemberJunction",
   "type": "module",
   "main": "./dist/index.js",
@@ -11,8 +11,8 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@memberjunction/core": "5.43.0",
-    "@memberjunction/global": "5.43.0",
+    "@memberjunction/core": "5.44.0",
+    "@memberjunction/global": "5.44.0",
     "graphql": "^16.12.0",
     "jsonwebtoken": "9.0.3",
     "jwks-rsa": "^3.2.2"

package/src/AuthProviderFactory.ts

@@ -9,6 +9,7 @@ import './providers/MSALProvider.js';
 import './providers/OktaProvider.js';
 import './providers/CognitoProvider.js';
 import './providers/GoogleProvider.js';
+import './providers/WorkOSProvider.js';
 import './providers/MagicLinkProvider.js';
 
 /**

package/src/__tests__/WorkOSProvider.test.ts

@@ -0,0 +1,169 @@
+/**
+ * Unit tests for WorkOSProvider.
+ *
+ * Covers the two pieces of logic the provider owns on top of BaseAuthProvider:
+ *   - extractUserInfo(): mapping WorkOS AuthKit JWT claims → AuthUserInfo, including the
+ *     fallbacks that keep a usable identity when a custom JWT Template only sets `name`.
+ *   - validateConfig(): the WorkOS-specific requirement (clientId) on top of the base fields.
+ *
+ * It also asserts the provider registers with the class factory under the `workos` key, which
+ * is what makes `AuthProviderFactory.createProvider({ type: 'workos', ... })` resolve it.
+ */
+import { describe, it, expect } from 'vitest';
+import type { JwtPayload } from 'jsonwebtoken';
+import { MJGlobal } from '@memberjunction/global';
+import { AuthProviderConfig } from '@memberjunction/core';
+import { BaseAuthProvider } from '../BaseAuthProvider';
+import { WorkOSProvider } from '../providers/WorkOSProvider';
+
+const CLIENT_ID = 'client_01HABCDEF';
+
+function makeConfig(overrides: Partial<AuthProviderConfig> = {}): AuthProviderConfig {
+  return {
+    name: 'workos-test',
+    type: 'workos',
+    issuer: `https://api.workos.com/user_management/${CLIENT_ID}`,
+    audience: CLIENT_ID,
+    jwksUri: `https://api.workos.com/sso/jwks/${CLIENT_ID}`,
+    clientId: CLIENT_ID,
+    ...overrides,
+  };
+}
+
+function makeProvider(overrides: Partial<AuthProviderConfig> = {}): WorkOSProvider {
+  return new WorkOSProvider(makeConfig(overrides));
+}
+
+describe('WorkOSProvider', () => {
+  describe('extractUserInfo', () => {
+    it('maps a token shaped by the recommended JWT Template (email + given/family name)', () => {
+      const provider = makeProvider();
+      const payload: JwtPayload = {
+        sub: 'user_01HXYZ',
+        email: 'ada@example.com',
+        given_name: 'Ada',
+        family_name: 'Lovelace',
+      };
+
+      const info = provider.extractUserInfo(payload);
+
+      expect(info.email).toBe('ada@example.com');
+      expect(info.firstName).toBe('Ada');
+      expect(info.lastName).toBe('Lovelace');
+      // No preferred_username on WorkOS tokens — falls back to email.
+      expect(info.preferredUsername).toBe('ada@example.com');
+      // `sub` is surfaced as the provider user id.
+      expect(info.userId).toBe('user_01HXYZ');
+    });
+
+    it('derives first/last name from a single `name` claim when given/family are absent', () => {
+      const provider = makeProvider();
+      const payload: JwtPayload = {
+        sub: 'user_01HXYZ',
+        email: 'grace.hopper@example.com',
+        name: 'Grace Hopper',
+      };
+
+      const info = provider.extractUserInfo(payload);
+
+      expect(info.fullName).toBe('Grace Hopper');
+      expect(info.firstName).toBe('Grace');
+      expect(info.lastName).toBe('Hopper');
+    });
+
+    it('falls back to the single name token for both first and last when name has one word', () => {
+      const provider = makeProvider();
+      const payload: JwtPayload = { sub: 'user_1', email: 'cher@example.com', name: 'Cher' };
+
+      const info = provider.extractUserInfo(payload);
+
+      expect(info.firstName).toBe('Cher');
+      expect(info.lastName).toBe('Cher');
+    });
+
+    it('prefers explicit given_name/family_name over the `name` split', () => {
+      const provider = makeProvider();
+      const payload: JwtPayload = {
+        sub: 'user_2',
+        email: 'jean.luc@example.com',
+        name: 'Wrong Split',
+        given_name: 'Jean-Luc',
+        family_name: 'Picard',
+      };
+
+      const info = provider.extractUserInfo(payload);
+
+      expect(info.firstName).toBe('Jean-Luc');
+      expect(info.lastName).toBe('Picard');
+    });
+
+    it('honors an explicit preferred_username when present', () => {
+      const provider = makeProvider();
+      const payload: JwtPayload = {
+        sub: 'user_3',
+        email: 'alan@example.com',
+        preferred_username: 'aturing',
+      };
+
+      const info = provider.extractUserInfo(payload);
+
+      expect(info.preferredUsername).toBe('aturing');
+    });
+
+    it('returns undefined email (rather than throwing) when no JWT Template added it', () => {
+      // This is the default WorkOS access token shape — identity/session claims only.
+      const provider = makeProvider();
+      const payload: JwtPayload = {
+        sub: 'user_4',
+        sid: 'session_01H',
+        org_id: 'org_01H',
+        role: 'admin',
+      };
+
+      const info = provider.extractUserInfo(payload);
+
+      expect(info.email).toBeUndefined();
+      expect(info.userId).toBe('user_4');
+      expect(info.preferredUsername).toBeUndefined();
+    });
+  });
+
+  describe('validateConfig', () => {
+    it('is valid with the full WorkOS config (base fields + clientId)', () => {
+      expect(makeProvider().validateConfig()).toBe(true);
+    });
+
+    it('is invalid without a clientId', () => {
+      expect(makeProvider({ clientId: undefined }).validateConfig()).toBe(false);
+    });
+
+    it('is invalid when a base field (audience) is missing', () => {
+      expect(makeProvider({ audience: '' }).validateConfig()).toBe(false);
+    });
+
+    it('exposes clientId on the instance for the OAuth proxy path', () => {
+      expect(makeProvider().clientId).toBe(CLIENT_ID);
+    });
+  });
+
+  describe('class-factory registration', () => {
+    it('is registered under the lowercase `workos` key and instantiable via the factory', () => {
+      const instance = MJGlobal.Instance.ClassFactory.CreateInstance<BaseAuthProvider>(
+        BaseAuthProvider,
+        'workos',
+        makeConfig(),
+      );
+
+      expect(instance).toBeInstanceOf(WorkOSProvider);
+    });
+  });
+
+  describe('issuer matching (inherited)', () => {
+    it('matches its configured issuer case-insensitively and ignores a trailing slash', () => {
+      const provider = makeProvider();
+      expect(provider.matchesIssuer(`https://api.workos.com/user_management/${CLIENT_ID}`)).toBe(true);
+      expect(provider.matchesIssuer(`https://api.workos.com/user_management/${CLIENT_ID}/`)).toBe(true);
+      expect(provider.matchesIssuer('https://api.workos.com/user_management/other')).toBe(false);
+    });
+  });
+});

package/src/providers/WorkOSProvider.ts

@@ -0,0 +1,78 @@
+import { JwtPayload } from 'jsonwebtoken';
+import { RegisterClass } from '@memberjunction/global';
+import { AuthProviderConfig, AuthUserInfo } from '@memberjunction/core';
+import { BaseAuthProvider } from '../BaseAuthProvider.js';
+
+
+/**
+ * WorkOS (AuthKit) authentication provider implementation.
+ *
+ * Validates JWT access tokens minted by WorkOS AuthKit / User Management. These tokens are
+ * signed with RS256 and verified against the per-environment JWKS endpoint
+ * (`https://api.workos.com/sso/jwks/<clientId>`); their `iss` claim is
+ * `https://api.workos.com/user_management/<clientId>`.
+ *
+ * ## Email is required — and is NOT in a WorkOS token by default
+ * MemberJunction resolves the signed-in user by **email**, but a WorkOS AuthKit access token
+ * only carries identity/session claims (`sub`, `sid`, `org_id`, `role`, `permissions`) out of
+ * the box — it does **not** include `email`. To use WorkOS with MJ you must add the email (and
+ * ideally the name) to the token via a WorkOS **JWT Template**:
+ *
+ * ```json
+ * {
+ *   "email": "{{user.email}}",
+ *   "given_name": "{{user.first_name}}",
+ *   "family_name": "{{user.last_name}}"
+ * }
+ * ```
+ *
+ * See `WORKOS.md` in this package for the full, step-by-step integration guide.
+ */
+@RegisterClass(BaseAuthProvider, 'workos')
+export class WorkOSProvider extends BaseAuthProvider {
+  constructor(config: AuthProviderConfig) {
+    super(config);
+  }
+
+  /**
+   * Extracts user information from a WorkOS AuthKit JWT payload.
+   *
+   * `email`, `given_name`, and `family_name` are expected to be supplied by a WorkOS JWT
+   * Template (see class docs). `sub` is the stable WorkOS user id (`user_...`). We fall back
+   * through standard OIDC claim names so a token shaped by a custom template (e.g. one that
+   * only sets `name`) still resolves a usable identity.
+   */
+  extractUserInfo(payload: JwtPayload): AuthUserInfo {
+    const email = payload.email as string | undefined;
+    const fullName = payload.name as string | undefined;
+    const firstName = payload.given_name as string | undefined;
+    const lastName = payload.family_name as string | undefined;
+    // WorkOS access tokens have no `preferred_username`; email is the natural handle.
+    const preferredUsername = payload.preferred_username as string | undefined || email;
+    // `sub` is the WorkOS user identifier (e.g. "user_01H...").
+    const userId = payload.sub as string | undefined;
+
+    return {
+      email,
+      firstName: firstName || fullName?.split(' ')[0],
+      lastName: lastName || fullName?.split(' ')[1] || fullName?.split(' ')[0],
+      fullName,
+      preferredUsername,
+      userId
+    };
+  }
+
+  /**
+   * Validates WorkOS-specific configuration.
+   *
+   * Beyond the base requirements (`name`, `issuer`, `audience`, `jwksUri`), WorkOS needs a
+   * `clientId` — it appears in both the issuer and JWKS URLs and identifies the AuthKit
+   * environment.
+   */
+  validateConfig(): boolean {
+    const baseValid = super.validateConfig();
+    const hasClientId = !!this.config.clientId;
+
+    return baseValid && hasClientId;
+  }
+}