Directory sync and verified domains
Set up single sign-on, add and remove members from your identity provider, give roles from directory groups, verify your email domains, approve new members and require SSO.
Single sign-on, directory sync and verified domains are part of the Enterprise plan. Organization admins set them up in Admin Console > Identity.
Set up single sign-on
In Admin Console > Identity, select Configure SSO. The WorkOS Admin Portal opens in a new tab, where your IT team connects your identity provider (Okta, Microsoft Entra ID, Google Workspace or any SAML or OIDC provider). The link works for 5 minutes; open a new one from the Identity page if it expires.
Once the connection is active, people on your verified domains sign in through your identity provider, and you can require SSO.
Connect your directory
Select Set up directory. The WorkOS Admin Portal opens in a new tab and walks your IT team through connecting Okta, Microsoft Entra ID, Google Workspace or any SCIM directory. The link works for 5 minutes; open a new one from the Identity page if it expires.
Once the directory is connected:
- People added to the directory join your organization. People whose email is on one of your verified domains join right away; anyone else gets an invitation email first.
- People removed or deactivated in the directory are suspended in Prodgator and signed out.
- People added back to the directory are reactivated, unless an admin suspended them in Prodgator.
Signed out of every organization
When your directory removes someone, WorkOS signs them out everywhere, including other Prodgator organizations they belong to. They can sign in again to keep using those organizations.
Give roles from directory groups
Turn on Use directory groups for roles, then map groups to roles. Custom roles work too. Someone in several mapped groups gets every mapped role (the highest one decides what they can do, and custom role permissions add up). Someone in no mapped group gets the default role. The default role cannot be an admin role: map a group to Admin to make admins.
Changes in the directory usually show up within a minute. Prodgator also checks the whole directory every night, and Sync now checks it right away.
Prodgator never removes the last admin of an organization. If a directory change would do that, the admin keeps their role and the Identity page and audit log say so.
Changing a role by hand
You can still change a directory member's role in Users. The member then shows Manual role, and the directory stops changing their roles until you choose Use directory role. Removal from the directory still suspends them.
Verify your email domains
Select Verify a domain and follow the steps in the Admin Portal to add a DNS TXT record. The domain shows as Verified once the record is found.
With a verified domain you can:
- Let people with a verified email domain join. Colleagues who sign in with an email on that domain join your organization with the role you choose.
- Require SSO for a domain. Everyone with an email on that domain must sign in through your identity provider. If they signed in another way, Prodgator asks them to continue with SSO before showing any of your organization's data.
Waiting for approval
When Let people with a verified email domain join is off, people who join through the domain wait for an admin. They see a "Waiting for an admin to approve you" screen and are not counted against your plan. Admins get a notification and find them under Identity > Waiting for approval, where they can approve them with a role or remove them.
Require SSO for everyone
Require SSO for everyone also covers guests whose email is on another domain. It needs an active SSO connection and a break-glass admin: one admin who can always sign in with a password, so someone can get in if your identity provider is down. The Identity page names the break-glass admin, each of their password sign-ins is recorded in the audit log, and they cannot lose the admin role or be suspended while they are named.
If your SSO connection stops working, or a domain is no longer verified, Prodgator turns the matching requirement off and records it in the audit log, so nobody is locked out.
If you leave the Enterprise plan
Nothing is deleted. Prodgator:
- turns off directory roles, auto-join and SSO requirements, and keeps a copy of your settings;
- keeps everyone's current role as a manual role;
- asks an admin to approve anyone new your directory or domain adds;
- leaves your WorkOS directory and SSO connection in place, but stops reading them.
If your new plan does not include SSO, signing in with SSO no longer opens your organization. Admins get an email to set a password, and in Users they can email the same password setup link to everyone or to one member.
If you come back to Enterprise, Prodgator restores your settings, and members whose role nobody changed in the meantime follow the directory again. SSO requirements come back only while an SSO connection is active.
Signing in
When someone enters an email on a verified domain, sign-in sends them to your identity provider. People who belong to several organizations pick one after signing in, and Prodgator opens the one they used last. See Organizations.
Audit log
Directory and domain changes appear in the audit log: settings changes, roles set by the directory, suspensions and reactivations, people who joined, waited for approval, were approved or removed, break-glass sign-ins and changes, plan changes, password setup emails, and SSO requirements that were turned off.