User-defined domains are a widely used feature in SaaS service platforms. Well-known platforms such as Shopify have provided this service to provide users with a more personalized and flexible experience.
In the conventional operational model, users of SaaS platforms purchase software services offered by the platform to create distinctive user experiences, serving end-users accordingly. As the starting point of service, SaaS platforms typically assign a randomly generated subdomain to each user as the default access point. However, to meet the demand for personalized access addresses, platforms also support users in setting their own domain names as access points, enhancing brand recognition and user accessibility.
This article aims to delve into how to effectively implement user custom domain functionality in practical product development, providing valuable insights and references for developers.
Problem Analysis
You may wonder: Can't users achieve this functionality simply by pointing the domain's DNS CNAME record to the platform's provided random domain? In reality, the issue is more complex, primarily focusing on the following two aspects:
Modern internet services all use the HTTPS protocol to ensure communication security. When end-users attempt to access the site provided by the SaaS platform, using the platform's provided random subdomain as the entry point allows for direct use of a wildcard TLS certificate, ensuring no issues with certificate management. At this point, the handshake between users and the SaaS platform's HTTPS service is trustworthy. However, when using a user custom domain, the SaaS platform must possess a trusted certificate for that domain for the end-user browser to establish a correct connection, requiring the platform to accept user-uploaded certificates or provide hosted certificate management services.
After establishing a secure connection, the SaaS platform also needs to identify which tenant the end-user is attempting to access on the platform. This necessitates the platform to maintain a mapping table of domains and tenant identifiers, extracting specific tenant information from incoming requests, such as the Host request header, and querying the mapping table to find the tenant ID to return the necessary data to the requester.
TLS Certificate Management
Leading Cloud Services
Major cloud service providers such as AWS (Amazon Web Services) and GCP (Google Cloud Platform) offer comprehensive certificate management services and corresponding API interfaces, with Cloudflare even launching a dedicated solution, Cloudflare for SaaS, tailored for SaaS services.
Taking AWS as an example, its AWS Certificate Manager service enables SaaS platforms to easily issue trusted certificates for user-configured custom domains through its API. As a service within the AWS ecosystem, it seamlessly integrates with other core functionalities like Elastic Load Balancer and CloudFront, allowing certificates issued by ACM to be directly used for TLS termination.
With these cloud services, platforms can manage TLS certificates in a one-stop manner, which indeed sounds attractive. In the early stages of SaaS service, using these cloud services can significantly alleviate the burden on developers, allowing them to focus more on implementing business logic. However, in pursuit of a consistent user experience, these cloud services also expose some potential issues.
Taking AWS Certificate Manager as an example, it requires domain ownership verification when issuing certificates. This process demands domain owners to set specific CNAME records in their DNS records pointing to the address of acm-validations.aws. Furthermore, this record needs to be maintained for an extended period for subsequent certificate renewal operations. This means SaaS platforms must expose specific implementation details specific to the cloud platform to users. Additionally, this mechanism does not adhere to any common certificate automation standards like the ACME protocol. Therefore, SaaS platforms may become tightly bound to AWS cloud services. When a SaaS platform has a large number of users, migration (requiring each user to readjust DNS records) becomes almost an impossible task.
Furthermore, trusted certificates issued by ACM services do not support downloading, meaning these certificates can only be used by other services within the AWS ecosystem, making it difficult to easily extend to other cloud providers, thereby limiting multi-cloud flexibility.
Automated Certificate Management
With Let's Encrypt and other Certificate Authorities (CAs) based on the Automatic Certificate Management Environment (ACME, RFC8555) protocol gradually becoming mainstream, automated certificate management is no longer exclusive to cloud services. Nowadays, any developer can easily implement automatic certificate issuance and renewal, greatly enhancing service usability and security.
The ACME specification defines various domain ownership verification mechanisms, including but not limited to DNS TXT, HTTP, TLS ALPN, etc., providing certificate applicants with flexible and diverse options. In the SaaS scenario, the HTTP authentication method is particularly suitable. Users only need to configure DNS CNAME records for their custom domains, pointing them to the platform's allocated random domain or a unified CNAME access point. For example, the platform may require users to resolve example.com to cname.contoso.com, and this CNAME access point points to the HTTP service self-deployed by the platform. This design simplifies the certificate issuance process, making it more concise and efficient.
Once the domain configuration is correct, the platform can invoke the CA's API to create certificate orders. The CA will then access the user's domain via HTTP. As the domain is already pointing to the platform's access point at this time, the platform can easily satisfy the CA's specific random string verification conditions, thus completing domain ownership verification and downloading the certificate.
This mechanism not only simplifies the user's configuration process but also avoids the hassle of frequently modifying DNS records. More importantly, it frees the platform from the constraints of specific cloud service providers, enabling SaaS platforms to provide a more friendly and consistent user experience.
Additionally, using this mechanism does not mean that CDN or load-balancing services cannot be utilized for TLS termination in the cloud. In fact, certificate management services provided by cloud service providers like AWS support developers in importing self-managed certificates via APIs for traffic access. Developers only need to complete certificate issuance in their own programs and then import the certificate into the cloud service provider's certificate management service, thereby achieving seamless integration and efficient utilization of cloud resources.
Multi-Tenant Systems
After successfully handling TLS certificates, the next challenge is managing multi-tenancy logic on SaaS platforms. Given that SaaS platforms do not solely serve the specific needs of a small number of users but strive to provide a unified set of features to a wide range of users, their system architectures typically adopt multi-tenant designs. In this design, the platform identifies different tenants through unique tenant IDs and provides corresponding services to their respective end-users.
Implementing tenant identification mechanisms is relatively straightforward. Since domain ownership verification and certificate management are required, users must configure custom domains in the SaaS platform console and follow system instructions to set up DNS resolution. Once the system completes the certificate configuration, records of custom domains will be stored in the system and associated with the current tenant. Therefore, whenever the system receives a request, it only needs to extract the Host field from the HTTP request header to determine the access domain used by the client's browser. Subsequently, by querying the tenant record corresponding to this domain, the system can quickly identify the tenant identifier. Once the tenant identifier is obtained, the system can precisely query and access the data of the corresponding tenant.
Conclusion
Custom domains are a core feature on SaaS platforms aimed at providing users with a more personalized and flexible access experience. In the process of implementing custom domain functionality, two key issues must be addressed: TLS certificate management and multi-tenant management.
By addressing these two problems, we can ensure communication security and personalized service in tenant identification, significantly enhancing the service quality and user experience of SaaS platforms. This will help strengthen user trust and satisfaction with the platform, promoting its sustainable development.