How to configure a custom domain in SMARTFENSE – SMARTFENSE

This article explains how to set up a custom domain so that users access the platform through an address that belongs to your organization, instead of the standard domain assigned by SMARTFENSE. It includes the correct order of the DNS records and what to check before activating it.

This feature is available from the Standard plan.

Definitions

Standard domain: the address SMARTFENSE assigns to you by default (for example, instance.takesecurity.com). It is always available, even if you set up your own domain.
Custom domain: a domain owned by your organization that you add to access the platform through your own address.
Primary domain: the domain the platform uses at any given time for access and for the links it sends (emails, campaigns). There can only be one at a time, and you can change it whenever you need.
DNS target: the value the platform generates when you register a custom domain. Your domain must point to that value through a CNAME record (or an ALIAS/ANAME record, in the case of a root domain).

Before you start

Keep these points in mind before starting the setup:

Each instance supports only one custom domain. To register a different one, you must first delete the existing one.
The domain you want to use must be validated as a corporate domain, with its exact name. If you want to use a subdomain (for example, cybersecurity.mycompany.com), you must validate that subdomain. Having the root domain (mycompany.com) validated does not enable its subdomains.
Two different DNS records are required: a TXT record to validate the corporate domain and a record that points the domain to the platform (CNAME for a subdomain, ALIAS or ANAME for a root domain).
Decide whether you will use a root domain or a subdomain, since the procedure changes:
- Subdomain: a DNS name that has a CNAME record cannot have any other record at the same time. For this reason, the subdomain's validation TXT record must be deleted before creating the CNAME.
- Root domain: CNAME records cannot be created on a root domain, so your DNS provider must support ALIAS or ANAME records. These records coexist with the domain's other records, so the validation TXT record is kept. Some providers, such as GoDaddy, do not offer ALIAS or ANAME for the root domain: in that case, the recommended option is to use a subdomain.

If you do not manage your organization's DNS, ask your IT team to create the records and share this article with them.

Where to set it up

Go to Configuration > Organization > Corporate Domains. The corporate domains section is at the top, and the Custom domains section is at the bottom.

Step 1: Validate the domain as a corporate domain

In the Corporate Domains section, add the exact domain you want to use as a custom domain.
Copy the validation code shown by the platform. It starts with smartfense-domain-verification= and is unique to each domain added.
In your DNS provider, create a TXT record with these values:
- Type: TXT.
- Name / Host: depends on the domain to validate:
  - If it is a subdomain, enter only the subdomain part. For example, for cybersecurity.mycompany.com, enter cybersecurity.
  - If it is a root domain, depending on the provider, enter @ or leave the field empty.
- Value: the validation code copied in the previous step.
- TTL: the default value.
Wait for the change to propagate and validate the domain from the platform.

For full details, see the guide: How to validate a domain in SMARTFENSE.

In providers such as GoDaddy, Namecheap, or Cloudflare, the Host field automatically appends the domain. If you enter @ for a subdomain, the record is created on the root domain and the validation fails. If you enter the full name, the record may end up duplicated (for example, cybersecurity.mycompany.com.mycompany.com).

Step 2: Register the custom domain

In the Custom domains section, click the New custom domain button.
In the Domain field, select the corporate domain validated in step 1. The list only shows validated domains that have not yet been registered as custom domains.
Click Register.

The platform generates a DNS target for that domain and adds it to the Custom domains table, with the status Registered. Copy that value for the next step.

If you do not have any validated corporate domains available, when you click New custom domain the platform shows the notice: "Important: You do not have any validated corporate domains available. Add and validate a corporate domain before registering a custom domain."

Step 3: Point the domain to the platform

The procedure depends on whether the custom domain is a subdomain or a root domain.

If it is a subdomain (for example, cybersecurity.mycompany.com)

In your DNS provider, delete the SMARTFENSE validation TXT record created in step 1 for that subdomain (the one that starts with smartfense-domain-verification=).
Create a CNAME record with these values:
- Type: CNAME.
- Name / Host: the same one used in step 1 (for example, cybersecurity).
- Value / Points to: the DNS target shown in the Custom domains table.
- TTL: the default value.

When you delete the TXT record, the periodic domain check will mark the subdomain as Not validated in the Corporate Domains section after 7 days. This is expected and does not affect the custom domain already registered, which keeps working normally.

If it is a root domain (for example, mycompany.com)

Before continuing, confirm that your DNS provider offers ALIAS or ANAME records for the root domain. GoDaddy, for example, does not offer them; in that case, use a subdomain.

Do not delete the validation TXT record. The root domain must remain validated.
Create an ALIAS or ANAME record with these values:
- Type: ALIAS or ANAME, depending on the name your provider uses.
- Name / Host: @ or leave the field empty, depending on the provider.
- Value / Points to: the DNS target shown in the Custom domains table.
- TTL: the default value.

Do not modify or delete other existing records on the root domain, such as mail records (MX) or TXT records for other services.

If you use Cloudflare, set the record to DNS only (gray cloud), without the proxy. With the proxy enabled, the platform cannot detect the record.

Step 4: Check propagation and wait for the certificate to be issued

Before setting the domain as primary, two conditions must be met: the DNS record must be propagated and the domain's security certificate (HTTPS) must be issued. This is because, when you click Set as primary, the platform connects over HTTPS through the new domain to confirm it reaches your instance.

Check the record's propagation

DNS changes can take from a few minutes to several hours to propagate. To check propagation:

Go to a DNS propagation checker. You can find several free options by searching for "DNS propagation checker" in your browser.
Enter the full domain (for example, cybersecurity.mycompany.com) and select the record type:
- CNAME if it is a subdomain. The result must show the DNS target indicated by the platform.
- A if it is a root domain with ALIAS or ANAME. These records are not shown as such in public lookups: the result must show the same IP addresses returned by the DNS target when you look it up with type A.
Run the lookup.
Confirm that most servers return the expected result.

