Integration with WorkOS
| 开发者 | bordoni |
|---|---|
| 更新时间 | 2026年5月13日 03:17 |
| 捐献地址: | 去捐款 |
| PHP版本: | 7.4 及以上 |
| WordPress版本: | 6.9 |
| 版权: | GPL-2.0-or-later |
| 版权网址: | 版权信息 |
详情介绍:
Integration with WorkOS connects your WordPress site with WorkOS for enterprise-grade identity management.
Requirements
- WordPress 6.2 or higher
- PHP 7.4 or higher
- A WorkOS account with API credentials
- WordPress-hosted React login — no redirect to WorkOS for password, magic code, signup, invitation, or MFA. Mounts on wp-login.php, a shortcode (
[workos:login]), and a dedicated/workos/login/{profile}route. - Login Profiles — admin-defined presets (enabled sign-in methods, pinned organization, signup/invite toggles, MFA policy, branding) edited from WorkOS → Login Profiles. The organization picker loads live from WorkOS so admins pick an org by name instead of pasting raw IDs.
- Per-profile custom URL paths — assign any profile its own URL (e.g.
/members,/team/login) on top of the canonical/workos/login/{profile}rewrite. When the default profile owns a custom path,/wp-login.php302s to it (preserving every inbound query arg). Reserved core paths can't be claimed. - Already-signed-in handling — visitors who hit any AuthKit surface while logged in are 302'd to their post-login destination (or, in the shortcode, see an inline "You're already signed in" notice with a Continue link).
forward_query_argsper-profile toggle — opt-in passing of marketing/analytics query args (utm_*,ref, etc.) onto the post-login destination. WP and plugin internals are always stripped.- Sign-in methods — email + password, magic code, social OAuth (Google, Microsoft, GitHub, Apple), and passkey. Each profile chooses its own subset.
- MFA — TOTP, SMS, and WebAuthn/passkey with in-app enrollment + challenge. Profile-level
mfa.enforce(never/if_required/always) and factor allowlist are applied at login time. - Self-serve sign-up + invitation acceptance + in-app password reset — all handled by the React shell; no third-party pages.
- Branding controls — per-profile heading, subheading, primary color (with WordPress admin-color presets), and logo with a three-mode toggle (
defaultfalls back to the Site Icon then a bundled WP logo,customuses the chosen image,nonehides the logo). - Embed & URLs in the editor — every Login Profile shows copyable input fields for its canonical URL, optional custom-path URL, and shortcode so admins can paste them into pages or share them with users.
- WorkOS Radar anti-fraud integration optional via
WORKOS_RADAR_SITE_KEY. - Profile routing rules — send incoming logins to a specific profile based on
redirect_to, referrer host, or user role.
- Single Sign-On (SSO) — legacy AuthKit redirect mode, per-profile selectable for SAML/OIDC connections.
- Headless mode — intercept WordPress's
authenticatefilter for custom login forms. - Legacy Login Button — Gutenberg block and classic widget (AuthKit-redirect flow).
- Login Bypass — Access the native WordPress login form via
?fallback=1when WorkOS is unavailable. - Password Reset Integration — Redirect password reset to WorkOS or fall back to WordPress.
- Registration Redirect — Redirect registration to WorkOS AuthKit.
- REST API Authentication — Verify WorkOS access tokens for headless/API usage.
- Directory Sync — Automatic user provisioning and deprovisioning via SCIM.
- Role Mapping — Map WorkOS organization roles to WordPress roles.
- Organization Management — Multi-tenant organization support.
- Entitlement Gate — Require organization membership to log in.
- Role-Based Login Redirects — Send users to different URLs after login based on their WordPress role.
- Role-Based Logout Redirects — Send users to different URLs after logout based on their WordPress role.
- Activity Logging — Local database table with admin viewer for tracking authentication and sync events.
- Audit Logging — Forward WordPress events to WorkOS Audit Logs.
- Diagnostics Page — System health checks, configuration status, and connectivity tests.
- Onboarding Wizard — Guided setup for initial plugin configuration and user sync.
- Admin Bar Badge — Shows the active WorkOS environment in the admin bar.
- WP-CLI Commands — Full CLI access for scripting, bulk operations, and diagnostics.
安装:
- Go to Plugins > Add New in your WordPress admin and search for "Integration with WorkOS".
- Click Install Now, then Activate.
- Go to Settings > WorkOS and enter your API Key and Client ID from the WorkOS Dashboard.
- Configure your webhook endpoint in the WorkOS Dashboard using the URL shown on the settings page.
- (Optional) Run the Onboarding Wizard at Settings > WorkOS > Onboarding for guided setup.
屏幕截图:
常见问题:
Where do I get my API credentials?
Sign up at workos.com and find your API Key and Client ID in the dashboard.
Can users still log in with passwords?
Yes, if "Password Fallback" is enabled in settings. Users can access the standard login form via ?fallback=1.
How do I add a login button to my site?
Add the "WorkOS Login" Gutenberg block or use the "WorkOS Login" classic widget. Both render a styled login button that redirects to WorkOS AuthKit.
How do I show the new WordPress-hosted login (Custom AuthKit) on a page?
Use [workos:login profile="your-profile-slug"] or link to /workos/login/{profile}. Both mount the same React shell. The reserved default Login Profile automatically takes over wp-login.php.
Can different login pages offer different sign-in methods?
Yes. Each Login Profile (WorkOS → Login Profiles) picks its own set of enabled methods (password, magic code, any subset of social providers, passkey), pins an organization, and sets its own MFA policy and branding. Reference a profile by slug in the shortcode or URL.
Can I host a Login Profile at a custom URL like /members?
Yes. Edit any profile and tick Use a custom URL path, then fill in the path (e.g. members or team/login). The plugin registers an extra rewrite rule that mounts the same React shell at https://yoursite.com/members/. The canonical /workos/login/{slug} URL keeps working too. Reserved core paths (wp-admin, wp-includes, wp-content, wp-json, workos, feed, etc.) are blocked at save time. If you set a custom path on the default profile, /wp-login.php?action=login 302s to it for everyone (with all redirect_to / interim-login / language / nonce args preserved).
What happens if WorkOS is down?
Users can bypass the WorkOS redirect by appending ?fallback=1 to the login URL (e.g., wp-login.php?fallback=1). This loads the standard WordPress login form with native password authentication.
Can I require organization membership to log in?
Yes. The Entitlement Gate feature restricts login to users who belong to the configured WorkOS organization. Users without a membership are denied access with a customizable error message.
How do I sync existing WordPress users to WorkOS?
Use the Onboarding Wizard (Settings > WorkOS > Onboarding) for a guided walkthrough, or use the WP-CLI command wp workos sync push to bulk-push users to WorkOS.
Does this plugin support WordPress multisite?
Yes. Organizations can be mapped to specific sites in a multisite network, and the plugin stores organization-to-site mappings in a dedicated table.
How do I run diagnostics?
Go to Tools > WorkOS Diagnostics in the WordPress admin. The diagnostics page checks API connectivity, configuration completeness, database schema status, and other health indicators.
更新日志:
1.0.3 - 2026-05-12
- Fix: AuthKit login flows now recover transparently from WorkOS
organization_selection_required. When the Login Profile has an organization pinned (withConfig::get_organization_id()as a fallback), the plugin re-authenticates via theorganization-selectiongrant instead of surfacing "The user must choose an organization to finish their authentication." to the user. - Fix: pre-existing WordPress users who joined before an organization was pinned are now auto-enrolled into the pinned WorkOS organization. The plugin creates the WorkOS membership and retries the authenticate call when (and only when) a matching local WP user exists and the WorkOS error body carries the authenticated
user_id. Membership creation and theentity_already_existsshort-circuit are logged viaworkos_log()(visible underWP_DEBUG/WORKOS_DEBUG). Strangers and ambiguous lookups still get a cleanpinned_org_mismatcherror — no email-lookup guessing. - Fix: the legacy OAuth callback at
/workos/callbacknow routes throughLoginCompleter, so it shares the sameorganization_selection_requiredrecovery, MFA gating, and post-login bookkeeping as the AuthKit REST endpoints. The callback no longer short-circuits on the WorkOS error and discards the OAuth code. Legacy AuthKit-redirect callbacks (no profile slug instate) keep their original redirect contract — the state-suppliedredirect_tostill wins over the default profile'spost_login_redirect.
- New: WordPress password fallback — if WorkOS rejects a password, the auth endpoint can retry against WordPress's own
wp_authenticate()to cover users whose passwords were never synced to WorkOS, then link the user to WorkOS and (by default) write the password through so future logins authenticate directly. A new "Require Email Confirmation on Fallback" setting switches the post-fallback step to a magic-code email instead of syncing the plaintext password. Gated by the existingallow_password_fallbacktoggle. - New: wp-config.php constant seeder — defining
WORKOS_*(or env-scopedWORKOS_{PRODUCTION|STAGING}_*) constants now seeds those values into the database on boot, so the admin UI reflects them. Covers string credentials, the new boolean toggles, andWORKOS_REDIRECT_URLSarrays. Hash-skipped when nothing has changed — one autoloaded option read per request in steady state. - Fix: Auth REST endpoints under
/wp-json/workos/v1/auth/*now read the nonce fromX-WorkOS-Nonceinstead ofX-WP-Nonceto avoid a header collision with WordPress core and other plugins. The bundled React shell is updated; external clients hitting these endpoints directly must rename the header.
- New: Organization tab — manual Refresh button next to the organization dropdown re-fetches organizations from WorkOS on demand via the admin REST endpoint (no admin-ajax), bypassing the 5-minute cache. The dropdown is blocked with a spinner during the refresh and the selected organization is preserved when it still exists.
- New:
?refresh=1query parameter onGET /wp-json/workos/v1/admin/profiles/organizationsto drop the shared transient before fetching. - Fix: Organization tab — "Save Settings" was blocked by a hidden, required
org_nameinput. The Create Organization modal is now rendered atadmin_footerso its inner<form>is no longer nested inside the settings form. - Fix: Active environment is now stored in a single place. The admin Settings UI wrote to
workos_active_environmentwhile the runtime auth flow read fromworkos_global['active_environment'], so picking "Production" still loaded staging credentials and redirected to the staging AuthKit. The runtime now reads/writes the standalone option, with a one-time migration (db_version 2 → 3) that moves any legacy value out ofworkos_global.
- React login shell on wp-login.php,
[workos:login]shortcode, and/workos/login/{profile}route. - Login Profiles — admin-defined presets for enabled methods, pinned organization, signup/invite/reset flows, MFA policy, and branding, managed at WorkOS → Login Profiles.
- Per-profile custom URL paths (e.g.
/members,/team/login) on top of the canonical/workos/login/{slug}rewrite. The default profile can claim a custom path so/wp-login.phpbounces to it. Reserved core paths are blocked. - Already-signed-in visitors are 302'd to their post-login destination on every AuthKit surface (or shown an inline "You're already signed in" notice in the shortcode).
- Per-profile
forward_query_argstoggle to pass marketing/analytics args onto the post-login destination (internals always stripped). - Pinned-organization picker in the Profile editor reads live from WorkOS (with a "Custom ID…" fallback for legacy or unlisted orgs), and the Profiles list renders organization names instead of raw IDs.
- Embed & URLs section in the editor exposes copyable input fields for the canonical URL, the optional custom-path URL, and the
[workos:login profile="…"]shortcode. - Sign-in methods: email + password, magic code, social OAuth (Google, Microsoft, GitHub, Apple), passkey.
- Full MFA support — TOTP, SMS, WebAuthn/passkey with in-app enrollment + challenge.
- Self-serve sign-up, invitation acceptance, and in-app password reset.
- Branding — heading, subheading, primary color (defaults to WordPress admin-color palette), and three-mode logo control (
defaultfalls back to Site Icon → bundled WP logo,customuses the chosen attachment,nonehides the logo). - SlotFill extensibility — ten named slots (including
workos.authkit.belowCard, which renders standard wp-login.php links by default) for plugins to inject React elements into the login UI. - Profile routing rules (redirect_to glob / referrer host / user role).
- WorkOS Radar anti-fraud integration (set
WORKOS_RADAR_SITE_KEY). - Public REST at
/wp-json/workos/v1/auth/*with profile-scoped nonces, per-IP/per-email rate limits, and signature-verified tokens. -
Full browser internationalization — every user-facing React/TS/JS string ships through
@wordpress/i18nwith theintegration-workostext domain andwp_set_script_translations()wiring. Base platform: - SSO login via WorkOS AuthKit (legacy redirect mode, per-profile selectable).
- Headless authentication via WorkOS API.
- Directory Sync (SCIM) for automatic user provisioning and deprovisioning.
- Role mapping between WorkOS organization roles and WordPress roles.
- Organization management with local caching and multisite support.
- Entitlement gate — require organization membership to log in.
- Webhook processing for user, organization, directory, membership, and connection events.
- REST API Bearer token authentication using WorkOS access tokens.
- Legacy login button Gutenberg block and classic widget (AuthKit-redirect flow).
- Login bypass via
?fallback=1for native WordPress login when WorkOS is unavailable. - Activity logging with local database table and admin viewer.
- Audit logging — forward WordPress events to WorkOS Audit Logs.
- Role-based login redirects with per-role URL configuration.
- Role-based logout redirects with per-role URL configuration.
- Password reset integration with WorkOS.
- Registration redirect to WorkOS AuthKit.
- Admin bar badge showing active environment (production/staging).
- Diagnostics page with health checks and connectivity tests.
- Onboarding wizard for guided first-time setup.
- WP-CLI commands for status, user management, organization management, and bulk sync.