Security and API
Domain verification
Single sign-on only applies to email domains your organisation has verified. This page walks an organisation admin through verifying a domain with a DNS TXT record and then using it for SSO. It takes about five minutes, plus however long your DNS provider takes to publish a record.
Before you start
You need:
- The Domains permission in your Solidafy organisation. Organisation owners and admins have it by default.
- Access to the DNS settings of the domain your users sign in with, or someone who can add a record for you.
Step 1: Open the Domains page
In the portal sidebar, select Manage organization, then Domains.
You can also do everything below from Manage organization > SSO, where the same list appears under Email domains. Removing a domain is only possible on the Domains page.
Step 2: Add your domain
Under Verified domains, type the domain your users' email addresses end in, such as example.com, and select Add domain.
The domain appears in the list as Pending verification.
- Add each email domain separately. Verifying
example.comdoes not covereu.example.com, so add a subdomain too if people sign in with addresses there. - If you registered an SSO provider already, the Email Domain you entered there is in the list for you. Skip to step 3.
Step 3: Copy the TXT record
Under the domain, the portal shows two values, each with a copy button:
| Shown as | Looks like |
|---|---|
| TXT record name | _solidafy-verify.example.com |
| TXT record value | solidafy-domain-verification= followed by a long random token |
Copy both. The value is unique to this domain in your organisation.
Step 4: Create the record at your DNS provider
Sign in to wherever your domain's DNS is hosted (for example Cloudflare, Route 53, Google Cloud DNS or your registrar) and add a record to the zone for the domain:
| Field | What to enter |
|---|---|
| Type | TXT |
| Name / Host | _solidafy-verify. Most providers add the domain themselves; if yours asks for the full name, enter _solidafy-verify.example.com |
| Value / Content | The TXT record value you copied, exactly as shown |
| TTL | Your provider's default |
In zone file form, the record looks like this:
_solidafy-verify.example.com. 3600 IN TXT "solidafy-domain-verification=Q3Jk...your-token...8xYw"
Save the record. Other TXT records at the same name do no harm; only the exact value counts.
Step 5: Verify the domain
Back on the Domains page, select Verify now next to the domain.
Solidafy asks your domain's own nameservers for the record rather than a caching resolver, so there is nothing to wait out on our side: as soon as your DNS provider is serving the record, the check sees it.
- If the record is found, the domain shows Verified, with the date it was verified.
- If not, the reason appears under the domain. Check the record, then select Verify now again. See Troubleshooting for each message.
Newly added domains are not checked in the background, so select Verify now once the record is published. You can check the same domain again after about 10 seconds.
Leave the record in place after verifying. Solidafy re-checks it every day.
Step 6: Use the domain for SSO
On the Domains page, select Use for SSO next to the verified domain, or open Manage organization > SSO.
- No SSO provider yet: fill in Configure SSO Provider as described in Single sign-on, with your verified domain as the Email Domain, and select Register SSO Provider. Because the domain is already verified, SSO applies to it straight away.
- SSO provider already registered: nothing else to do. The SSO Provider section lists the domain under Domains, and its status changes from Inactive to Active.
To require SSO for everyone at your verified domains, turn on Enforce SSO under Enforcement Settings and select Save Settings. Password, Google and GitHub sign-in are then refused for those addresses, so the only way in is through your identity provider.
Sign out and sign in with an address at the domain to confirm you are sent to your identity provider.
Keeping a domain verified
Verified domains are re-checked once a day. If the record goes missing, nothing changes straight away; after 7 failed daily checks in a row, the domain shows Lapsed.
When a domain lapses, or you remove it from the Domains page, SSO stops applying to it: people at that domain are no longer sent to your identity provider, Enforce SSO stops applying so password, Google and GitHub sign-in work for them again, and SSO can't create new accounts there. If no verified domain is left, the SSO provider shows Inactive and nobody can sign in through it.
A lapsed domain is not re-checked automatically. Put the record back and select Verify now; SSO applies again as soon as the check passes.
Warning: When you move DNS providers or clean up records, carry every
_solidafy-verifyrecord across. If you remove a domain and add it again, it gets a new value, and the record must be updated.
Domains with a verification deadline
A domain that shows Verification required by a date works unverified until that date, and a banner on the page gives the earliest deadline. Follow steps 3 to 5 for each before then. Solidafy also checks these domains daily and marks them verified as soon as the record appears. A domain still unverified at its deadline lapses within the hour.
When more than one organisation has configured the same domain, none of them gets a deadline: the first organisation to verify it holds it.
Why verification is required
SSO decides how someone signs in from the domain of their email address. Without proof of ownership, another organisation could add your domain, point it at an identity provider it controls, and take over sign-in for your people. Verification makes sure only an organisation that controls a domain's DNS can use SSO for it, and once one organisation has verified a domain, no other can.
Troubleshooting
"No TXT record found at _solidafy-verify.example.com". The record isn't at that exact name. Most often the provider added the domain twice, producing _solidafy-verify.example.com.example.com; enter just _solidafy-verify as the name. To see what your nameservers publish:
dig +short NS example.com
dig +short TXT _solidafy-verify.example.com @ns1.your-dns-provider.example
Use one of the nameservers the first command prints in the second.
"...has TXT records, but none matches this domain's verification value". The name is right but the value isn't. Copy it again with the copy button, including the solidafy-domain-verification= prefix.
A CNAME at _solidafy-verify. A TXT record can't sit next to a CNAME at the same name, and Solidafy doesn't follow a CNAME into another zone. Replace the CNAME with the TXT record.
The record was only just added. Some DNS providers take a few minutes to publish a change to all their nameservers; wait a moment and select Verify now again. If you have just moved the domain to new nameservers, add the record at the new provider; the move itself can take up to 48 hours to be seen everywhere.
Split DNS. Solidafy checks your public DNS. Publish the record in the public zone, not only on internal nameservers.
"DNS lookup timed out". Your nameservers didn't answer within 5 seconds. Try again; if it persists, check they are online and publicly reachable over IPv4.
"Another organization has already verified this domain". A different Solidafy organisation holds it. If your company owns the domain, contact support.
"This domain was checked moments ago". Wait a few seconds and try again.
The domain can't be added. You can't add an IP address or a public suffix such as co.uk or github.io, and an organisation can have at most 50 domains.