# Verify a domain

Prove with a DNS TXT record that your organization controls an email domain, so its people can sign in through a single sign-on connection.

Only addresses on a verified domain sign in through a connection, and a connection can be turned on
only once it has one. Replace _example.com_ with your domain and _connection-id_ with the
connection's ID.

## Prerequisites

- Permission for `iam:UpdateSsoConnection` to add or remove a domain, and `iam:VerifySsoDomain` to
  check it. To open the **Single sign-on** page in the console, `iam:ListSsoConnections`.
- Access to the DNS of the domain.

## Add and verify the domain

**Console**
1. Open **IAM**, then choose **Single sign-on**.
2. On the connection's card, under **Domains**, enter example.com and choose
   **Add domain**. The domain is listed as **Not verified**, with a **TXT name** and a
   **TXT value**.
3. At your DNS provider, create a TXT record with that name (`_ews-verification.example.com`) and
   that value (`ews-verification=<token>`).
4. Choose **Check**. The domain shows **Verified** with the date.

**CLI**
```sh
dcloud iam sso-connections add-domain connection-id --domain example.com
dcloud iam sso-connections verify-domain connection-id domain-id
```

The first command prints the TXT record to create; run the second once it is published.

**API**
```http
POST /iam/api/sso-connections/connection-id/domains
{ "domain": "example.com" }
```

The response carries `record` (`type`, `name`, `value`). Once the record is published:

```http
POST /iam/api/sso-connections/connection-id/domains/domain-id/verify
```

It answers `verified` and the TXT values it `found`.

**Terraform**
```hcl
resource "dcloud_iam_sso_domain" "example" {
  connection_id = dcloud_iam_sso_connection.okta.id
  domain        = "example.com"
}
```

Publish `verification_record_name` with `verification_record_value` (for example with
`dcloud_dns_record`), then verify the domain in the console or with the CLI. Terraform does not
verify it.

## Result

The record is looked up through public resolvers, so a new record can take a few minutes to be
found. Until it matches, **Check** answers `No TXT record at … yet. DNS changes can take a few
minutes.` or `The TXT record at … does not match yet.`

Leave the record in place. Removing a domain from the connection stops sign-ins for its addresses,
and a connection left without a verified domain is switched off and no longer enforced.

## If it is refused

- 409 `example.com is already verified for another connection`: a domain is verified for one
  connection at most.
- 409 `example.com is already on this connection`
- 400 `domain: Enter a domain such as example.com` for a value that is not a domain name.
- 502 `Could not look up _ews-verification.example.com. Try again in a minute.`

## Related

- [Single sign-on](single-sign-on.md) · [Enforce single sign-on](enforce-single-sign-on.md)
- `iam.sso-connections.add-domain` · `dcloud iam sso-connections verify-domain` · `dcloud_iam_sso_domain`
