Shipping with WorkOS?

WorkOS SSO or SCIM giving odd results? We ship it properly.

WorkOS gets you an enterprise-ready SSO and SCIM path in days rather than months, but the day a prospect sends their IdP metadata and nothing matches, or a Directory Sync webhook deletes half an organization, the clean demo is suddenly a production incident. We work through the connections, the events and your own user-provisioning code until the pipe lines up again.

  • Since 2015Fixing technology
  • FreeEstimates
  • US teamReal engineers

workos-events.log

still failing

What it is

WorkOS at a glance

WorkOS is a developer-first platform for the parts of authentication that enterprises ask for: SAML and OIDC single sign-on, SCIM user and group provisioning, Directory Sync against Okta, Azure AD, Google Workspace and a long tail of smaller IdPs, plus Admin Portal, Audit Logs and AuthKit. It was founded in 2019 and is used by teams who want one integration instead of writing a connector per enterprise customer.

The pitch is that a mid-market B2B product can offer all of that through one API and one dashboard, and ship a tenant in an afternoon rather than a sprint. In practice the first few customer rollouts still involve IdP metadata that fails signature checks, SCIM clients that treat your schema in creative ways, and Directory Sync events that arrive in a different order than your database expects.

Type
B2B authentication and user management platform
First released
2019
License
Proprietary API, per-connection pricing
Maintained by
WorkOS, Inc.
Typically used for
Enterprise SSO (SAML, OIDC), SCIM provisioning, Directory Sync, Audit Logs, Admin Portal

The honest version

WorkOS pros and cons

No technology is all upside. This is where WorkOS earns its place and where it tends to cause trouble.

Where WorkOS is strong

  • One integration for every IdPA single WorkOS connection abstracts Okta, Azure AD, Google, OneLogin, Ping and a dozen more, so you stop writing SAML quirks per customer.
  • Admin Portal removes a sales taskEnterprise admins configure their own connection in a hosted portal, which takes you out of the chain of screenshots and metadata emails.
  • SCIM done for youDirectory Sync normalizes user and group events across providers into one webhook feed, so your app sees a consistent shape.
  • AuthKit for new buildsA hosted login UI with social, passwordless and SSO fallbacks that skips the login-page project for teams that would rather ship features.
  • Reasonable developer ergonomicsOfficial SDKs for Node, Go, Python, Ruby and Java, and documentation that mostly matches what the API does.
  • Audit Logs and Events solve enterprise checklistsA compliant audit feed and a signed webhook stream cover items that would otherwise need a custom logging system.

Where WorkOS bites

  • Per-connection pricing bites at scaleEach enterprise SSO or Directory Sync tenant has a monthly line on the bill, and the total grows faster than most pricing pages suggest once you cross a few hundred customers.
  • You still own the matching logicWorkOS gives you a profile and a connection; deciding which existing user that matches, or whether to create one, is your code and your bugs.
  • Directory Sync events arrive out of orderA delete can land before the create it was meant to follow, and if your handler is not idempotent you get phantom users or orphan memberships.
  • SCIM clients interpret the spec looselyOkta, Azure and the smaller vendors all send slightly different PATCH operations. The spec is thin, and reality is thinner.
  • Debugging SAML remains unpleasantWhen an assertion is rejected the error is often one line, the fix is in the IdP, and the person who can change it works at the customer, not at you.
  • Lock-in is real if you build around AuthKitMoving user records, session shape and the hosted UI to another vendor later is a project, not a flag.

Sound familiar?

Common WorkOS problems we fix

The WorkOS problems that bring people to us, and what you have once each one is fixed.

sso.connection.invalid_metadata

IdP metadata is rejected on upload

A customer uploads a SAML metadata XML and WorkOS refuses it because the signing certificate is expired, the entity ID does not match, or the ACS URL in the file points at a staging host.

Connection active on first try

scim.user.create: externalId exists

SCIM provisioning collides with existing users

An admin flipped on SCIM for a tenant that already had manual users; now the IdP is trying to create accounts for emails that already exist, and WorkOS returns 409 all day.

Users merged, SCIM idempotent

directory_sync.user.deleted batch

Directory Sync deletes a cohort of users at once

A customer re-scoped their Okta group, the next poll reported dozens of removals, and your app soft-deleted them before anyone could stop it.

Deletes gated behind review

profile_mismatch

SSO login lands on the wrong account

The IdP sends an email that matches one WorkOS user but a different internal user, and the session attaches to the wrong tenant. The customer sees data that is not theirs.

