Email domain verification
Verify your SSO email domain with a DNS TXT record to activate your SSO connection.
This guide explains how to verify your SSO email domains.
What is domain verification
When you create an SSO connection, Cast AI verifies that the email domain belongs to you.
You prove ownership by publishing a DNS TXT record.
Cast AI requires verification for every email domain that the connection uses. This includes the main domain and each additional domain.
A domain becomes active for SSO only after Cast AI verifies it.
Follow this guide when you create an SSO connection or add an email domain to one.
Prerequisites
To verify your domains, you need the following:
- Access to your domain DNS settings
- The verification secret for each domain
NoteThe verification secret appears in the console only while the connection is pending.
Add the verification TXT records
Create the SSO connection in the Cast AI console as described in Single Sign-On (SSO).
Then, for each email domain in the connection:
- Copy the verification secret for the domain.
- Publish a TXT record for the domain.
Use these record values:
| Field | Value |
|---|---|
| Host | _castai-verification.<your-domain> |
| Type | TXT |
| Value | castai-verification=<verification-secret> |
Here is an example. The main domain is your-company.com. The additional domain is your-company.co.uk. Each domain has its own verification secret. The console shows a different secret for each domain.
| Domain | Host | Value |
|---|---|---|
your-company.com | _castai-verification.your-company.com | castai-verification=<secret-for-your-company.com> |
your-company.co.uk | _castai-verification.your-company.co.uk | castai-verification=<secret-for-your-company.co.uk> |
WarningCopy the value exactly. It must match the secret that the console shows for that domain. Check the letters, the case, and the spacing.
Create one record per domain. The record is not a wildcard.
Verify the connection
Cast AI checks your domain automatically.
The first check starts about 2 minutes after Cast AI creates the connection.
If a check does not find the record, Cast AI retries. The delay grows after each retry, up to about 1 hour. DNS changes may also take time to propagate.
When Cast AI finds the matching record, the domain becomes verified. The connection becomes active for login.
Regenerate the verification secret
You regenerate the verification secret when you no longer have the old secret.
To regenerate the secret:
- In the console, open the SSO connection.
- Select Regenerate secret.
Cast AI creates a new verification secret. The domain becomes pending again. Cast AI restarts the verification wait.
After you regenerate the secret, publish a new TXT record with the new value. The old record does not match the new secret.
Connection and domain statuses
The console shows a status for each domain.
| Status | Meaning |
|---|---|
pending | Cast AI waits for the verification record. |
verified | You proved ownership. The domain is active for the connection. |
error | The last check failed. Cast AI retries automatically. |
expired | The domain stayed pending for 14 days without verification. |
denied | Another organization verified the domain first. The connection cannot use it. |
To restart an expired domain, update or recreate the SSO connection. Cast AI starts a new verification period for the domain.
A denied domain belongs to another organization. Your connection cannot use it. Use a domain that your organization can verify. If you believe the domain was claimed in error, contact Cast AI support.
Login while a domain is pending
Until the domain is verified, SSO does not route logins for it.
A user on that domain logs in with the normal password login.
Troubleshooting
Your domain is not verified after about 1 hour. Check these items in order:
- Check the host. It must be
_castai-verification.<your-domain>exactly. Correct any typo. - Check the value. It must be
castai-verification=<verification-secret>exactly. Correct the case and the spacing. - If you regenerated the secret, confirm the published record uses the new value.
- Check DNS propagation. Wait for the change to take effect.
To inspect the record at a terminal, run this command:
dig +short TXT _castai-verification.<your-domain>The output shows the record value in quotes:
"castai-verification=<verification-secret>"Next steps
Updated 9 hours ago
