Tutorial: Map an existing custom domain to Azure Spring Apps

Note

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.

Prerequisites

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:

  • 20.99.204.111
  • 20.201.9.97
  • 20.74.97.5
  • 52.235.25.35
  • 20.194.10.0
  • 20.59.204.46
  • 104.214.186.86
  • 52.153.221.222
  • 52.160.137.39
  • 20.39.142.56
  • 20.199.190.222
  • 20.79.64.6
  • 20.211.128.96
  • 52.149.104.144
  • 20.197.121.209
  • 40.119.175.77
  • 20.108.108.22
  • 102.133.143.38
  • 52.226.244.150
  • 20.84.171.169
  • 20.93.48.108
  • 20.75.4.46
  • 20.78.29.213
  • 20.106.86.34
  • 20.193.151.132

Import certificate

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:

  1. Go to your key vault instance.

  2. In the left navigation pane, select Certificates.

  3. On the upper menu, select Generate/import.

  4. In the Create a certificate dialog under Method of certificate creation, select Import.

  5. Under Upload Certificate File, navigate to certificate location and select it.

  6. 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.

  7. Select Create.

    Import certificate 1

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:

  1. Go to your key vault instance.
  2. In the left navigation pane, select Access Policy.
  3. On the upper menu, select Add Access Policy.
  4. 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

Note

If you don't find the "Azure Spring Apps Resource Provider", search for "Azure Spring Cloud Resource Provider".

Screenshot of the Azure portal showing the Add Access Policy page for a key vault with Azure Spring Apps Domain-management selected from the Select a principal dropdown.

Import certificate to Azure Spring Apps

  1. Go to your Azure Spring Apps instance.

  2. From the left navigation pane, select TLS/SSL settings.

  3. Select Import key vault certificate.

    Screenshot of the Azure portal showing the TLS/SSL settings page for an Azure Spring Apps instance, with the Import key vault certificate button highlighted.

  4. When you have successfully imported your certificate, you'll see it in the list of Private Key Certificates.

    Private key certificate

Important

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.

Note

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:

DNS records page

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.

  1. Select Custom Domain.

  2. Then Add Custom Domain.

    Custom domain

  3. 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)

  4. Select Validate to enable the Add button.

  5. Select Add.

    Add custom domain

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.

Custom domain table

Note

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.

  1. Select your Certificate or import it.

  2. Select Save.

    Add SSL binding 1

After you successfully add SSL binding, the domain state will be secure: Healthy.

Add SSL binding 2

Enforce HTTPS

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.

Add SSL binding 3

When the operation is complete, navigate to any of the HTTPS URLs that point to your app. Note that HTTP URLs don't work.

Next steps