https://github.com/dirnbauer/workos

TYPO3 v14 extension for WorkOS-powered frontend and backend login.
https://github.com/dirnbauer/workos

Last synced: 4 months ago
JSON representation

TYPO3 v14 extension for WorkOS-powered frontend and backend login.

• Host: GitHub
• URL: https://github.com/dirnbauer/workos
• Owner: dirnbauer
• Created: 2026-04-10T20:22:59.000Z (4 months ago)
• Default Branch: main
• Last Pushed: 2026-04-16T12:27:46.000Z (4 months ago)
• Last Synced: 2026-04-16T12:32:51.834Z (4 months ago)
• Language: PHP
• Size: 118 KB
• Stars: 0
• Watchers: 0
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

README

          
# WorkOS Auth for TYPO3 14

`workos_auth` adds [WorkOS](https://workos.com) authentication to both the

TYPO3 **frontend** and the TYPO3 **backend**. It supports the full WorkOS

AuthKit feature set: email + password, passwordless magic auth, and

social sign-in with Google, Microsoft, GitHub, and Apple.

Requirements: TYPO3 `^14.0`, PHP `^8.2`. Current release: **0.25.0**.

---

## What you get

| Area | Feature |

|---|---|

| **WorkOS Login** plugin | Email + password form, magic-auth form, social buttons, self sign-up |

| **WorkOS Login** plugin | Shows the current WorkOS profile (including custom metadata) when signed in |

| **WorkOS Account Center** plugin | Self-service profile, password, MFA, sessions and organizations for signed-in users |

| **WorkOS Team** plugin | Send/resend/revoke teammate invitations and launch one-time WorkOS Admin Portal sessions (SSO, SCIM, audit logs, …) |

| Backend login | "Continue with WorkOS" button, email-code login, social sign-in |

| Backend module | Setup assistant at `System > WorkOS Auth` (no PHP editing required) |

| Provisioning | Create or link TYPO3 users from WorkOS identities (frontend & backend) |

| Storage | Identity mapping table `tx_workosauth_identity` (with full WorkOS profile JSON) |

| Localization | English and German out of the box, XLIFF 1.2 with ICU MessageFormat |

## Quick install

```bash

composer require webconsulting/workos-auth

```

1. Activate the extension in TYPO3.

2. Open **System > WorkOS Auth** in the backend.

3. Enter your **API key**, **Client ID**, and a **cookie password** (≥ 32 characters).

4. Copy all **Redirect URIs** from the setup assistant into the WorkOS Dashboard.

5. In the WorkOS Dashboard, enable the authentication methods you need (Magic Auth, Email + Password, Social providers).

6. Add the **WorkOS Login** content element to a frontend page.

A detailed walk-through is in [`Documentation/Configuration.rst`](Documentation/Configuration.rst).

## Frontend login

Place the **WorkOS Login** plugin on a page and users get a ready-to-go card:

- Email + password form

- "Email me a login code" (magic auth, six-digit code)

- One-tap social buttons (Google, Microsoft, GitHub, Apple)

- Link to the native sign-up form

Signed-in users see their WorkOS profile, including any **custom metadata**

stored on the WorkOS user record.

Detailed feature guide: [`Documentation/Features.rst`](Documentation/Features.rst).

## Account Center (frontend)

Drop the **WorkOS Account Center** plugin on any page that signed-in

users can reach (typically a "My account" page) and they get a

self-service hub backed by the WorkOS API:

- **Profile** — update first and last name (synced back to WorkOS via

  `UserManagement::updateUser`)

- **Password** — change the WorkOS password without leaving the site,

  with friendly errors for too-short, too-weak and breached passwords

- **Two-factor authentication** — enroll an authenticator app (TOTP).

  The QR code is generated by WorkOS and rendered inline; a fallback

  manual secret is shown for users who can't scan

- **Active sessions** — list every WorkOS session for the user with

  IP, browser/OS summary and expiry, plus a one-click "Sign out" to

  revoke any individual session ("sign me out of other devices")

- **Organizations** — list every organization (and role) the user

  belongs to, including a "Directory sync" badge for memberships

  managed by an external IdP

Each section degrades gracefully: a failure of one WorkOS call only

disables that single card and shows a friendly message.

## Team workspace (frontend)

Drop the **WorkOS Team** plugin on a page reserved for organization

admins (typically a "Team" or "Workspace" page). It turns any TYPO3

frontend into a thin wrapper around the WorkOS B2B feature set:

- **Organization switcher** — if the signed-in user belongs to more

  than one active WorkOS organization, they pick which one to manage

  (the choice is sticky for the session).

- **Admin Portal launchers** — one-click buttons that mint a signed,

  organization-scoped link into the WorkOS Admin Portal for every

  supported intent: **SSO**, **Directory Sync (SCIM)**, **Audit Logs**,

  **Log Streams**, **Domain Verification** and **Certificate Renewal**.

  This is the same flow WorkOS recommends so customer IT admins can

  self-serve enterprise setup without you ever exchanging credentials.

- **Send invitations** — invite teammates by email with an optional

  role slug; WorkOS dispatches the email and tracks acceptance.

- **Pending invitations list** — see every recent invitation with its

  state badge (Pending / Accepted / Expired / Revoked), expiry date

  and accept-link, plus inline **Resend** and **Revoke** actions.

The plugin requires a frontend user that is linked to a WorkOS

identity (i.e. signed in via the WorkOS Login plugin). If that user

isn't a member of any active organization, a friendly empty-state

card explains what to do.

## Backend login

TYPO3's backend login gains a WorkOS section with:

- "Continue with WorkOS" (full AuthKit experience)

- Social sign-in buttons

- An email field that sends a six-digit magic-auth code

- A visible code-entry step for verification

Standard TYPO3 username + password login keeps working in parallel via

the "Login with username and password" switcher.

> **Heads-up — "This WorkOS account is not linked to a TYPO3 user":**

> If a user authenticates successfully with WorkOS but no matching

> `be_users` record exists and `backendAutoCreateUsers` is off, the

> backend login shows that error card together with the WorkOS e-mail

> and id. Either set the e-mail on an existing backend user, or enable

> auto-create with a domain allowlist in the setup assistant. Full

> walk-through:

> [Troubleshooting → "This WorkOS account is not linked to a TYPO3 user"](Documentation/Troubleshooting.rst).

## WorkOS Dashboard setup

All authentication methods (AuthKit, Magic Auth, Email + Password, Social

providers) are **enabled in the WorkOS Dashboard**, not in TYPO3.

See [`Documentation/WorkosDashboard.rst`](Documentation/WorkosDashboard.rst)

for step-by-step screenshots of:

- Adding Redirect URIs

- Enabling Magic Auth

- Enabling social providers

## Dynamic AuthKit parameters

The frontend login URL accepts optional query parameters that customise

the AuthKit experience without changing any TYPO3 configuration:

| Query param | Value | Effect |

|---|---|---|

| `screen` | `sign-in` or `sign-up` | Open AuthKit on the given screen |

| `provider` | `GoogleOAuth`, `MicrosoftOAuth`, `GitHubOAuth`, `AppleOAuth` | Jump directly to one social provider |

| `login_hint` | Any email | Pre-fill the email field |

| `organization` | WorkOS organization id | Scope the login to an organization |

| `returnTo` | Target URL | Where to land after login |

Example — open the hosted sign-up screen pre-filled with an email:

```

/workos-auth/frontend/login?screen=sign-up&login_hint=jane@example.com

```

## Configuration location

Settings live in TYPO3 extension configuration under

`EXTENSIONS.workos_auth`. In a Composer-based TYPO3 14 project they are

persisted to `config/system/settings.php`, which is the right place for

installation-wide auth secrets.

The full list of keys is in

[`Documentation/Configuration.rst`](Documentation/Configuration.rst).

## Documentation

- [Configuration](Documentation/Configuration.rst) – Setup assistant, every config key, workspaces behaviour

- [Features](Documentation/Features.rst) – Frontend/backend flows, profile display, dynamic parameters

- [WorkOS Dashboard](Documentation/WorkosDashboard.rst) – Redirect URIs and enabling auth methods

- [Troubleshooting](Documentation/Troubleshooting.rst) – Common errors and fixes

- [Changelog](Documentation/Changelog.rst) – Release notes

- [Audit reports](Documentation/Reports/) – Workspaces, upgrade, conformance, security, testing, docs

## Security

The extension takes an auth-first stance. Notable guarantees:

- **Authorization on Team actions**: every Team plugin action

  verifies the signed-in WorkOS user is an active member of the

  organization the POST references before calling the SDK. Stops

  cross-tenant invite / revoke / Admin-Portal-link mints via crafted

  POST bodies.

- **CSRF tokens** are enforced on every state-changing action of the

  Account Center and Team plugins (password change, MFA, session

  revoke, invitations, Admin Portal launch) and on the backend

  User Management module's widget-token, join, and

  create-organization routes.

- **Admin guard** is asserted inside the backend

  `UserManagementController` in addition to the module's

  `access => 'admin'` gate — defence in depth if the module is ever

  re-registered outside admin access.

- **No open-redirects**: `returnTo` parameters only accept strict

  relative paths or absolute URLs on the same scheme+host+port as the

  request. Protocol-relative (`//evil.example`) and backslash variants

  fall back to the configured default redirect.

- **Secrets never hit logs**: all log entries run through a

  `SecretRedactor` that strips WorkOS API keys, client ids, bearer

  tokens, and JWTs. Unknown WorkOS error bodies fall back to a

  translated `error.generic` instead of leaking into redirect URLs.

- **Workspaces-safe**: the identity mapping table is `adminOnly`,

  `hideTable`, and pinned to `versioningWS=false` so workspace

  drafts can never mutate live authentication state. The three

  WorkOS backend modules are registered with `workspaces => 'live'`

  and only appear in the LIVE workspace.

All third-sweep audit reports live under

[`Documentation/Reports/`](Documentation/Reports/).

## Quality

- PHPStan **level max** (10 on 2.x) with

  `saschaegerer/phpstan-typo3 ^3.0` — run `composer phpstan`.

- **82 unit tests** (151 assertions), including regressions for

  every security fix, a TCA contract guard on the identity table,

  and XLIFF parity between English and German — run

  `composer test:unit`.

- Functional tests cover `IdentityService` round-trips (including

  under a workspace aspect) and `UserProvisioningService`

  create-or-link flows via `typo3/testing-framework ^9.2`.

- Uniform entry point: `Build/Scripts/runTests.sh -s ci` runs

  PHPStan + unit tests with the same flags locally and in CI.

## Licence

GPL-2.0-or-later