Understanding domain verification and domain-captured users.
Domain capture is a set of controls the IT admin of an organization can apply to everything related to its organizational resources on WorkOS. This currently enables provisioning of new users into an organization, but will soon support organization-level control of authentication and user membership policies.
Everything starts by verifying a domain. Domain verification requires an IT admin to perform tasks that prove access to a domain’s configuration that only owners of the domain can have. This might include adding a TXT DNS record, verifying access to an administrator email inbox, or modifying a webpage on the domain’s website.
WorkOS provides a set of APIs and Admin Portal flows for the whole verification process. The result of a domain verification is that a domain is marked as verified for the specific organization that initiated the verification, and the organization becomes domain-verified.
Proof of ownership of the domain is a shortcut to proving that the IT admin has access to do everything else on the domain, including creation of email inboxes, accessing password-reset emails, and deletion of email accounts. When an organization has verified a domain, that organization has proven they have access to control every resource on that domain.
Verified domains may also be added via the WorkOS Dashboard
This is a useful shortcut if the IT admin has already proven ownership of the domain in another context and you do not want to enforce explicit domain verification.
Only one organization can successfully verify a given domain. The alternative would create ambiguity as to which organization has ultimate control over resources on that domain.
If you find that a customer is trying to verify a domain that has already been verified, you should intermediate between the two organizations and identify which should assume ultimate control over the domain.
Once a domain is verified, all existing and future users with email addresses of that domain are considered domain-captured users. The organization that verified that domain now controls all of those users and can automatically provision users signing in with that organizations email domain.
Domain-captured users will automatically be considered verified and will not need to go through the email verification process.
The organization can also enforce specific authentication methods on its domain-captured users.