Identity resolution deterministic

AuthKit: PKCE verifier missing

AuthKit redirect loops after login

Session cookies lost between the authorize call and the callback, usually because of a cookie domain mismatch or a reverse proxy stripping headers.

Login flow completing cleanly

connection_not_active

A tenant cannot sign in after setup

The Admin Portal shows the connection as draft, the customer thinks it is live, and every login attempt bounces back with a generic error.

Connection promoted and tested

events.endpoint: 429

Webhook consumer cannot keep up

A directory with 20,000 members replays through the events endpoint, your handler takes 800ms per event, WorkOS backs off, and the sync drifts hours behind.

Handler throughput raised

organization_domain_not_verified

Just-in-time provisioning refuses to create users

The organization in WorkOS has a domain claim that was never verified, so JIT silently stops and new employees get a confusing error on first login.

Domains verified, JIT working

What we do

WorkOS help, from first connection to steady state

Hire us for one stuck tenant, or for the whole enterprise rollout.

Rescue
A SAML connection that refuses to go live, a Directory Sync that is deleting real users, or a tenant that signs in as the wrong account. We stabilize the immediate damage and then explain what happened.
SSO and SCIM build-out
Picking the right connection type per customer, writing the user-matching logic, and testing against real IdP sandboxes rather than only the WorkOS mock.
Directory Sync handling
Idempotent webhook consumers, out-of-order event handling, and guardrails on bulk deletes so a customer re-scoping a group does not wipe their seats.
Migrations onto WorkOS
Moving from custom SAML, from Auth0 enterprise connections or from a legacy IdP library onto WorkOS without disrupting live tenants.
AuthKit adoption
Replacing a bespoke login page with AuthKit cleanly, handling session shape and the migration of existing users.
Managed Tech
Ongoing watch on your WorkOS events stream, tenant onboarding support, and an engineer on call the week a new enterprise goes live.

How it works

From first message to fixed

  1. Look Free estimate

    Tell us what's going wrong. We look at it, then tell you plainly what's wrong and what it will cost.

  2. Fix

    We fix the cause, not the symptom. If something is down, getting it back up comes first.

  3. Harden

    Backups, monitoring, updates and access, so the same problem can't quietly come back.

  4. Hand back or stay on

    You get a plain-language write-up. Or we stay on for hosting, upkeep and new work.

Often found together

Running WorkOS alongside something else?

We work on the whole stack, so the problem can be wherever it actually is.

Questions

WorkOS questions

Something else? Call+1 737 727 7327

Why does my customer's SAML metadata keep failing WorkOS validation?

In nine cases out of ten the uploaded XML either carries an expired signing certificate, points at an ACS URL that belongs to a different environment, or omits the signature element altogether because the IdP was configured to sign responses but not assertions. The error is terse; the fix sits in the IdP, which means working with your customer's admin rather than only with WorkOS.

Our Directory Sync keeps falling behind. What's wrong?

Usually the consumer. A webhook handler that takes a second per event cannot keep up with a directory of twenty thousand users replaying, and WorkOS rate-limits the retries. We profile the handler, batch what can be batched, and defer the slow work to a queue so the sync catches up.

Can we move from Auth0 enterprise connections to WorkOS without breaking existing users?

Yes, with care. The plan keeps Auth0 handling existing customers while new SSO tenants land on WorkOS, then moves tenants over one at a time with a mapped user table so sessions do not land on the wrong account on the first login. We script the cutover and run it tenant by tenant.

Why do users get provisioned twice through SCIM?

Either the IdP is pushing an externalId that does not match what your app already stored, or your SCIM handler creates on every POST instead of treating it as idempotent. The behavior gets worse when an admin disables and re-enables provisioning. The fix is a stable external identifier and a handler that upserts rather than inserts.

Should we use AuthKit or build our own login UI on top of WorkOS?

If you are early and do not already have a login page, AuthKit removes weeks of work. If you have a custom UI with brand, accessibility and copy that your marketing team cares about, keeping it and calling the SSO and SCIM APIs directly is the usual right call.

How much does WorkOS help cost?

The estimate is free. Send us the connection errors or the piece of the integration that is failing and we come back with a fixed price before any work starts.

Free estimate

WorkOS giving you trouble?

Tell us what you're running and what's going wrong. A person reads it and comes back with an estimate.

  • No charge to find out what it will take
  • If it's urgent, say so

Replies come from a person. By sending, you authorize us to email you back. No marketing.