Usar um certificado TLS/SSL no seu código no Serviço de Aplicativo do Azure

No código do aplicativo, você pode acessar os certificados públicos ou privados adicionados ao Serviço de Aplicativo. O código do aplicativo pode atuar como um cliente e acessar um serviço externo que requer autenticação de certificado ou pode precisar executar tarefas criptográficas. Este guia de instruções mostra como usar certificados públicos ou privados no código do aplicativo.

Essa abordagem de uso de certificados no código utiliza a funcionalidade de TLS no Serviço de Aplicativo, sendo necessário que o seu aplicativo esteja na camada Básica ou superior. Se seu aplicativo estiver em uma camada Gratuita ou Compartilhada, você poderá incluir o arquivo de certificado em seu repositório de aplicativos.

Ao permitir que o Serviço de Aplicativo gerencie os certificados TLS/SSL, é possível manter os certificados e o código do aplicativo separados e proteger seus dados confidenciais.

Pré-requisitos

Para seguir este guia de instruções, é necessário ter:

• Crie um aplicativo do Serviço de Aplicativo
• Adicione um certificado ao seu aplicativo Web

Ache a impressão digital

No portal do Azure, no menu à esquerda, selecione Serviços de Aplicativos><nome-do-aplicativo>.

Na navegação à esquerda do aplicativo, selecione Certificados e, em seguida, selecione Traga seus próprios certificados (.pfx) ou Certificados de chave pública (.cer).

Ache o certificado que você deseja utilizar e copie a impressão digital.

Tornar o certificado acessível

Para acessar um certificado em seu código do aplicativo, adicione sua impressão digital à configuração do aplicativo WEBSITE_LOAD_CERTIFICATES executando o seguinte comando no Cloud Shell:

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

Para disponibilizar todos os certificados, defina o valor como *.

Observação

Quando WEBSITE_LOAD_CERTIFICATES é definido como *, todos os certificados adicionados anteriormente ficam acessíveis ao código do aplicativo. Se você adicionar um certificado ao aplicativo mais tarde, reinicie o aplicativo para que o novo certificado fique acessível ao aplicativo. Para obter mais informações, confira Ao atualizar (renovar) um certificado.

Carregar o certificado em aplicativos do Windows

A configuração do aplicativo WEBSITE_LOAD_CERTIFICATES torna os certificados especificados acessíveis para seu aplicativo hospedado do Windows no repositório de certificados do Windows, no User\My atual.

No código C#, você acessa o certificado pela impressão digital do certificado. O código a seguir carrega um certificado com a impressão digital 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<X509Certificate2>().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, available in .NET 4.6 and later
}

No código Java, você acessa o certificado do repositório “Windows-MY” usando o campo nome comum da entidade (veja Certificado de chave pública). O código a seguir mostra como carregar um certificado de chave privada:

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

Para idiomas que não dão suporte ou oferecem suporte insuficiente para o repositório de certificados do Windows, veja Carregar certificado do arquivo.

Carregar certificado do arquivo

Se você precisar carregar um arquivo de certificado que é carregado manualmente, é melhor carregar o certificado usando FTPS em vez de Git, por exemplo. Você deve manter dados confidenciais como um certificado privado fora do controle do código-fonte.

Observação

ASP.NET e ASP.NET Core no Windows devem acessar o repositório de certificados mesmo se você carregar um certificado de um arquivo. Para carregar um arquivo de certificado em um aplicativo do Windows .NET, carregue o perfil do usuário atual com o seguinte comando no Cloud Shell:

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

Essa abordagem de uso de certificados no código utiliza a funcionalidade de TLS no Serviço de Aplicativo, sendo necessário que o seu aplicativo esteja na camada Básica ou superior.

O exemplo C# a seguir carrega um certificado público de um caminho relativo em seu aplicativo:

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

Para ver como carregar um certificado TLS/SSL de um arquivo em Node.js, PHP, Python ou Java, veja a documentação do respectivo idioma ou plataforma da Web.

Carregar o certificado em contêineres do Linux/Windows

A configuração do aplicativo WEBSITE_LOAD_CERTIFICATES torna os certificados especificados acessíveis aos seus contêineres personalizados do Windows ou do Linux (incluindo contêineres internos do Linux) como arquivos. Os arquivos são encontrados nos seguintes diretórios:

