Verified domains
Prove that your organization owns an email domain, and what a verified domain unlocks.
A verified domain is an email domain, such as example.com, that you have proved your organization controls. You prove it by adding a DNS record.
Why verify a domain
- Single sign-on. An identity provider can only serve domains you have verified. See Single sign-on and SCIM.
- Invitation policy. Once you have a verified domain, invitations to other domains need an explicit External user confirmation by default. See Invitation policy.
- SCIM provisioning. Your identity provider can only create users whose email domain is verified and connected to that provider.
Only admins can add, verify and remove domains.
Verify a domain
-
Add the domain. Call Register a domain with the domain name, for example
example.com. The response contains the domain'sidand averification_token. -
Add a TXT record at your DNS provider:
Setting Value Type TXTName _vigilfield-verification.example.com(many DNS providers want only_vigilfield-verification)Value vf-domain-verification=followed by yourverification_token -
Check the record. Call Verify a domain with the domain's
id. Vigilfield looks up the record straight away.
The result of step 3:
| Response | Meaning |
|---|---|
200 | The record matched. The domain is verified. |
403 | The record is missing or its value is wrong. The response does not say which. |
503 | DNS lookup failed on Vigilfield's side. Try again. |
DNS changes can take a while to spread. If you get a 403 right after adding the record, wait a few minutes and try again.
Verified domains appear under Administration → Verified Domains. From a domain's menu you can use View DNS Records to see the record again, Verify Now to check it again, and Remove Domain.
The Verified Domains page lists only domains that have been verified at least once. A domain you add with New Domain does not appear there until it is verified, and the page does not show its token. Use the API steps above to verify a new domain.
Keep the record in place
Vigilfield checks every verified domain again once a day.
- If a check fails, the domain becomes degraded. It keeps working.
- After 7 failed checks in a row, the domain is revoked.
- A successful Verify Now (or API verification) brings a degraded or revoked domain back to verified.
While a domain is not fully verified, users from it who sign in with single sign-on for the first time cannot be created. While it is revoked, your identity provider cannot create, change or deactivate its users over SCIM.
Leave the TXT record in DNS for as long as you use the domain.
Remove a domain
Select Remove Domain and confirm. After that:
- New single sign-on users from that domain cannot be created on their first sign-in.
- The domain no longer counts as verified for the invitation policy.
Existing users keep their accounts.