English for WorkOS Developers

WorkOS exists to abstract away the messy details of enterprise identity — SSO, SCIM provisioning, directory sync — but a team integrating it still needs precise vocabulary, because customer IT admins will use these exact terms and expect the engineering team to understand them without translation. This guide covers the English used when discussing WorkOS integrations with a team.

Key Vocabulary

SSO (Single Sign-On) connection — a configured integration between your application and a customer’s identity provider (like Okta or Azure AD), letting their employees log in using their existing corporate credentials. “The customer’s SSO connection is misconfigured on their end — their identity provider is sending the assertion to the wrong callback URL, not something we can fix from our side.”

SAML assertion — the signed XML document an identity provider sends after a successful login, containing the authenticated user’s identity and attributes, which the application must validate before establishing a session. “The login is failing because the SAML assertion’s signature doesn’t validate — that usually means the identity provider’s certificate was rotated and we have a stale one configured.”

SCIM provisioning — an automated protocol for creating, updating, and deactivating user accounts based on changes in a customer’s identity provider, so access is kept in sync without manual admin work. “When an employee leaves the customer’s company, SCIM provisioning should deactivate their account here automatically — if it’s not happening, check whether the SCIM endpoint is actually receiving deprovisioning events.”

Directory sync — the ongoing synchronization of a customer’s user and group directory (departments, roles, memberships) into your application, typically the data source SCIM provisioning is built on. “We’re granting access based on group membership, so directory sync needs to include group data, not just individual user records.”

Identity provider (IdP) vs. service provider (SP) — in an SSO flow, the IdP is the customer’s authentication system (Okta, Azure AD, Google Workspace); the service provider is your application, which trusts assertions issued by the IdP. “From our side as the service provider, we just need to validate the assertion’s signature and audience — the actual login challenge happens entirely on the IdP’s side.”

Connection domain — the email domain(s) associated with an SSO connection, used to route a user attempting to log in to the correct identity provider automatically. “The user is being routed to the wrong SSO connection because their email domain was added to two different connections by mistake — connection domains need to be unique per customer.”

Common Phrases

• “Is this an SSO connection misconfiguration, or an issue on our side as the service provider?”
• “Is the SAML assertion failing to validate, or is it not reaching us at all?”
• “Is SCIM provisioning actually deprovisioning users, or just creating new ones?”
• “Does directory sync include group memberships, or only individual users?”
• “Is this connection domain conflicting with another customer’s SSO setup?”

Example Sentences

Reviewing a pull request: “This webhook handler only processes SCIM ‘create’ events — let’s make sure we’re also handling ‘deactivate’ events, otherwise offboarded employees will keep their access indefinitely.”

Explaining a design decision: “We built access control on top of directory sync group data instead of individual user attributes, so a customer’s own org structure changes automatically flow through to our permissions.”

Describing a bug: “Enterprise users couldn’t log in after their IT team rotated their identity provider’s signing certificate — we were still validating against the old one.”

Professional Tips

• Say “SSO connection” and “SCIM provisioning” as the precise, customer-facing terms — enterprise IT admins use this exact vocabulary, and matching it builds credibility in support conversations.
• When debugging login failures, ask “is this an assertion validation problem or a routing problem?” — these point to different parts of the SSO flow.
• Use “identity provider” and “service provider” correctly — your application is the service provider trusting the customer’s identity provider, not the other way around.
• Distinguish “directory sync” (the underlying data feed) from “SCIM provisioning” (the automated account lifecycle actions built on that data) when explaining an offboarding gap.

Practice Exercise

1. Explain in two sentences the difference between an identity provider and a service provider in an SSO flow.
2. Write a one-sentence explanation of what SCIM provisioning is for, aimed at a non-technical stakeholder.
3. Describe, in your own words, why a stale identity provider certificate would cause SAML assertion validation to fail.