Use a TLS/SSL certificate in your code in Azure App Service

In your application code, you can access the public or private certificates you add to App Service. Your app code may act as a client and access an external service that requires certificate authentication, or it may need to perform cryptographic tasks. This how-to guide shows how to use public or private certificates in your application code.

This approach to using certificates in your code makes use of the TLS functionality in App Service, which requires your app to be in Basic tier or above. If your app is in Free or Shared tier, you can include the certificate file in your app repository.

When you let App Service manage your TLS/SSL certificates, you can maintain the certificates and your application code separately and safeguard your sensitive data.

Prerequisites

To follow this how-to guide:

Find the thumbprint

In the Azure portal, from the left menu, select App Services > <app-name>.

From the left navigation of your app, select TLS/SSL settings, then select Private Key Certificates (.pfx) or Public Key Certificates (.cer).

Find the certificate you want to use and copy the thumbprint.

Copy the certificate thumbprint

Make the certificate accessible

To access a certificate in your app code, add its thumbprint to the WEBSITE_LOAD_CERTIFICATES app setting, by running the following command in the Cloud Shell:

az webapp config appsettings set --name <app-name> --resource-group <resource-group-name> --settings WEBSITE_LOAD_CERTIFICATES=<comma-separated-certificate-thumbprints>

To make all your certificates accessible, set the value to *.

Load certificate in Windows apps

The WEBSITE_LOAD_CERTIFICATES app setting makes the specified certificates accessible to your Windows hosted app in the Windows certificate store, in Current User\My.

In C# code, you access the certificate by the certificate thumbprint. The following code loads a certificate with the thumbprint E661583E8FABEF4C0BEF694CBC41C28FB81CD870.

using System;
using System.Linq;
using System.Security.Cryptography.X509Certificates;

string certThumbprint = "E661583E8FABEF4C0BEF694CBC41C28FB81CD870";
bool validOnly = false;

using (X509Store certStore = new X509Store(StoreName.My, StoreLocation.CurrentUser))
{
  certStore.Open(OpenFlags.ReadOnly);

  X509Certificate2Collection certCollection = certStore.Certificates.Find(
                              X509FindType.FindByThumbprint,
                              // Replace below with your certificate's thumbprint
                              certThumbprint,
                              validOnly);
  // Get the first cert with the thumbprint
  X509Certificate2 cert = certCollection.OfType<X509Certificate>().FirstOrDefault();

  if (cert is null)
      throw new Exception($"Certificate with thumbprint {certThumbprint} was not found");

  // Use certificate
  Console.WriteLine(cert.FriendlyName);
  
  // Consider to call Dispose() on the certificate after it's being used, avaliable in .NET 4.6 and later
}

In Java code, you access the certificate from the "Windows-MY" store using the Subject Common Name field (see Public key certificate). The following code shows how to load a private key certificate:

import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.bind.annotation.RequestMapping;
import java.security.KeyStore;
import java.security.cert.Certificate;
import java.security.PrivateKey;

...
KeyStore ks = KeyStore.getInstance("Windows-MY");
ks.load(null, null); 
Certificate cert = ks.getCertificate("<subject-cn>");
PrivateKey privKey = (PrivateKey) ks.getKey("<subject-cn>", ("<password>").toCharArray());

// Use the certificate and key
...

For languages that don't support or offer insufficient support for the Windows certificate store, see Load certificate from file.

Load certificate from file

If you need to load a certificate file that you upload manually, it's better to upload the certificate using FTPS instead of Git, for example. You should keep sensitive data like a private certificate out of source control.

Note

ASP.NET and ASP.NET Core on Windows must access the certificate store even if you load a certificate from a file. To load a certificate file in a Windows .NET app, load the current user profile with the following command in the Cloud Shell:

az webapp config appsettings set --name <app-name> --resource-group <resource-group-name> --settings WEBSITE_LOAD_USER_PROFILE=1

This approach to using certificates in your code makes use of the TLS functionality in App Service, which requires your app to be in Basic tier or above.

The following C# example loads a public certificate from a relative path in your app:

using System;
using System.IO;
using System.Security.Cryptography.X509Certificates;

...
var bytes = File.ReadAllBytes("~/<relative-path-to-cert-file>");
var cert = new X509Certificate2(bytes);

// Use the loaded certificate

To see how to load a TLS/SSL certificate from a file in Node.js, PHP, Python, Java, or Ruby, see the documentation for the respective language or web platform.

Load certificate in Linux/Windows containers

The WEBSITE_LOAD_CERTIFICATES app settings makes the specified certificates accessible to your Windows or Linux container apps (including built-in Linux containers) as files. The files are found under the following directories:

Container platform Public certificates Private certificates
Windows container C:\appservice\certificates\public C:\appservice\certificates\private
Linux container /var/ssl/certs /var/ssl/private

The certificate file names are the certificate thumbprints.

Note

App Service inject the certificate paths into Windows containers as the following environment variables WEBSITE_PRIVATE_CERTS_PATH, WEBSITE_INTERMEDIATE_CERTS_PATH, WEBSITE_PUBLIC_CERTS_PATH, and WEBSITE_ROOT_CERTS_PATH. It's better to reference the certificate path with the environment variables instead of hardcoding the certificate path, in case the certificate paths change in the future.

In addition, Windows Server Core containers load the certificates into the certificate store automatically, in LocalMachine\My. To load the certificates, follow the same pattern as Load certificate in Windows apps. For Windows Nano based containers, use the file paths provided above to Load the certificate directly from file.

The following C# code shows how to load a public certificate in a Linux app.

using System;
using System.IO;
using System.Security.Cryptography.X509Certificates;

...
var bytes = File.ReadAllBytes("/var/ssl/certs/<thumbprint>.der");
var cert = new X509Certificate2(bytes);

// Use the loaded certificate

To see how to load a TLS/SSL certificate from a file in Node.js, PHP, Python, Java, or Ruby, see the documentation for the respective language or web platform.

More resources