The Developer's Guide to Domain Verification
Learn what domain verification is, how it works, its challenges, best practices, and how you can use WorkOS to verify domains.
Domain verification is key to building security and trust between service providers and organizations.
It’s essential for various use cases, like proving ownership for organization-level features, enabling custom domains for hosted services, and letting service providers send emails on behalf of their clients.
In this article, you'll learn:
- What domain verification is and why it matters.
- How the verification process works, with step-by-step guidance.
- Best practices to ensure smooth verification.
- Common challenges and how to overcome them.
- How WorkOS can streamline the domain verification process.
Let’s start by breaking down what domain verification is and how it functions.
What is domain verification?
Domain verification is the process of proving ownership of a domain name. It involves confirming that you have control over a specific domain and it’s usually required when you want to integrate with external services like email providers, social media platforms, or identity verification systems.
Its primary purpose is to ensure that only the legitimate owner can make changes or connect the domain with certain services.
Domain verification helps protect your website from unauthorized access and spam. Plus, it gives your visitors confidence that they are interacting with a genuine website and not a fake one.
How does domain verification work?
There are a few different methods for verifying domain ownership:
- DNS records: Add a TXT or CNAME record to your DNS settings as provided by the service to prove domain control.
- File upload verification: Download a unique verification file provided by the service and upload it to your domain’s root directory. When the service finds this file on your domain, it confirms your ownership.
- Meta tag verification: Add a unique
metatag to the<head>section of your website's homepage. The service will check for thismetatag when verifying your domain.
Why is domain verification important for developers?
Domain verification is important to developers for a few reasons:
- Ensure data protection: Developers often build apps that handle sensitive user data, such as personal information or payment details. Domain verification ensures that only the verified owner can modify DNS records or access backend services.
- Prevent phishing and spoofing: Phishing attacks often involve creating fake websites to trick users. Domain verification helps prevent attackers from registering similar domains, reducing the risk of phishing scams.
- Secure access to APIs and third-party services: Many third-party APIs, such as those for payment gateways (e.g., Stripe, PayPal) or social login providers (e.g., Google, Facebook), require domain verification before they allow API calls. This step ensures that API keys, tokens, and other credentials are only issued to the verified domain owner.
- Safely link identities: Domain verification enables the automatic association of user profiles with a verified domain. Any user with an email address from that domain can be considered authenticated without additional checks. This makes life easier for developers. There is no need to verify every user’s email one by one, as they can safely link identities. Though other measures like MFA might still be necessary.
Steps to verify a domain
The steps to follow differ according to the method you choose to verify domain ownership.
Add DNS TXT records
- Log in to your domain registrar and navigate to the DNS management section.
- Add a new TXT record using the value provided by the service you’re verifying with. This value typically looks like a unique string of characters.
- Save the record and allow some time for the changes to propagate, which can take up to 48 hours. Once complete, the service can validate that the TXT record exists, confirming your ownership.
Upload verification files
- Download the verification file provided by the service.
- Use an FTP client or a file manager to upload the file to your domain’s root directory (the main folder where your website is hosted).
- Ensure that the file is accessible by visiting the provided URL (e.g.,
https://yourdomain.com/verification-file.html). This allows the service to verify your ownership by checking for the presence of the file.
Use the service provider’s verification method
Some services offer custom methods for domain verification, such as adding a meta tag or using API-based verification. Follow the instructions provided by the service, such as adding a specific meta tag to your website's section or providing a unique token through an API request.
Best practices for domain verification
- Double-check DNS settings: Before you begin the domain verification process, ensure your DNS records are properly configured. This includes placing them in a dedicated subdomain instead of directly at the domain root (e.g.,
foo-corp.com). This approach helps to avoid cluttering TXT records, which can complicate verification and cause potential issues with DNS response sizes. - Use underscore prefix labels: For DNS validation records, use labels prefixed with an underscore (e.g.,
_verification). This practice offers several advantages:- Helps with namespace separation: Prefixed labels help separate validation records from regular domain services, reducing confusion and potential conflicts.
- Enhanced security: The prefix makes it harder for attackers to identify and manipulate these validation records, although it's not a foolproof security measure by itself.
- Simplifies automation: Standardized prefixes make it easier for automated systems, like certificate authorities, to recognize and validate records.
- Generate secure random tokens: Use 128 bits of entropy to generate tokens with strong randomness. This will make them difficult to guess or brute force. For URL-based verification, apply base64url encoding to keep the tokens URL-safe. However, check with your DNS provider, as not all systems support or require this encoding.
- Specify expiration metadata: Where supported, include expiration metadata directly within DNS TXT records to ensure outdated records are removed. This will prevent security risks associated with stale validation data.
- Regularly update records for new services: As new integrations or third-party services are added, update DNS records to accommodate verification requirements. This ensures that your domain is continuously validated for the services in use, helping to prevent service disruptions and maintain security.
- Ensure proper access control for domain management: Limit access to domain management settings to authorized personnel only. This helps prevent unauthorized changes to DNS records that could compromise domain verification. Implement role-based access control (RBAC) or multi-factor authentication (MFA) for an additional layer of security when managing domain settings.
Common challenges in domain verification
- DNS propagation delays: One of the most frequent issues during domain verification is the time it takes for DNS changes to propagate across the internet. DNS propagation typically takes up to 48 hours but may take longer in some cases, depending on your DNS TTL settings and how quickly DNS servers update globally. During this period, attempts to verify the domain might fail because the updated records haven't yet reached all DNS servers.
- Incorrect record entries: Another common challenge is incorrect or incomplete DNS record entries. Even a small mistake can prevent verification from failing, such as a typo in the TXT or CNAME value or placing the record in the wrong subdomain.
- Misconfigurations in DNS settings: Misconfigurations, such as setting the wrong TTL values or placing records at the domain root instead of a subdomain, can complicate the verification process. For example, crowded TXT records at the root domain can make it difficult for the service to identify the specific validation record, leading to failed verifications.
Domain verification with WorkOS
Rather than building and maintaining support for domain verification from scratch, a simpler solution is to use WorkOS Domain Verification. This standalone feature enables IT admins to prove domain ownership by creating and verifying DNS TXT records.
Verifying an organization domain enables the following features:
- Users with the verified domain who sign in with the organization’s SSO connection don’t need to verify their email.
- By default, users with the verified domain are managed by the organization’s domain policy, allowing for enhanced control over authentication and membership.
Domains can be verified using the following methods:
- Using the Admin Portal: An out-of-the-box UI that guides an IT admin to add a DNS TXT record to prove domain ownership. Once the DNS TXT record is correctly added, the organization domain is automatically verified. All you have to do is to invite the admin to verify a domain using the WorkOS dashboard.
- Manually via the WorkOS dashboard.
- Programmatically using the domain verification API.
.webp)
Choosing WorkOS for domain verification offers several advantages:
- Saves development time: WorkOS handles the complexities of the DNS protocol, including response parsing, which frees up developers to focus on more impactful work.
- Flexible verification: Developers can select from various delivery methods, such as Slack or email, to provide Admin Portal links to customers. These links guide customers through the verification process that’s specific to their DNS provider.
- Active monitoring: With DNS changes potentially taking up to 48 hours to propagate, WorkOS continuously monitors for updates and automatically triggers a domain verification event to notify your application when verification is complete.
- Broad compatibility: WorkOS Domain Verification supports all major DNS providers.