# Verify a domain

> Prove your organization owns an email domain with a DNS TXT record, so By Dawn can send its people to your single sign-on.

This page helps you prove to By Dawn that your organization owns an email domain, such as `acme.com`.
At the end the domain shows as **Verified**, and you're ready to set up
[single sign-on](https://docs.bydawn.com/sso/) for the people who use it.

By Dawn needs that proof before it trusts your identity provider about anyone's email. Without it,
any organization could claim `acme.com` and sign people in as Acme's staff. The proof is a DNS
record, because only someone who controls a domain's DNS can add one.

Any plan can verify a domain. Single sign-on itself depends on your organization's plan (see
[Plans and billing](https://docs.bydawn.com/billing/)).

## Before you start

- **You need to be the organization's owner.** Admins can open **Settings › Organization › Domains**
  and read it, but only the owner can add, verify or remove a domain. The page says so: "Only the organization
  owner can add, verify or remove domains." A domain lets your identity provider vouch for every mailbox at it,
  so it gets the same protection as the sign-in policy.
- You need to be able to add a TXT record to the domain's DNS, or know who can. That's often IT or whoever
  manages your website.

## Verify a domain

1. Open **Settings › Organization › Domains**. Under **Add a domain**, type the domain your
   people's emails use, such as `acme.com`, and choose **Add domain**. Type just the domain, without `@` or
   `www`.

2. The domain appears as **Pending**, with the TXT record to publish. Each part has a copy button:

   | By Dawn shows | What it holds |
   | --- | --- |
   | **TXT record name** | `_sawrun-challenge.acme.com` |
   | **Value** | `sawrun-domain-verification=` followed by a long random token, new for every claim |

3. Add the record at your DNS host. Many hosts add the domain to the name for you. If yours does, enter only
   `_sawrun-challenge` as the name, or you'll end up with `_sawrun-challenge.acme.com.acme.com`.

4. Back in By Dawn, choose **Verify**. By Dawn looks the record up, and if the value matches exactly, the domain turns
   **Verified**: "Verified. The record must stay published — SAW re-checks it daily."

If By Dawn can't find the record yet, it says "We couldn't find the record yet. DNS changes can take a while to
spread; check the name and value, then try again." and the domain stays pending. Most DNS changes show up within
a few minutes, but some hosts take an hour or more. You can check what the world sees from a terminal:

```sh
dig TXT _sawrun-challenge.acme.com +short
# or, on Windows:
nslookup -type=TXT _sawrun-challenge.acme.com
```

When the value By Dawn showed you appears in the answer, choose **Verify** again. If By Dawn says it "couldn't reach a
DNS resolver just now", nothing changed, so try again in a minute.

## Add every domain your people use

Add each domain that appears in your people's email addresses, such as `acme.com`, `acme.co.uk` and
`acme-labs.io`. Each is verified on its own, with its own record, and an organization can hold up to 20.
Matching is exact, so verifying `acme.com` doesn't cover `eng.acme.com`: add a subdomain separately if people's
emails use it. Someone whose email domain isn't verified can't sign in through your connection.

By Dawn refuses a domain no single company owns: "That domain can't be claimed. Use a domain your company owns — not
an IP address, a public suffix such as co.uk, or a shared mail provider such as gmail.com."

## One organization per domain

A domain can be verified by only one By Dawn organization at a time, so there's never a question of whose single
sign-on an email belongs to. Any number of organizations can hold a pending claim, each with its own record, and
the first to verify wins. If another organization has already verified a domain you own, By Dawn says "Another
organization has already verified that domain. Ask SAW support if it belongs to you." It never names that
organization. Often it's a second By Dawn organization at your company, whose owner can remove the domain.

## Keep the record in place

Leave the TXT record in your DNS after the domain is verified. By Dawn re-checks it every day, so a domain your
company no longer controls doesn't stay verified forever.

- **One re-check fails.** The domain shows **Verified · re-check failing**, and the record appears again so you can
  check it. Nothing changes for your people yet, because a short DNS outage shouldn't switch off sign-in.
- **The record stays missing for 72 hours.** The domain turns **Lapsed** and gets a new record value. A lapsed
  domain counts as unverified, so its people can't sign in through your connection, and another organization
  could verify it.

To restore a lapsed domain, publish the new value By Dawn shows and choose **Verify**.

> **Moving DNS hosts?** Copy the `_sawrun-challenge` record across with your other records. A domain that lapses during a move stops
> single sign-on for its people until you verify it again.

## Remove a domain

Choose **Remove** next to the domain, then **Remove domain**. For a verified domain, By Dawn warns you first:
"Single sign-on stops recognising people at this domain, and another organization could then verify it." You can
add it again later, but it needs a new TXT record, and you can delete the old one from your DNS.

## FAQ

**Does verifying a domain add anyone to our organization?**

No. A verified domain only decides whose sign-ins your identity provider may vouch for. People join through an
invite, or on their first single sign-on if you allow that (see [First sign-in](https://docs.bydawn.com/sso/#first-sign-in)).

**Why can't an admin verify the domain?**

Because a verified domain lets your identity provider speak for every mailbox at it, which is as much power as
changing how people sign in. Both are the owner's. Admins can still see each domain and its status.

## Where to go next

- [Single sign-on](https://docs.bydawn.com/sso/): the order to set things up, and how to add a connection.
- [SCIM provisioning](https://docs.bydawn.com/scim/): needs a verified domain too.

Source: https://docs.bydawn.com/sso-domains/