Tutorial: Map an existing custom domain to Azure Spring Apps
Azure Spring Apps is the new name for the Azure Spring Cloud service. Although the service has a new name, you'll see the old name in some places for a while as we work to update assets such as screenshots, videos, and diagrams.
This article applies to: ✔️ Java ✔️ C#
This article applies to: ✔️ Standard tier ✔️ Enterprise tier
Domain Name Service (DNS) is a technique for storing network node names throughout a network. This tutorial maps a domain, such as www.contoso.com, using a CNAME record. It secures the custom domain with a certificate and shows how to enforce Transport Layer Security (TLS), also known as Secure Sockets Layer (SSL).
Certificates encrypt web traffic. These TLS/SSL certificates can be stored in Azure Key Vault.
- An application deployed to Azure Spring Apps (see Quickstart: Launch an existing application in Azure Spring Apps using the Azure portal, or use an existing app).
- A domain name with access to the DNS registry for domain provider such as GoDaddy.
- A private certificate (that is, your self-signed certificate) from a third-party provider. The certificate must match the domain.
- A deployed instance of Azure Key Vault
Key Vault private link considerations
The IP addresses for Azure Spring Apps management are not yet part of the Azure Trusted Microsoft services. Therefore, to enable Azure Spring Apps to load certificates from a Key Vault protected with private endpoint connections, you must add the following IP addresses to Azure Key Vault firewall:
Prepare your certificate file in PFX (optional)
Azure Key Vault support importing private certificate in PEM and PFX format. If the PEM file you obtained from your certificate provider doesn't work in section below: Save certificate in Key Vault, follow the steps here to generate a PFX for Azure Key Vault.
Merge intermediate certificates
If your certificate authority gives you multiple certificates in the certificate chain, you need to merge the certificates in order.
To do this, open each certificate you received in a text editor.
Create a file for the merged certificate, called mergedcertificate.crt. In a text editor, copy the content of each certificate into this file. The order of your certificates should follow the order in the certificate chain, beginning with your certificate and ending with the root certificate. It looks like the following example:
-----BEGIN CERTIFICATE----- <your entire Base64 encoded SSL certificate> -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- <The entire Base64 encoded intermediate certificate 1> -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- <The entire Base64 encoded intermediate certificate 2> -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- <The entire Base64 encoded root certificate> -----END CERTIFICATE-----
Export certificate to PFX
Export your merged TLS/SSL certificate with the private key that your certificate request was generated with.
If you generated your certificate request using OpenSSL, then you have created a private key file. To export your certificate to PFX, run the following command. Replace the placeholders <private-key-file> and <merged-certificate-file> with the paths to your private key and your merged certificate file.
openssl pkcs12 -export -out myserver.pfx -inkey <private-key-file> -in <merged-certificate-file>
When prompted, define an export password. You'll use this password when uploading your TLS/SSL certificate to Azure Key Vault later.
If you used IIS or Certreq.exe to generate your certificate request, install the certificate to your local machine, and then export the certificate to PFX.
Save certificate in Key Vault
The procedure to import a certificate requires the PEM or PFX encoded file to be on disk and you must have the private key.
To upload your certificate to key vault:
Go to your key vault instance.
In the left navigation pane, select Certificates.
On the upper menu, select Generate/import.
In the Create a certificate dialog under Method of certificate creation, select
Under Upload Certificate File, navigate to certificate location and select it.
Under Password, if you are uploading a password protected certificate file, provide that password here. Otherwise, leave it blank. Once the certificate file is successfully imported, key vault will remove that password.
Grant Azure Spring Apps access to your key vault
You need to grant Azure Spring Apps access to your key vault before you import certificate:
- Go to your key vault instance.
- In the left navigation pane, select Access Policy.
- On the upper menu, select Add Access Policy.
- Fill in the info, and select Add button, then Save access police.
|Secret permission||Certificate permission||Select principal|
|Get, List||Get, List||Azure Spring Apps Domain-Management|
If you don't find the "Azure Spring Apps Resource Provider", search for "Azure Spring Cloud Resource Provider".
Import certificate to Azure Spring Apps
To secure a custom domain with this certificate, you still need to bind the certificate to a specific domain. Follow the steps in this section: Add SSL Binding.
Add Custom Domain
You can use a CNAME record to map a custom DNS name to Azure Spring Apps.
The A record is not supported.
Create the CNAME record
Go to your DNS provider and add a CNAME record to map your domain to the <service_name>.azuremicroservices.io. Here <service_name> is the name of your Azure Spring Apps instance. We support wildcard domain and sub domain. After you add the CNAME, the DNS records page will resemble the following example:
Map your custom domain to Azure Spring Apps app
If you don't have an application in Azure Spring Apps, follow the instructions in Quickstart: Launch an existing application in Azure Spring Apps using the Azure portal.
Go to application page.
Select Custom Domain.
Then Add Custom Domain.
Type the fully qualified domain name for which you added a CNAME record, such as www.contoso.com. Make sure that Hostname record type is set to CNAME (<service_name>.azuremicroservices.io)
Select Validate to enable the Add button.
One app can have multiple domains, but one domain can only map to one app. When you've successfully mapped your custom domain to the app, you'll see it on the custom domain table.
A Not Secure label for your custom domain means that it's not yet bound to an SSL certificate. Any HTTPS request from a browser to your custom domain will receive an error or warning.
Add SSL binding
In the custom domain table, select Add ssl binding as shown in the previous figure.
Select your Certificate or import it.
After you successfully add SSL binding, the domain state will be secure: Healthy.
By default, anyone can still access your app using HTTP, but you can redirect all HTTP requests to the HTTPS port.
In your app page, in the left navigation, select Custom Domain. Then, set HTTPS Only, to True.
When the operation is complete, navigate to any of the HTTPS URLs that point to your app. Note that HTTP URLs don't work.
Submit and view feedback for