Always look up the full name of the domain you are going to use. If you look up the root domain when you set up a subdomain, you will see other records and the result will not be representative.

Wait for the certificate to be issued

The security certificate is requested automatically once the record points to the platform. Issuing it can take up to one hour. Wait that long before continuing with step 5.

Step 5: Set the domain as primary

In the Custom domains table, click Set as primary on the domain's row.
The platform shows the Set domain as primary dialog. Before applying the change, it checks over HTTPS that the domain already points correctly to your instance.
If your instance has integrations that depend on the primary domain, the dialog shows a warning. In that case, click Accept only after registering the new address with the corresponding provider.

From that moment on, the links generated by the platform start using the new primary domain.

Integrations affected by changing the primary domain

Some integrations use redirect addresses built from the primary domain. When you change it, the platform will use the new domain in those addresses, so you must register them in the corresponding provider's configuration; otherwise, sign-in or those integrations may stop working. The affected integrations are:

Single sign-on (SSO) with Microsoft Entra ID, Google, Auth0, Okta, Keycloak, or SAML.
Microsoft Teams app.
User import from Google.
Google custom mail server.
Vanta.

Other integrations, such as the phishing report button or user import from Microsoft Entra ID, are not affected by changing the primary domain.

Updating the redirect URI in Microsoft Entra ID

If your instance uses Microsoft Entra ID for authentication (single sign-on), changing the primary domain directly affects that integration. If you only use it to import users, you do not need to follow these steps. The redirect URI registered in Azure is built from the primary domain and stops working as soon as the change is applied.

The redirect URI follows this format:

https://<new-domain>/complete/azuread-oauth2/

Before confirming the domain change in SMARTFENSE, follow these steps in the Azure portal:

Sign in to the Microsoft Azure portal and open the application registered for SMARTFENSE.
Go to Overview and select the Redirect URIs option.
Add the new URI built with the new domain as a reply URL.
Click Save.

Complete these steps before clicking Accept in the SMARTFENSE confirmation dialog. If you confirm the change without updating the URI, users will not be able to sign in through Entra ID.

For more information about setting up this integration, see Step 2 in the article: How to import users and groups from Microsoft Entra ID.

Custom domains table

For each domain, the table shows the columns Domain, DNS target, Status (Registered or Primary), and Actions (Set as primary, Delete). The standard domain always appears in the table, without a DNS target, and cannot be deleted. When it is not the primary domain, it has the Set as primary action, which lets you go back to using it.

Troubleshooting

When validating the corporate domain, the message "It was not possible to validate the domain" appears. The platform cannot find the validation TXT record on the exact domain name. The technical details in the message may vary depending on the case, but the cause to check is the same. Make sure the TXT record was created on that name and not on the root domain: for a subdomain, the Host field must contain only the subdomain part, without @. Check it with a DNS propagation checker by looking up the full domain with type TXT.

The DNS provider does not allow creating the CNAME record on a subdomain. The validation TXT record or another record with the same name probably still exists. Delete it and create the CNAME again.

The DNS provider does not allow creating the CNAME record on a root domain. This is expected: root domains do not support CNAME records. Use an ALIAS or ANAME record. If your provider does not offer them (for example, GoDaddy), use a subdomain as your custom domain.

When clicking Set as primary, the message "The domain does not point to the platform yet" appears. It may be due to one of these causes:

The record has not propagated yet or does not point to the correct DNS target. Check propagation as described in step 4 and make sure the value exactly matches the DNS target in the table.
The security certificate has not been issued yet. Wait up to one hour after the record points to the platform and try again.

If the record is correctly propagated and the error persists after one hour, contact Support to check the certificate status.

The subdomain appears as Not validated in Corporate Domains after setting up the CNAME. This is expected after deleting the subdomain's validation TXT record. It does not affect the custom domain. If the root domain appears as Not validated, make sure its validation TXT record has not been deleted.

Frequently asked questions

Does the standard domain stop working? No. It remains available at all times.

Can I register more than one custom domain? No. Each instance supports only one custom domain. If you try to register another one, the platform indicates that the maximum allowed has been reached. To register a different domain, first delete the existing one; if it is the primary domain, first set the standard domain as primary.

Do I need to keep the root domain validated if I use a subdomain as my custom domain? It is not required for the custom domain, but it is recommended. The platform uses validated corporate domains to recognize your organization from your users' email addresses, for example, in suspicious email reports.

How long does it take to be available? It depends on the DNS change propagation, which can take from a few minutes to several hours. Once the domain points to the platform, the security certificate (HTTPS) is issued automatically and can take up to one more hour. Only then can you set the domain as primary.

How do I go back to using the standard domain? Set the standard domain as primary from the table. If you also want to stop using a custom domain, delete it; it must no longer be the primary domain before you can do so.

Why can't I delete the primary domain? To prevent the platform from being left without a valid access address. Set another domain as primary and then you will be able to delete the previous one.

💡 Best practices

Decide first whether the domain to use is a root domain or a subdomain, since that determines the value of the Host field, the record type, and whether the validation TXT record must be deleted.
Validate as a corporate domain exactly the same domain that will be used as the custom domain.
Keep your organization's root domain validated, even if the custom domain is a subdomain.
Check the propagation of the CNAME or ALIAS/ANAME record and wait up to one hour for the certificate to be issued before setting the domain as primary.
Register the new address with the single sign-on providers and the other affected integrations before confirming the primary domain change.
Inform users about the change of access address and keep the standard domain as a backup in case of any DNS issue.