Authentication Domains

This document seeks to explain what an authentication domain is, how it is used, and how we implement it internally.

The Basics

When a user wants to sign in to your applicaiton using Authproject, they have to visit a given URL to enter their information. This URL is the beginning of an “authentication domain.” It is a logical grouping of user identities in our database that can be authenticated against.

How does the URL work?

When a user requests auth.yourwebsite.com, for example, it will be “pointed” via a CNAME record to our servers. This means that when the user visits auth.yourwebsite.com, their browser talks to Authproject’s “domain service.” The domain service is the core service that supports user interaction within our platform.

The URL, as mentioned above, sends a user to the domain service.

How does the domain service work?

The domain service looks for the Host header sent by the user’s browser. It then uses that as a partition key to finding all users that are registered with that domain. It means that when you look up email@example.com for the domain auth.yourwebsite.com, it doesn’t find any results for email@example.com under auth.authproject-demo.com as well. This allows a user to have multiple “accounts” in the domain service, while ensuring that each “account” they have is separate from any others stored in the database.

Networking

This simplicity from a user’s perspective comes at a cost to us, in terms of operational overhead. Any new website or application we onboard has to go through a process to register within our platform. The first step is for us to register the domain with our CDN provider, Cloudflare. All new domains have an entry added into Cloudflare, allowing TLS certificates (the S in HTTPS) to be provisioned, and enabling our web firewall for use by the customer.

Then, once the website has been set up on our side, the customer needs to point their domain to our services. They do this by creating the CNAME mentioned above. This directs web traffic aimed at the authentication domain (auth.yourwebsite.com) to go to our servers.

Emails

Once the authentication domain has been provisioned on both ends, we need to be able to send emails from your authentication domain. This is done by creating three more CNAME records, each of them pointing to a DKIM entry hosted by our email provider, AWS SES.

Once these are configured, we can successfully send emails from the authentication domain. But don’t worry - just because we can send emails from noreply@auth.yourwebsite.com doesn’t mean we can impersonate alan@yourwebsite.com. We can only send emails from auth.yourwebsite.com.

Hope this helps!

We hope this helps explain what an authentication domain is in our platform, how it’s used, and how we implemented it.