Nullgap.dev Docs

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

  1. Open Settings, Access, Single sign-on and save the domain in Allowed email domains.
  2. Under Domain verification, find the domain. The console shows a record with a Type, a Name and a Value, each with a copy button.
  3. Create that record at your DNS provider.
  4. 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

PartValue
TypeTXT
Name_nullgap-challenge. followed by the domain, for example _nullgap-challenge.acme.example
Valuenullgap-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

MessageMeaningWhat to do
"The record was found. This domain is verified."Done. People on this domain can now sign inLeave the record in place
"The record was not found..."No TXT record exists at that nameCheck 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 tokenCopy 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 domainTry again shortly
"This domain is already verified by another workspace..."Another organisation holds the domainSee one organisation per domain
404 "That domain is not on the list. Save it first."The domain is not in Allowed email domainsSave it, then verify
429 rate_limitedMore than ten checks in a minute for your organisationWait 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:

StatusConsole showsSign-in with an address on the domain
verifiedVerifiedWorks. New people join with the role for new members
pendingVerification neededRefused
legacyVerification neededA 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 findsWhat happens
The recordNothing changes. Any earlier failure is cleared
No record, or a record with another valuefailingSince 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_lapsed with "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

WhoEffect
People on the lapsed domain signing in through SSORefused, with error=sso_domain_unverified on the sign-in page, until the domain is verified again
Their open SSO sessionsEnded when the verification lapses
People on your other verified domainsNot affected
Members who sign in another way (passkey, e-mail link)Not affected, unless single sign-on is required
Owners with a second factorCan still sign in another way even when single sign-on is required. See the owner break-glass path
SCIMCan 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.uk or a shared hosting domain), single-label names and IP addresses cannot be listed.
  • International domain names are stored in their xn-- form.

Nullgap documentation