Azure Static Web Apps Custom Domain Configuration | Complete Guide

This comprehensive guide walks you through adding a custom domain to your Azure Static Web App, including DNS configuration, SSL certificate setup, and troubleshooting common issues.

🌐 Overview

Azure Static Web Apps provides free SSL certificates and global CDN distribution when you configure custom domains. This guide covers everything you need to know to set up your custom domain successfully.

What You’ll Learn

✅ How to add and verify custom domains in Azure Portal
✅ DNS configuration for popular domain registrars
✅ Automatic SSL certificate provisioning
✅ Domain verification methods
✅ Troubleshooting common configuration issues
✅ Best practices for domain management

Prerequisites

Before starting, ensure you have:

🔹 An active Azure subscription
🔹 An existing Azure Static Web App
🔹 A registered domain name
🔹 Access to your domain’s DNS settings

🚀 Step 1: Prepare Your Azure Static Web App

1.1 Verify Your Static Web App Status

Navigate to Azure Portal: Go to portal.azure.com
Find Your Static Web App: Search for your Static Web App resource
Check Deployment Status: Ensure your app is deployed and running

# Verify your app is accessible via the default URL
curl -I https://your-app-name.azurestaticapps.net

1.2 Note Your App Details

Record the following information:

Resource Group Name: my-static-app-rg
Static Web App Name: my-awesome-webapp
Default URL: https://my-awesome-webapp.azurestaticapps.net

🔧 Step 2: Add Custom Domain in Azure Portal

2.1 Navigate to Custom Domains

Open Azure Portal: Go to your Static Web App resource
Select Settings: In the left navigation panel
Choose Custom domains: Click on the Custom domains option

2.2 Add New Custom Domain

Click ’+ Add’: Select the Add custom domain button
Enter Domain Name: Type your custom domain (e.g., www.yoursite.com)
Choose Domain Type:
- Custom domain on Azure DNS: If using Azure DNS
- Custom domain on other DNS: For external DNS providers

2.3 Domain Configuration Options

Option A: Root Domain (yourdomain.com)

Domain name: yourdomain.com
Domain type: Custom domain on other DNS

Option B: Subdomain (www.yourdomain.com)

Domain name: www.yourdomain.com
Domain type: Custom domain on other DNS

Option C: Custom Subdomain (app.yourdomain.com)

Domain name: app.yourdomain.com
Domain type: Custom domain on other DNS

🌍 Step 3: Configure DNS Records

Azure will provide specific DNS records that you need to add to your domain registrar. The exact records depend on your configuration.

3.1 Required DNS Records

For Root Domain (yourdomain.com)

A Record:

Type: A
Name: @
Value: [IP Address provided by Azure]
TTL: 3600

TXT Record (for verification):

Type: TXT
Name: @
Value: [Verification string provided by Azure]
TTL: 3600

For Subdomain (www.yourdomain.com or app.yourdomain.com)

CNAME Record:

Type: CNAME
Name: www (or app)
Value: your-app-name.azurestaticapps.net
TTL: 3600

TXT Record (for verification):

Type: TXT
Name: _dnsauth.www (or _dnsauth.app)
Value: [Verification string provided by Azure]
TTL: 3600

3.2 DNS Configuration by Popular Registrars

GoDaddy Configuration

Log into GoDaddy: Visit godaddy.com and sign in
Manage DNS: Go to My Products → All Products and Services → DNS
Add Records:

# For subdomain setup
Type: CNAME
Host: www
Points to: your-app-name.azurestaticapps.net
TTL: 1 Hour

Type: TXT
Host: _dnsauth.www
TXT Value: [Azure verification string]
TTL: 1 Hour

Namecheap Configuration

Access Domain List: Log in and go to Domain List
Manage Domain: Click Manage next to your domain
Advanced DNS: Navigate to Advanced DNS tab
Add New Record:

# For subdomain setup
Type: CNAME Record
Host: www
Value: your-app-name.azurestaticapps.net
TTL: Automatic

Type: TXT Record
Host: _dnsauth.www
Value: [Azure verification string]
TTL: Automatic

Cloudflare Configuration

Open Cloudflare Dashboard: Go to dash.cloudflare.com
Select Your Domain: Click on your domain name
DNS Settings: Go to DNS → Records
Add Records:

# For subdomain setup
Type: CNAME
Name: www
Content: your-app-name.azurestaticapps.net
Proxy status: DNS only (gray cloud)
TTL: Auto

Type: TXT
Name: _dnsauth.www
Content: [Azure verification string]
TTL: Auto

