Como instalar um certificado SSL no Google App Engine

Este guia mostra como instalar um certificado SSL no Google App Engine, tanto pelo método moderno (um certificado gratuito gerenciado pelo Google que o App Engine provisiona e renova automaticamente para qualquer domínio personalizado) quanto pelo método legado (fazendo upload do seu próprio certificado de terceiros quando você precisa de uma CA específica, um certificado EV/OV ou um wildcard). O App Engine é uma plataforma PaaS totalmente gerenciada, então tudo isso acontece no Google Cloud Console ou através da CLI gcloud; você nunca precisa acessar um servidor.

Pré-requisitos

Antes de instalar um certificado, certifique-se de que os seguintes itens estejam prontos:

• Uma aplicação App Engine implementada (ambiente padrão ou flexível) em um projeto do Google Cloud.
• Um domínio registrado sob seu controle, com acesso aos seus registros DNS.
• O domínio verificado para sua conta Google através do Google Search Console ou Webmaster Central (o App Engine lê a propriedade verificada a partir daí).
• A CLI gcloud instalada e autenticada, caso prefira a linha de comando em vez do Console.
• O papel de Owner, Editor ou App Engine Admin no projeto.

Domínios personalizados e SSL no App Engine funcionam nesta ordem: verifique o domínio, mapeie-o para sua aplicação, aponte o DNS para o App Engine e, então, deixe o Google provisionar um certificado gerenciado ou faça o upload do seu próprio.

Opção 1: SSL gratuito gerenciado pelo Google (recomendado)

Os certificados gerenciados pelo Google são gratuitos, provisionados automaticamente através do Let’s Encrypt e renovados automaticamente enquanto o domínio permanecer mapeado. Esta é a opção padrão para qualquer novo domínio personalizado no App Engine e é a escolha correta para a grande maioria dos sites. Os certificados gerenciados não suportam wildcards: cada nome de host (por exemplo, example.com e www.example.com) é coberto por seu próprio certificado.

Passo 1: Verifique a propriedade do seu domínio

No seu navegador, faça login no Google Search Console com a mesma conta Google que possui o projeto Cloud, adicione seu domínio como propriedade e conclua um dos métodos de verificação (o registro DNS TXT é o mais confiável). O App Engine não permitirá que você mapeie um domínio que você não verificou.

Passo 2: Mapeie o domínio personalizado no Console

• Abra o Google Cloud Console e selecione seu projeto.
• No menu de Navegação, escolha App Engine > Settings.
• Abra a aba Custom Domains e clique em Add a custom domain.
• Escolha o domínio verificado no menu suspenso e, então, insira os subdomínios que deseja servir (normalmente o domínio raiz example.com e www.example.com).
• Clique em Save mappings e, então, siga as instruções na tela para adicionar os registros A, AAAA e CNAME sugeridos junto ao seu provedor de DNS.

Para fazer o mesmo pela linha de comando, execute:

gcloud app domain-mappings create www.example.com --project=YOUR_PROJECT_ID
gcloud app domain-mappings create example.com --project=YOUR_PROJECT_ID

Passo 3: Espere pelo certificado gerenciado

Assim que o DNS tiver se propagado, o App Engine solicita automaticamente um certificado Let’s Encrypt para cada nome de host mapeado. O provisionamento geralmente é rápido, mas a propagação do DNS pode levar até 24 horas. Verifique o status com:

gcloud app domain-mappings list --project=YOUR_PROJECT_ID

Cada mapeamento mostra um estado SSL de MANAGED_CERTIFICATE_STATUS: OK quando o certificado está ativo. Enquanto estiver sendo emitido, você verá PROVISIONING ou PENDING_DNS; isso geralmente se resolve automaticamente assim que os registros DNS apontarem para os IPs do Google.

Passo 4: Force o HTTPS para os visitantes (ambiente padrão)

No App Engine padrão, redirecione todas as solicitações para HTTPS adicionando secure: always a cada handler no app.yaml:

handlers:
- url: /.*
  script: auto
  secure: always
  redirect_http_response_code: 301

Implemente a alteração com gcloud app deploy. No ambiente flexível, trate o redirecionamento de HTTP para HTTPS no nível da aplicação ou do load balancer.

Opção 2: Faça upload do seu próprio certificado SSL de terceiros

