1# App Service Custom Domains and Managed TLS
2 
3## Prerequisites
4 
5| Requirement | Details |
6|------------|---------|
7| SKU tier | Basic (B1) or higher |
8| DNS access | Ability to create CNAME, A, and TXT records |
9| Domain ownership | Verified via TXT record |
10 
11## DNS Configuration
12 
13### Subdomain (CNAME)
14 
15| Record Type | Name | Value |
16|------------|------|-------|
17| CNAME | `www` | `<app-name>.azurewebsites.net` |
18| TXT | `asuid.www` | `<verification-id>` |
19 
20### Apex / Root Domain (A Record)
21 
22| Record Type | Name | Value |
23|------------|------|-------|
24| A | `@` | `<app-ip-address>` |
25| TXT | `asuid` | `<verification-id>` |
26 
27Get the verification ID and IP address:
28 
29```bash
30# Get verification ID
31az webapp show -n $APP -g $RG --query "customDomainVerificationId" -o tsv
32 
33# Get IP address (for A records)
34az webapp show -n $APP -g $RG --query "inboundIpAddress" -o tsv
35```
36 
37> 💡 **Tip:** Prefer CNAME records for subdomains. For apex domains, consider using an Azure DNS alias record to avoid hardcoding IP addresses that may change.
38 
39## Bind Custom Domain via CLI
40 
41```bash
42# Add custom domain
43az webapp config hostname add -n $APP -g $RG --hostname www.contoso.com
44 
45# Create managed certificate (free)
46az webapp config ssl create -n $APP -g $RG --hostname www.contoso.com
47 
48# Capture certificate thumbprint
49THUMBPRINT=$(az webapp config ssl list -n $APP -g $RG \
50  --query "[?contains(hostNames, 'www.contoso.com')].thumbprint | [0]" -o tsv)
51 
52# Bind the certificate
53az webapp config ssl bind -n $APP -g $RG \
54  --certificate-thumbprint $THUMBPRINT --ssl-type SNI
55```
56 
57## Bicep — Custom Domain with Managed Certificate
58 
59```bicep
60resource customDomain 'Microsoft.Web/sites/hostNameBindings@2022-09-01' = {
61  parent: webApp
62  name: 'www.contoso.com'
63  properties: {
64    siteName: webApp.name
65    hostNameType: 'Verified'
66    sslState: 'Disabled' // enable after cert is created
67  }
68}
69 
70resource managedCert 'Microsoft.Web/certificates@2022-09-01' = {
71  name: 'www.contoso.com'
72  location: location
73  properties: {
74    serverFarmId: appServicePlan.id
75    canonicalName: 'www.contoso.com'
76  }
77  dependsOn: [customDomain]
78}
79```
80 
81Then run a follow-up Bicep deployment to enable SNI and bind the managed certificate to the hostname:
82 
83```bicep
84resource managedCert 'Microsoft.Web/certificates@2022-09-01' existing = {
85  name: 'www.contoso.com'
86}
87 
88resource customDomainTlsBinding 'Microsoft.Web/sites/hostNameBindings@2022-09-01' = {
89  parent: webApp
90  name: 'www.contoso.com'
91  properties: {
92    siteName: webApp.name
93    hostNameType: 'Verified'
94    sslState: 'SniEnabled'
95    thumbprint: managedCert.properties.thumbprint
96  }
97}
98```
99 
100> ⚠️ **Warning:** Managed certificate creation requires the DNS records to be in place first. The hostname binding must exist before requesting the certificate.
101 
102## Terraform — Custom Domain with Managed Certificate
103 
104```hcl
105resource "azurerm_app_service_custom_hostname_binding" "domain" {
106  hostname            = "www.contoso.com"
107  app_service_name    = azurerm_linux_web_app.app.name
108  resource_group_name = azurerm_resource_group.rg.name
109}
110 
111resource "azurerm_app_service_managed_certificate" "cert" {
112  custom_hostname_binding_id = azurerm_app_service_custom_hostname_binding.domain.id
113}
114 
115resource "azurerm_app_service_certificate_binding" "binding" {
116  hostname_binding_id = azurerm_app_service_custom_hostname_binding.domain.id
117  certificate_id      = azurerm_app_service_managed_certificate.cert.id
118  ssl_state           = "SniEnabled"
119}
120```
121 
122## TLS Options
123 
124| Option | Cost | Renewal | Use Case |
125|--------|------|---------|----------|
126| App Service Managed Certificate | Free | Auto-renewed | Standard custom domains |
127| App Service Certificate (purchased) | ~$70/yr | Auto-renewed | Extended validation, wildcard |
128| Bring your own certificate | Varies | Manual | Enterprise PKI, specific CA |
129 
130### Enforce HTTPS Only
131 
132```bicep
133resource webApp 'Microsoft.Web/sites@2022-09-01' = {
134  name: appName
135  location: location
136  properties: {
137    httpsOnly: true
138    // ...
139  }
140}
141```
142 
143```hcl
144resource "azurerm_linux_web_app" "app" {
145  name                = var.app_name
146  # ...
147  https_only          = true
148}
149```
150 
151## Minimum TLS Version
152 
153```bash
154# Set minimum TLS version to 1.2
155az webapp config set -n $APP -g $RG --min-tls-version 1.2
156```
157 
158```bicep
159siteConfig: {
160  minTlsVersion: '1.2'
161}
162```
163 
164> ⚠️ **Warning:** TLS 1.0 and 1.1 are deprecated. Always set minimum TLS version to 1.2 for production workloads.
165 
166## Troubleshooting
167 
168| Issue | Cause | Fix |
169|-------|-------|-----|
170| Domain verification fails | Missing TXT record | Add `asuid` TXT record and wait for DNS propagation |
171| Certificate creation fails | DNS not yet propagated | Wait 5-15 min for propagation; verify with `nslookup` |
172| SSL binding error | SKU too low | Upgrade to Basic (B1) or higher |
173| Managed cert not renewing | DNS record changed | Verify CNAME/A record still points to the app |
174