Set up custom domains
To use the Ory Network on one or more domains that you own, you can set a CNAME record.
This feature is only available on paid plans. If you're using the free plan, you will have to upgrade before being able to add a custom domain.
Adding a custom domain to your project
Locate "Custom Domains" in the Ory Console navigation menu.
When you click it and navigate to the "Custom Domains" page, your list of custom domains will likely be empty at this point. If you're not on a paid plan, you won't be able to add one.
Click "Add one now" to add your first domain. You will be greeted by a creation screen:
When you add a custom domain, it becomes your project's SDK Configuration URL. To check your SDK Configuration URL, go to Ory Console → Access & APIs.
The domain you enter in the first step will be the domain that you'll use for requests to Ory Network. You will have to create a CNAME record with the DNS provider with which the domain is registered, with the value that's provided in this form (you will be able to see this value later as well).
Note that the value in the above screenshot is an example. You will have your own value that you will need to copy.
The Cookie Domain is the domain cookies will be scoped to. This is an important security setting. In all likelihood, you'll want this to be the root domain of whatever you supplied in the first step. See the Cookie configuration document and this Stack Overflow answer.
CORS
Cross-Origin Resource Sharing (CORS) is also enabled by default on the custom domain you add, in this example we have
auth.foobar.ory set as our custom domain which will point to your project. It's important that you add CORS origins to your
custom domain to ensure Single Page Applications (SPAs) support. Ory Network allows up to 50 origins. If you plan on using
server-side rendering or native applications, you can disable CORS. You can read more about
CORS at MDN.
Ory Network doesn't allow setting the CORS origins to be *, null or localhost/127.0.0.1. You can, however, use a wildcard
subdomain such as https://*.foobar.ory. To be on the safe side, Ory recommends setting the CORS origins to be an exact match
instead of a wildcard subdomain. For local development with localhost/127.0.0.1 use Ory Tunnel.
Waiting for propagation
When you've added the domain in Ory Console, we will continuously recheck its status to see if it was configured with your registrar. Note that it can take up to 24 hours for your changes to propagate.
You may also manually recheck on the custom domains page, or check the value to set with your DNS provider by clicking the magnifying icon in the custom domains section:
When the domain is reachable, it will have the "Active status".
The CORS status will show "Inactive" while the domain is pending verification. After the domain is verified, the CORS status will show "Enabled/Disabled".
Once active, the Ory Account Experience is reachable at https://<your-custom-domain>/ui/welcome. Learn how to configure a custom
UI: Bring Your Own UI.
You may also remove your custom domain from the Console, but please note that any requests to it will no longer resolve once you do.
When editing your custom domain entry, you can update the CORS settings independent of the custom domain or cookie domain settings.
Setting up a CNAME record
If your DNS provider/registrar automatically activates a proxy on the CNAME record, it can keep the custom domain in a pending state. Please make sure to deactivate proxying on the CNAME record. We use a tailored Cloudflare configuration on our side, to ensure requests to the custom hostname are fully protected.
In case you are using Cloudflare as your DNS provider, make sure "Zone Hold" is released. It needs to be released temporarily so that we can preconfigure the subdomain in our account.
If you're with any of these registrars, you can use their respective guide on how to add a CNAME record:
If not, don't worry - your registrar likely has a similar guide, or a similar process. Setting up a CNAME record typically requires you to specify 3 values:
- A record type, CNAME in this case
- The Host, which is the subdomain that will be reachable. With most registrars, entering
@as the value signifies that you want to use the root domain. - The value, which is provided by us. Check the value provided in the form (detailed in the first step of this article) to know what this should be for your project.
If your Custom Hostname remains in pending or error state, you can check your configuration using a command line tool like
dig, which outputs how the DNS query is resolved:
❯ dig auth.foobar.com
; <<>> DiG 9.10.6 <<>> auth.foobar.com
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 7283
;; flags: qr rd ra; QUERY: 1, ANSWER: 3, AUTHORITY: 0, ADDITIONAL: 1
;; OPT PSEUDOSECTION:
; EDNS: version: 0, flags:; udp: 512
;; QUESTION SECTION:
;auth.foobar.com. IN A
;; ANSWER SECTION:
auth.foobar.com. 300 IN CNAME <your-project-slug>.projects.oryapis.com.
<your-project-slug>.projects.oryapis.com. 300 IN A 104.18.12.126
<your-project-slug>.projects.oryapis.com. 300 IN A 104.18.13.126
;; Query time: 28 msec
;; SERVER: 8.8.8.8#53(8.8.8.8)
;; WHEN: Tue Oct 31 11:47:22 CET 2023
;; MSG SIZE rcvd: 135
If the ANSWER SECTION lists an IP address instead of the generic Ory network URL <your-project-slug>.projects.oryapis.com, it
indicates you did not deactivate proxying. Check the configuration of your CNAME record in your DNS Provider/registrar and disable
proxying.
Automated emails
The Ory Network sends emails for certain actions a user can take, for example account recovery or address verification. Since most email providers take measures against spam and phishing attacks, for example "fake" link campaigns, it's advised to only link to domains that match the sender of the email.
However, when using a custom domain in the Ory Network without a custom SMTP server, links inside the automated Ory Identities
emails won't match the domain these emails were sent from. For example the address verification link will point to
ory.your-custom-domain.com, but the email was sent from the default Ory Network email sender domain (e.g.
courier-eu.oryapis.com). Some email providers, such as Gmail, might interpret this as a phishing attack and mark the email as
spam, or block it entirely.
To prevent this, configure a custom SMTP server, that matches at least the root domain of your custom domain. For example, if you
configured the custom domain ory.your-custom-domain.com, you should also configure an email server that lives under
your-custom-domain.com.
To learn how to set up a custom SMTP server on the Ory Network, read Send emails using your SMTP server.