Administration
Domain verification
Prove that your organisation controls an e-mail domain, so that addresses on it can sign in through single sign-on and be provisioned through SCIM.
Before anyone can sign in through single sign-on with an address on a domain, your organisation must prove that it controls that domain. The proof is a DNS TXT record that only the domain's owner can create.
The reason: your identity provider is run by you and can assert any e-mail address. Without the proof, an organisation could list another company's domain and have its own provider vouch for that company's people.
#What you need
- To be an owner of the organisation.
- Single sign-on saved with the domain in Allowed email domains.
- The ability to add a TXT record to the domain's DNS.
#Verify a domain
- Open Settings, Access, Single sign-on and save the domain in Allowed email domains.
- Under Domain verification, find the domain. The console shows a record with a Type, a Name and a Value, each with a copy button.
- Create that record at your DNS provider.
- Back in the console, choose Verify for the domain.
DNS changes can take a while to reach every name server. If the record is not found yet, wait and try again.
#The record
| Part | Value |
|---|---|
| Type | TXT |
| Name | _nullgap-challenge. followed by the domain, for example _nullgap-challenge.acme.example |
| Value | nullgap-domain-verification= followed by a token, exactly as shown |
The token is generated for your organisation and this domain. Another organisation's record proves nothing for yours, and yours proves nothing for theirs. The token is not a secret: it is public in DNS by design.
Some DNS providers append the domain to the name for you. If yours does, enter only _nullgap-challenge.
You can keep other TXT records on the same name. Nullgap looks for one whose value matches exactly.
#Reading the record through the API
The record's name and value are in the single sign-on configuration, one entry per domain. An API key with the admin scope can read it:
curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/sso"
The domains part of the answer:
{
"domains": [
{
"domain": "acme.example",
"status": "pending",
"recordName": "_nullgap-challenge.acme.example",
"recordValue": "nullgap-domain-verification=Zk3v...",
"verifiedAt": null,
"lastCheckedAt": null,
"failingSince": null,
"legacyUntil": null
}
]
}
Starting the check itself (POST /api/orgs/:org/sso/domains/verify with {"domain":"acme.example"}) is an owner action, so it is done from the console and not with an API key. See the single sign-on reference.
#Results of a check
| Message | Meaning | What to do |
|---|---|---|
| "The record was found. This domain is verified." | Done. People on this domain can now sign in | Leave the record in place |
| "The record was not found..." | No TXT record exists at that name | Check the name (see the note about appended domains) and wait for DNS to update |
| "A verification record was found, but its value is different..." | A nullgap-domain-verification= record exists with another token | Copy the value shown for this organisation and this domain again |
| "The DNS look-up did not get an answer..." | The look-up timed out or the name server failed. This never counts against the domain | Try again shortly |
| "This domain is already verified by another workspace..." | Another organisation holds the domain | See one organisation per domain |
404 "That domain is not on the list. Save it first." | The domain is not in Allowed email domains | Save it, then verify |
429 rate_limited | More than ten checks in a minute for your organisation | Wait a minute |
Every check is written to the audit log: sso.domain_verified or sso.domain_check_failed with the reason.
#Domain states
Each domain has a status:
| Status | Console shows | Sign-in with an address on the domain |
|---|---|---|
verified | Verified | Works. New people join with the role for new members |
pending | Verification needed | Refused |
legacy | Verification needed | A domain that was allowed before verification existed. Until the date in legacyUntil, people who are already members can still sign in; nobody new can join. After that date it behaves like pending |
SCIM follows the same rule: it can add people only on a verified domain. See SCIM provisioning.
#One organisation per domain
A domain can be verified by one organisation at a time. The first organisation to prove a domain holds it.
If another organisation already holds the domain, your check is refused even when your record is in DNS. The holder's audit log receives sso.domain_claim_attempt, so they know that someone with control of the domain's DNS tried.
The holder gives a domain up by:
- removing it from Allowed email domains;
- removing single sign-on;
- letting the record stay missing for seven days (below).
If your company has two organisations in Nullgap, each needs its own domain, or one of them must do without single sign-on for that domain. If a domain that belongs to you is held by an organisation you do not recognise, contact Nullgap.
#The daily re-check
Nullgap looks every verified domain's record up again once a day. The same check runs when you choose Check again on a domain that is already verified.
| What the look-up finds | What happens |
|---|---|
| The record | Nothing changes. Any earlier failure is cleared |
| No record, or a record with another value | failingSince is set to the time of the first failed look-up. The domain stays verified for now |
| No definite answer (time-out, server failure) | Nothing changes. An unreachable name server never counts against you |
While failingSince is set, the console marks the domain Verified ยท record missing and says since when.
#The seven-day lapse
If the record is still missing seven days after failingSince, the verification ends:
- the domain goes back to
pending; - your organisation's hold on the domain is released, so whoever controls the domain now can verify it;
- the single sign-on sessions of people on that domain are ended;
- the audit log records
sso.domain_verification_lapsedwith "The DNS verification record was missing for seven days".
Restore the record and choose Verify to get the domain back. Putting the record back before the seven days are up clears the failure at the next look-up, and nothing lapses.
#What a lapse does to sign-in
| Who | Effect |
|---|---|
| People on the lapsed domain signing in through SSO | Refused, with error=sso_domain_unverified on the sign-in page, until the domain is verified again |
| Their open SSO sessions | Ended when the verification lapses |
| People on your other verified domains | Not affected |
| Members who sign in another way (passkey, e-mail link) | Not affected, unless single sign-on is required |
| Owners with a second factor | Can still sign in another way even when single sign-on is required. See the owner break-glass path |
| SCIM | Can still deactivate and remove people on the domain. It cannot add or reactivate them until the domain is verified again |
Memberships are not removed by a lapse. Once the domain is verified again, people sign in as before.
#Removing a domain
Removing a domain from Allowed email domains gives up the proof and ends the SSO sessions of people on that domain. Adding it back later creates a new token, so the old TXT record no longer matches: publish the new value and verify again.
#Limits
- The look-up uses ordinary DNS with a five-second limit. DNSSEC is not checked.
- Public suffixes (such as
co.ukor a shared hosting domain), single-label names and IP addresses cannot be listed. - International domain names are stored in their
xn--form.
Nullgap documentation