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:UpdateSsoConnectionto add or remove a domain, andiam:VerifySsoDomainto 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
- Open IAM, then choose Single sign-on.
- 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.
- At your DNS provider, create a TXT record with that name (
_ews-verification.example.com) and that value (ews-verification=<token>). - Choose Check. The domain shows Verified with the date.
dcloud iam sso-connections add-domain connection-id --domain example.com
dcloud iam sso-connections verify-domain connection-id domain-idThe first command prints the TXT record to create; run the second once it is published.
POST /iam/api/sso-connections/connection-id/domains
{ "domain": "example.com" }The response carries record (type, name, value). Once the record is published:
POST /iam/api/sso-connections/connection-id/domains/domain-id/verifyIt answers verified and the TXT values it found.
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.comfor a value that is not a domain name. - 502
Could not look up _ews-verification.example.com. Try again in a minute.