Escolha este caminho quando precisar de um certificado wildcard, um certificado OV ou EV de uma Autoridade Certificadora específica, ou um certificado já emitido para o seu domínio. O App Engine aceita um único arquivo PEM contendo o certificado folha e quaisquer certificados intermediários, além de uma chave privada RSA codificada em PEM não criptografada. É permitido um total de até cinco certificados no arquivo PEM enviado (um certificado folha mais até quatro intermediários), e os certificados enviados podem ser reutilizados entre projetos na mesma organização Cloud.

Passo 1: Gere o CSR e solicite o certificado

Se você já gerou seu CSR e recebeu o certificado emitido pela sua CA, avance para o Passo 2.

Um CSR (Certificate Signing Request) é um bloco de texto codificado contendo seus dados de contato e domínio, que a CA usa para verificar e assinar o seu certificado. Você tem duas formas de criar um:

• Use o nosso Gerador de CSR para produzir o CSR e a chave privada no seu navegador.
• Gere-o localmente com OpenSSL; consulte como gerar um CSR no Google App Engine.

Envie o CSR (incluindo os marcadores —–BEGIN CERTIFICATE REQUEST—– e —–END CERTIFICATE REQUEST—–) para a CA durante o seu pedido. Guarde a chave privada correspondente em um local seguro; você precisará dela durante a instalação.

Passo 2: Combine o certificado e a cadeia em um único PEM

Se a CA entregou arquivos separados (o seu certificado do servidor mais um ou mais intermediários), concatene-os na ordem correta (primeiro o seu certificado, depois os intermediários). Abra um terminal na pasta que contém os arquivos e execute:

cat yourdomain.crt intermediate.crt > concat.crt

No Windows PowerShell, o equivalente é:

Get-Content yourdomain.crt, intermediate.crt | Set-Content concat.crt

O resultado é um arquivo de certificado codificado em PEM com a cadeia completa. Se também precisar converter formatos (por exemplo, de .pfx ou .p12 para PEM), use as nossas ferramentas SSL.

A chave privada deve ser uma chave RSA codificada em PEM não criptografada (por exemplo, myserver.key.pem). Se a sua estiver protegida por senha, remova a frase-senha com:

openssl rsa -in encrypted.key -out myserver.key.pem

Passo 3: Faça upload do certificado no Cloud Console

• Abra o Google Cloud Console e selecione seu projeto.
• Vá para menu de Navegação > App Engine > Settings e, então, abra a aba SSL Certificates.
• Clique em Upload a new certificate.
• Dê um Name ao certificado e, então, faça upload do concat.crt em PEM encoded X.509 public key certificate e do myserver.key.pem em Unencrypted PEM encoded RSA private key.
• Clique em Upload.

Passo 4: Atribua o certificado aos seus domínios

Na página de detalhes do certificado, selecione os domínios personalizados que deseja proteger com ele e, então, clique em Save. Se um domínio estiver usando atualmente um certificado gerenciado pelo Google, desative primeiro o modo gerenciado para ele; caso contrário, o upload não será aplicado.

Passo 5 (opcional): Faça upload e vincule pela CLI gcloud

A mesma operação pela linha de comando:

gcloud app ssl-certificates create 
  --display-name="example.com 2026" 
  --certificate=concat.crt 
  --private-key=myserver.key.pem

O comando retorna o novo ID do certificado. Vincule-o a um domínio mapeado e desative o modo gerenciado para esse mapeamento:

gcloud app domain-mappings update www.example.com 
  --certificate-id=CERT_ID 
  --certificate-management=manual

Para voltar a usar um certificado gratuito gerenciado pelo Google mais tarde, execute:

gcloud app domain-mappings update www.example.com 
  --certificate-management=automatic

Observações e limites

• Os certificados gerenciados não cobrem wildcards. Para *.example.com, faça upload de um certificado wildcard como na Opção 2.
• O Let’s Encrypt limita a emissão a 50 certificados gerenciados por semana por domínio base. O limite raramente é um problema, mas importa se você mapear muitos subdomínios ao mesmo tempo.
• Certificados enviados que não estão atribuídos a nenhum domínio são excluídos automaticamente após 30 dias.
• O máximo permitido é um certificado folha mais quatro intermediários em um único arquivo PEM enviado.
• Um certificado enviado fica visível em todos os projetos da sua organização Cloud, então um único wildcard pode ser reutilizado.

Teste a instalação do SSL

Abra o seu site via https:// e confirme o cadeado, e então execute uma verificação mais profunda com o nosso SSL Checker para obter um relatório instantâneo sobre o certificado, a cadeia e o suporte a protocolos.

Perguntas Frequentes