Set up a custom domain with free certificate in Azure Static Web Apps

By default, Azure Static Web Apps provides an auto-generated domain name. This article shows you how to map a custom domain name to an Azure Static Web Apps application.

Free SSL/TLS certificate

Azure Static Web Apps automatically provides a free SSL/TLS certificate for the auto-generated domain name and any custom domains you may add.

Walkthrough Video

Prerequisites

  • A purchased domain name
  • Access to the DNS configuration properties for your domain

DNS configuration options

There are a few different types of DNS configurations available for an application.

Scenario Example Domain validation method DNS record type
Add a root/apex domain mydomain.com, example.co.uk TXT ALIAS
Add a subdomain www.mydomain.com, foo.mydomain.com CNAME CNAME
Transfer a subdomain that is currently in use www.mydomain.com, foo.mydomain.com TXT CNAME

Add domain using CNAME record validation

CNAME record validation is the recommended way to add a custom domain, however, it only works for subdomains. If you would like to add a root domain (mydomain.com), please skip to Add domain using TXT record validation and then create an ALIAS record.

Important

If your subdomain is currently associated to a live site, and you aren't ready to transfer it to your static web app, use TXT record validation.

Enter your subdomain

  1. Open your static web app in the Azure portal.

  2. Select Custom domains in the menu.

  3. Select the Add button.

  4. In the Domain name field, enter your subdomain. Make sure that you enter it without any protocols. For example, www.mydomain.com.

    Add domain screen showing the custom subdomain in the input box

  5. Select the Next button to move to the Validate + configure step.

Configure CNAME with your domain provider

You'll need to configure a CNAME with your domain provider. Azure DNS is recommended, but these steps will work with any domain provider.

  1. Make sure CNAME is selected from the Hostname record type dropdown list.

  2. Copy the value in the Value field to your clipboard by selecting the copy icon.

    Validate + add screen showing CNAME selected and the copy icon outlined

  3. In a separate browser tab or window, open your Azure DNS Zone in the Azure portal.

  4. Select the + Record Set button.

  5. Create a new CNAME record set with the following values.

    Setting Value
    Name Your subdomain, such as www
    Type CNAME
    Alias Record Set No
    TTL Leave as default value
    TTL Unit Leave as default value
    Alias Paste the domain name from your clipboard
  6. Select OK.

    Azure DNS record set screen with name, type and alias fields highlighted

Validate CNAME

  1. Return to the Validate + add window in the Azure portal.

  2. Select the Add button.

Azure will attempt to validate the new CNAME with your domain provider. This may take a few minutes depending on your domain provider. If the validation fails immediately, wait a few minutes and try again before proceeding with any troubleshooting.

Now that the subdomain is configured, it may take several hours for the DNS provider to propagate the changes worldwide.

Add domain using TXT record validation

Azure uses a TXT record to validate that you own a domain. This is useful when you want to do one of the following...

  1. You want to configure a root domain (i.e. mydomain.com). Validating that you own the domain is required before you can create an ALIAS record that configures the root domain.

  2. You want to transfer a subdomain without downtime. The TXT record validation method allows you to validate that you own the domain, and for static web apps to go through the process of issuing you a certificate for that domain. You can then switch your domain to point to your static web app at any time with a CNAME record.

Enter your domain

  1. Open your static web app in the Azure portal.

  2. Select Custom domains in the menu.

  3. Select the Add button.

  4. In the Domain name field, enter either your root domain (i.e. mydomain.com) or your subdomain (i.e. www.mydomain.com).

    Add domain screen showing the custom domain in the input box

  5. Click on the Next button to move to the Validate + configure step.

Configure TXT record with your domain provider

You'll need to configure a TXT record with your domain provider. Azure DNS is recommended, but these steps will work with any domain provider.

  1. Ensure that the "Hostname record type" dropdown is set to "TXT".

  2. Select the Generate code button.

    Add custom screen with generate code button highlighted

    This action generates a unique code, which may take up to a minute to process.

  3. Select the clipboard icon next to the code to copy the value to your clipboard.

    Add custom domain screen with copy code button highlighted

  4. In a separate browser tab or window, open your Azure DNS Zone in the Azure portal.

  5. Select the + Record Set button.

  6. Create a new TXT record set with the following values.

    Setting Value
    Name @ for root domain, or enter the subdomain
    Type TXT
    TTL Leave as default value
    TTL Unit Leave as default value
    Value Paste the code from your clipboard
  7. Select OK.

    Azure DNS record set screen with name, type and value fields highlighted

Validate TXT record

  1. Return to the Validate + configure screen in the Azure portal.

During this step, Azure automatically verifies the TXT record with your DNS provider. Once the validation process is complete, a green indicator appears next to the added domain.

Green indicator showing TXT record has been validated

When the green indicator appears next to your domain in the Custom domains screen, you can complete the second step, which is to add an ALIAS record if you are adding a root domain or a CNAME record if you are adding a subdomain.

Create an ALIAS record

An ALIAS record maps one domain to another. It is used specifically for root domains (i.e. mydomain.com). In this section, you will create an ALIAS record that maps your root domain to the auto-generated URL of your static web app.

Important

Your Azure DNS Zone should be in the same subscription as your static web app.

  1. Open your domain's Azure DNS Zone in the Azure portal.

  2. Select the + Record Set button.

  3. Create a new A record set with the following values.

    Setting Value
    Name @
    Type A - Alias record to IPv4 Address
    Alias Record Set Yes
    Alias type Azure resource
    Subscription <Your Subscription>
    Azure resource <Your Static Web App>
    TTL Leave as default value
    TTL Unit Leave as default value
  4. Select OK.

    Azure DNS record set screen with name, type, alias and resource fields highlighted

Now that the root domain is configured, it may take several hours for the DNS provider to propagate the changes worldwide.

Next steps