Route 53 (AWS) Configuration

AWS Console: Navigate to Route 53 → Hosted zones
Select Domain: Click on your domain
Create Record Set:

{
  "Name": "www.yourdomain.com",
  "Type": "CNAME",
  "TTL": 300,
  "Value": "your-app-name.azurestaticapps.net"
}

{
  "Name": "_dnsauth.www.yourdomain.com",
  "Type": "TXT",
  "TTL": 300,
  "Value": "[Azure verification string]"
}

✅ Step 4: Domain Verification

4.1 Initiate Verification

Return to Azure Portal: Go back to your Static Web App → Custom domains
Click Validate: After adding DNS records, click the Validate button
Wait for Verification: This process can take up to 48 hours

4.2 Verification Status

Monitor the verification status:

Status Options:
✅ Validated - Domain is ready to use
⏳ Validating - Verification in progress
❌ Failed - DNS records need correction
⚠️ Pending - Waiting for DNS propagation

4.3 Check DNS Propagation

Use these tools to verify DNS propagation:

# Check DNS propagation globally
nslookup www.yourdomain.com 8.8.8.8

# Verify TXT record
nslookup -q=TXT _dnsauth.www.yourdomain.com

# Use online tools
# Visit: https://dnschecker.org
# Enter: www.yourdomain.com

🔒 Step 5: SSL Certificate Configuration

5.1 Automatic SSL Certificate

Azure automatically provisions SSL certificates for verified domains:

Certificate Authority: DigiCert
Validity Period: 3 months (auto-renewed)
Certificate Type: Domain Validated (DV)

5.2 SSL Certificate Status

Check certificate status in Azure Portal:

Certificate States:
✅ Ready - SSL certificate active
⏳ Requesting - Certificate being provisioned
❌ Failed - Certificate request failed
🔄 Renewing - Certificate being renewed

5.3 Force HTTPS Redirect

Enable HTTPS redirect in your Static Web App configuration:

staticwebapp.config.json:

{
  "routes": [
    {
      "route": "/*",
      "headers": {
        "Strict-Transport-Security": "max-age=31536000; includeSubDomains"
      }
    }
  ],
  "globalHeaders": {
    "content-security-policy": "default-src https: 'unsafe-eval' 'unsafe-inline'; object-src 'none'"
  }
}

🧪 Step 6: Testing and Verification

6.1 Domain Accessibility Tests

Test your custom domain configuration:

# Test HTTP to HTTPS redirect
curl -I http://www.yourdomain.com

# Test HTTPS response
curl -I https://www.yourdomain.com

# Test SSL certificate
openssl s_client -connect www.yourdomain.com:443 -servername www.yourdomain.com

6.2 Browser Testing

Open Browser: Navigate to https://www.yourdomain.com
Check SSL Certificate: Click the lock icon in address bar
Verify Certificate Details:
- Issued by: DigiCert
- Valid dates
- Subject Alternative Names

6.3 Performance Testing

Test global CDN performance:

# Test from different locations
curl -w "@curl-format.txt" -o /dev/null -s https://www.yourdomain.com

# Create curl-format.txt:
echo "time_namelookup: %{time_namelookup}s
time_connect: %{time_connect}s
time_appconnect: %{time_appconnect}s
time_pretransfer: %{time_pretransfer}s
time_redirect: %{time_redirect}s
time_starttransfer: %{time_starttransfer}s
time_total: %{time_total}s" > curl-format.txt

🔧 Step 7: Advanced Configuration

7.1 Multiple Domain Setup

Configure multiple domains for the same Static Web App:

Primary Domain: www.yourdomain.com
Additional Domains:
- yourdomain.com (redirect to www)
- app.yourdomain.com
- staging.yourdomain.com

7.2 Subdomain Routing

Configure different subdomains for different environments:

staticwebapp.config.json:

{
  "routes": [
    {
      "route": "/api/*",
      "allowedRoles": ["authenticated"]
    },
    {
      "route": "/*",
      "serve": "/index.html",
      "statusCode": 200
    }
  ],
  "responseOverrides": {
    "404": {
      "rewrite": "/404.html",
      "statusCode": 404
    }
  }
}

7.3 Environment-Specific Domains

Configure different domains for different environments:

# Production
az staticwebapp hostname set \
  --name my-production-app \
  --hostname www.yourdomain.com

# Staging
az staticwebapp hostname set \
  --name my-staging-app \
  --hostname staging.yourdomain.com

🔍 Troubleshooting

Common Issues and Solutions

Issue 1: DNS Propagation Delays

Symptoms:

Domain verification fails
DNS changes not reflected globally

Solutions:

# Check TTL values
dig www.yourdomain.com

# Wait for global propagation (up to 48 hours)
# Use lower TTL values (300-3600 seconds)

# Verify with multiple DNS servers
nslookup www.yourdomain.com 8.8.8.8
nslookup www.yourdomain.com 1.1.1.1

Issue 2: SSL Certificate Provisioning Fails

Symptoms:

Certificate status shows “Failed”
HTTPS not working after domain verification

Solutions:

Verify DNS Records: Ensure CNAME/A records are correct
Check Domain Validation: TXT records must be exactly as provided
Remove and Re-add: Delete domain and add again
Contact Support: For persistent issues

Issue 3: Redirect Loops

Symptoms:

Browser shows “Too many redirects” error
Site not accessible

Solutions:

// Check staticwebapp.config.json for conflicting redirects
{
  "routes": [
    {
      "route": "/old-path",
      "redirect": "/new-path",
      "statusCode": 301
    }
  ]
}

Issue 4: CNAME Record Conflicts

Symptoms:

Domain verification fails with CNAME conflicts
Multiple CNAME records for same subdomain

Solutions:

Remove Conflicting Records: Delete existing CNAME records
Use Correct Format: Ensure CNAME points to your-app.azurestaticapps.net
Check Subdomain: Verify you’re configuring the right subdomain

Debug Commands

# Check DNS resolution
dig +trace www.yourdomain.com

# Test SSL certificate
echo | openssl s_client -connect www.yourdomain.com:443 2>/dev/null | openssl x509 -noout -dates

# Verify HTTP headers
curl -I https://www.yourdomain.com

# Check Azure CLI status
az staticwebapp show --name my-app --resource-group my-rg

📊 Best Practices

Security Best Practices

Enable HSTS: Add Strict-Transport-Security headers
Use Content Security Policy: Implement CSP headers
Regular Certificate Monitoring: Monitor SSL certificate expiration
DNS Security: Use DNSSEC if supported by registrar

Performance Optimization

Use CDN-Friendly TTL: Set appropriate TTL values (3600-86400 seconds)
Minimize DNS Lookups: Reduce number of subdomains
Enable Compression: Configure gzip/brotli compression
Optimize Images: Use WebP format and responsive images

Monitoring and Maintenance

Set Up Alerts: Monitor domain and certificate status
Regular Testing: Perform monthly accessibility tests
Update Documentation: Keep DNS configurations documented
Backup Configurations: Document all DNS settings

📈 Monitoring and Analytics

Domain Performance Monitoring

# Create monitoring script
#!/bin/bash
DOMAIN="www.yourdomain.com"
RESPONSE_TIME=$(curl -w "%{time_total}" -o /dev/null -s https://$DOMAIN)
STATUS_CODE=$(curl -w "%{http_code}" -o /dev/null -s https://$DOMAIN)

echo "Domain: $DOMAIN"
echo "Response Time: ${RESPONSE_TIME}s"
echo "Status Code: $STATUS_CODE"

if [ $STATUS_CODE -eq 200 ]; then
    echo "✅ Domain is healthy"
else
    echo "❌ Domain issue detected"
fi

SSL Certificate Monitoring

# Check certificate expiration
echo | openssl s_client -servername $DOMAIN -connect $DOMAIN:443 2>/dev/null | openssl x509 -noout -dates

🎯 Summary

Configuration Checklist

Azure Static Web App deployed and running
Custom domain added in Azure Portal
DNS records configured at registrar
Domain verification completed
SSL certificate provisioned
HTTPS redirect enabled
Domain accessibility tested
Performance optimized
Monitoring configured

Key Takeaways

DNS Propagation: Allow up to 48 hours for global DNS propagation
Certificate Automation: Azure handles SSL certificate provisioning automatically
Multiple Domains: You can configure multiple custom domains per Static Web App
Global CDN: Custom domains benefit from Azure’s global CDN network
Free SSL: SSL certificates are provided free with custom domains

Next Steps

After successful domain configuration:

Configure Analytics: Set up Application Insights or Google Analytics
Implement Monitoring: Set up uptime and performance monitoring
Optimize Performance: Configure caching and compression
Plan Scaling: Consider multiple environments and CI/CD integration

📞 Support and Resources

Official Documentation

Useful Tools

DNS Checker - Check DNS propagation
SSL Server Test - Test SSL configuration
Azure Status - Check Azure service status

Community Resources

Need help? Check the troubleshooting section above or reach out to the Azure community for support!