Plataforma de contêiner	Certificados públicos	Certificados privados
Contêiner do Windows	C:\appservice\certificates\public	C:\appservice\certificates\private
Contêiner do Linux	/var/ssl/certs	/var/ssl/private

Os nomes de arquivo de certificado são as impressões digitais do certificado.

Observação

O Serviço de Aplicativo injeta os caminhos de certificado em contêineres do Windows como as variáveis de ambiente a seguir WEBSITE_PRIVATE_CERTS_PATH, WEBSITE_INTERMEDIATE_CERTS_PATH, WEBSITE_PUBLIC_CERTS_PATH e WEBSITE_ROOT_CERTS_PATH. É melhor fazer referência ao caminho do certificado com as variáveis de ambiente em vez de codificar o caminho do certificado, caso os caminhos do certificado sejam alterados no futuro.

Além disso, os contêineres Windows Server Core e Windows Nano Server carregam os certificados no armazenamento de certificados automaticamente, em LocalMachine\My. Para carregar os certificados, siga o mesmo padrão que Carregar certificado em aplicativos do Windows. Para contêineres baseados no Windows Nano, use os caminhos de arquivo Carregar o certificado diretamente do arquivo.

Linux

O código C# a seguir mostra como carregar um certificado público em um aplicativo Linux.

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

O código C# a seguir mostra como carregar um certificado privado em um aplicativo Linux.

using System;
using System.IO;
using System.Security.Cryptography.X509Certificates;
...
var bytes = File.ReadAllBytes("/var/ssl/private/<thumbprint>.p12");
var cert = new X509Certificate2(bytes);

// Use the loaded certificate

Windows

O exemplo C# a seguir mostra como carregar um certificado público em um aplicativo .NET Framework em um contêiner Windows Server Core.

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

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

using (X509Store certStore = new X509Store(StoreName.My, StoreLocation.LocalMachine))
{
  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<X509Certificate2>().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, available in .NET 4.6 and later
}

O exemplo C# a seguir mostra como carregar um certificado público em um aplicativo .NET Core em um Windows Server Core ou Windows Nano Server Contêiner.

using System.Security.Cryptography.X509Certificates;

string Thumbprint = "C0CF730E216F5D690D1834446554DF5DC577A78B";

using X509Store store = new X509Store(StoreName.My, StoreLocation.LocalMachine);
{
    store.Open(OpenFlags.ReadOnly);
    
    // Get the first cert with the thumbprint
    var certificate = store.Certificates.OfType<X509Certificate2>()
        .First(c => c.Thumbprint == Thumbprint) ?? throw new Exception($"Certificate with thumbprint {Thumbprint} was not found");

    // Use certificate
    ViewData["certificateDetails"] = certificate.IssuerName.Name.ToString();
}

Para ver como carregar um certificado TLS/SSL de um arquivo em Node.js, PHP, Python ou Java, veja a documentação do respectivo idioma ou plataforma da Web.

Ao atualizar (renovar) um certificado

Quando você renova um certificado e o adiciona ao aplicativo, ele obtém uma nova impressão digital, que também precisa ficar acessível. O funcionamento disso depende do tipo de certificado.

Se você carregar manualmente o certificado público ou privado:

• Se você listar as impressões digitais explicitamente no WEBSITE_LOAD_CERTIFICATES, adicione a nova impressão digital à configuração de aplicativo.
• Se WEBSITE_LOAD_CERTIFICATES estiver definido como *, reinicie o aplicativo para que o novo certificado fique acessível.

Se você renovar um certificado no Key Vault, por exemplo, usando um certificado do Serviço de Aplicativo, a sincronização diária do Key Vault fará a atualização necessária automaticamente ao sincronizar o aplicativo com o certificado renovado.

• Se WEBSITE_LOAD_CERTIFICATES contiver a impressão digital antiga do certificado renovado, a sincronização diária atualizará automaticamente a impressão digital antiga para a nova impressão digital.
• Se WEBSITE_LOAD_CERTIFICATES for definido como *, a sincronização diária tornará o novo certificado acessível automaticamente.

Mais recursos

• Proteger um nome DNS personalizado com uma associação TLS/SSL no Serviço de Aplicativo do Azure
• Impor HTTPS
• Impor o TLS 1.1/1.2
• Perguntas frequentes: Certificados do Serviço de Aplicativo
• Referência de variáveis de ambiente e configurações de aplicativo