The Developer's Guide to Domain Verification

November 15, 2023

Domain verification is an important measure for establishing security and trust between providers and organizations. This blog examines best practices to consider when building in-house as well as a simple alternative that WorkOS provides.

Domain verification is a crucial security measure for SaaS providers, ensuring that services are securely delivered to the legitimate owners of a domain. It’s implemented in a number of use cases like verifying ownership for organization-level functionality, supporting the use of custom domains for hosted features, and enabling service providers to send emails on behalf of their customers.

Several methods exist for validating domains. Domain Name System (DNS) validation requires directly altering TXT records in DNS configuration. Email-based validation requires responding to an email sent to the domain. HTTP-based verification relies on updating content hosted at the domain.

Of these, DNS-based validation is frequently recommended for its resilience to common attack vectors. Email confirmation is susceptible to phishing attacks, while HTTP-based verification can be exploited via vulnerabilities in an organization’s web servers. While DNS-based validation is arguably the most secure, there are a number of practices to follow when taking this approach.

Best Practices

Don’t place TXT records on the root domain

DNS-based verification methods are effective at preventing unauthorized access, but their implementation has some subtleties. One common mistake is placing a DNS TXT record directly on the domain being verified, creating a crowded TXT record at the domain root (e.g. foo-corp.com). Crowded TXT records are problematic because querying for the validation record will return all TXT records in the response, requiring the verifier to process the entire set of responses to identify the specific record of interest. To help mitigate overcrowding issues use specific, unique record names like _verification.foo-corp.com or _service-challenge.foo-corp.com.

Crowded TXT record can also cause fragmentation in DNS responses that occurs when the size of the response exceeds the maximum transmission unit (MTU) size of the network path, typically 512 bytes. When DNS responses are fragmented, it leads to increased vulnerabilities for several reasons:

Increased exposure to interception: Fragmented packets are easier to intercept and manipulate. Attackers can potentially reassemble the fragments incorrectly or inject malicious fragments. This could lead to cache poisoning attacks, where false DNS information is inserted into the cache of the resolving server or client.
Increased complexity of reassembly and Denial of Service (DoS) attacks: The process of reassembling fragmented packets is resource-intensive. Attackers can exploit this by sending a flood of fragmented packets, leading to a DoS condition where legitimate requests cannot be processed due to the excessive load on reassembling these fragments.
Increased Latency and Performance Impact: Fragmentation often results in a higher number of packets being transmitted, which increases network load and latency. This can degrade performance of DNS resolution, and in cases of high network traffic or intentional flooding, it can lead to service disruptions.

Use underscore prefix labels

The naming convention in validation records, particularly the use of application-specific underscore-prefixed labels, is important for several reasons:

Namespace Separation: Since the underscore character (“_”) is not typically used in hostnames for regular services and is reserved for special use in DNS records, there is a clear separation between normal operational hostnames and those used for validation purposes, which helps prevent naming conflicts.
Security: By using a unique label that includes the provider's name, the risk of malicious interference is reduced. It makes it more difficult for an attacker to predict or forge the validation record because they would need to know the specific label format that the provider is using.
Automation: A standardized format that includes an underscore prefix helps automate the validation process. Automated systems, such as those used by certificate authorities in the issuance of SSL/TLS certificates, can easily identify and verify these records because they follow a predictable pattern.
Application-Specific Identification: Including the application or provider-specific identifier in the label ensures that the DNS record can be directly associated with a particular service or validation request. This helps in managing multiple validations and avoids confusion when multiple services may be issuing challenges for the same domain.

Generate secure random tokens

When generating random tokens used in DNS challenges, two there are two primary recommendations:

The first is to use 128 bits of entropy when generating the token. This is the recommended threshold for thwarting guessing or brute-force attacks. The more random and unpredictable the value, the more secure it is against attempts to forge or predict the token in a malicious way.

The second recommendation is to encode the token with base64url, a variant of base64, ensuring the token is a URL-safe string that can be transmitted without issues related to encoding or special characters.

Specify expiration metadata

Clear guidance on when DNS validation record should be removed is crucial for DNS configuration and security.

Providers should use comma-separated key-value pairs in DNS TXT record RDATA. The expiry key indicates a specific expiration timestamp or the value can be to never in case the record should not be removed. For instance, a record formatted as follows informs developers of both the token value and its expiration, enabling automated or manual cleanup post-validation:

_foo-corp-challenge.example.com. IN TXT 'token=1113...1d816z4,expiry=2023-11-14T05:20:30+00:00'

This improves record hygiene and reduces risks associated with outdated records that lead to security issues or validation conflicts. Alternatively, the expiry key can also be omitted for flexibility while maintaining alignment with domain control validation standards.

Alternative Solution: Choosing WorkOS

Rather than building and maintaining support for domain verification from scratch, a simpler solution is to use WorkOS Domain Verification. With quick API integration, developers can offer a self-serve flow that IT Admins can follow to prove domain ownership through DNS TXT records. There are several reasons why this is the preferred route:

Domain Verification relieves developers from dealing with the intricacies of the DNS protocol and parsing responses, thus freeing up engineering time for more impactful work.
Developers can select from various delivery mechanisms to provide Admin Portal links to customers, guiding them through the verification process specific to their DNS provider in just minutes.
Since domain configuration changes can take up to 48 hours to propagate, Domain Verification actively monitors DNS changes and issues a Webhook notification upon successful validation.

Domain Verification supports all domain name system providers with tailored setup instructions for the following providers with more coming soon:

AWS Route 53
GoDaddy
Google Domains
Cloudflare

In the coming months, we will launch additional Domain Verification features to streamline the developer workflow:

More verification methods such as WHOIS-based email, constructed email, email to DNS TXT contact, and manual verification
Tailored setup instructions for more providers
Optional continuous verification, requiring IT admins to complete verification on a regular basis
Audit logs containing DNS response and proof of domain validation

To get started, check out the Domain Verification docs.

In this article

Link

We’re hiring

Our global team is growing and we’re hiring all types of roles.

View open roles

About us

WorkOS builds developer tools for quickly adding enterprise features to applications.

Learn more