SSO, SCIM & Domain Verification
An organization admin on the Enterprise plan configures identity from the dashboard. People & Access → Organization shows three cards. Each button opens the WorkOS Admin Portal in a new tab and, when you finish, returns you to that same organization page.
Do the three setups in this order. Domain verification is the step WorkOS requires before SSO can be turned on. Connect SSO next, then Directory Sync.
| Card | Button | What it does |
|---|---|---|
| Domain verification | Verify domain | Prove you own an email domain with a DNS TXT record. |
| Single Sign-On | Configure SSO | Connect SAML or OIDC to your identity provider. |
| Directory Sync (SCIM) | Configure SCIM | Provision and deprovision members from that directory. |
The identity providers the portal offers include Okta, Microsoft Entra ID, and Google Workspace. Pick yours in the portal; it shows the provider-specific steps.
Prerequisites
You open this setup as an organization admin (owner or admin) from People & Access → Organization. On that page, Verify domain, Configure SSO, and Configure SCIM stay disabled until the organization is on the Enterprise plan and linked to WorkOS. One plan check covers all three.
Enterprise plan. When the plan does not include this setup, each card says Available on the Enterprise plan. A portal request from that organization is rejected with Self-serve SSO requires the Enterprise plan.
Linked to WorkOS. When the organization has no WorkOS link yet, each card says Available once this organization is linked to WorkOS. A portal request for an unlinked organization is rejected with Organization is not linked to WorkOS.
When the buttons are enabled, click one. The Admin Portal opens in a new browser tab.
Domain verification
Claim the email domain people will use to sign up, before you connect SSO.
- Open People & Access → Organization.
- On the Domain verification card, click Verify domain.
- In the Admin Portal, add the DNS TXT record it gives you at the DNS host for that domain. Leave the record in place. The portal confirms the domain once DNS resolves.
How to tell it worked. Go back to the organization page. Focusing that browser tab refreshes domain status. The card lists the domain with a green Verified tag.
Until then, the card says No email domain is claimed for this organization, or it lists the domain as Not verified. Domain status is unavailable. Reload the page to try again. means the lookup failed for this request; reload the page.
Once the domain is claimed, a later signup from that domain joins this organization as a member.
Single Sign-On
Connect the identity provider so members of this organization sign in through it.
- On the same organization page, open the Single Sign-On card.
- Click Configure SSO.
- In the Admin Portal, create a SAML or OIDC connection and finish the steps it shows for your provider (metadata, ACS or redirect URL, and the matching settings in the identity provider).
How to tell it worked. A member signs in and is sent to that identity provider, then lands in this organization.
Directory Sync (SCIM)
Keep membership in step with the directory. A provision creates the user and links them to the organization's default team. A deprovision archives the user, removes their membership, and revokes their active virtual API keys.
- On the same organization page, open the Directory Sync (SCIM) card.
- Click Configure SCIM.
- In the Admin Portal, turn on directory sync and finish the SCIM steps your identity provider shows, using the endpoint and token the portal provides.
How to tell it worked.
- Provision someone in the directory. They show up on People & Access → Members, and on People & Access → Teams they are on the team named default.
- Deprovision that person in the directory. They are archived and removed from the organization. Virtual API keys that belonged to them stop authorizing gateway requests.
Directory sync leaves a protected owner in place. Role assignment still resolves inside Corveil; see Roles & Permissions.