Sobre o certificado de CA raiz da Apigee e a rotação

Esta página se aplica à Apigee, mas não à Apigee híbrida.

Confira a documentação da Apigee Edge.

Esta página descreve o certificado da autoridade certificadora raiz (CA) da Apigee que protege as conexões TLS com o ambiente de execução da Apigee e explica o processo de rotação. Ele também lista os padrões de acesso afetados por uma rotação e as etapas que você precisa seguir para preparar seus aplicativos.

Sobre o certificado de CA raiz

Cada organização da Apigee tem um certificado de CA raiz gerenciado pelo Google que emite o certificado do servidor usado pelo ingresso do ambiente de execução da Apigee para término de TLS. Quando um cliente abre uma conexão HTTPS com uma instância do Apigee, o servidor apresenta um certificado que se encadeia a essa CA raiz. Os clientes que validam o certificado do servidor precisam confiar na CA raiz, de forma implícita (quando o tráfego flui por um balanceador de carga gerenciado pelo cliente que encerra o TLS) ou explícita (quando o cliente se conecta diretamente ao ambiente de execução da Apigee).

O certificado de CA raiz é exposto na resposta da API organizations.get no campo caCertificates[]. O campo é uma matriz porque, durante uma rotação, os certificados da CA raiz atual e futura são retornados ao mesmo tempo para que os clientes possam confiar em ambos antes da transição.

Por que o certificado de CA raiz é alternado

O certificado de CA raiz da Apigee tem um período de validade longo, mas finito (normalmente 10 anos). Ele é alternado antes de expirar para que:

  • O certificado que protege o ambiente de execução da Apigee nunca expira enquanto está em uso.
  • Os canais de comunicação interna entre os componentes da Apigee continuam funcionando sem interrupção.

A rotação é uma operação rotineira e planejada. A Apigee executa em uma programação controlada pelo Google Cloud . Você não inicia a rotação, e ela não muda, por si só, o endpoint de ambiente de execução da Apigee nem a superfície da API Apigee.

Etapas e cronograma da rotação

A Apigee faz a rotação do certificado de CA raiz em quatro etapas. Cada etapa é gradual: ela é aplicada região por região na sua organização e leva tempo para ser concluída. A tabela abaixo descreve o efeito visível ao cliente de cada etapa e o tempo típico em que ela começa, medido em relação à data de validade da CA raiz atual.

Fase Período típico O que há em caCertificates[] O que acontece
1. Novo certificado publicado Cerca de um ano antes da expiração do certificado atual Atual e novo (ambos) O Apigee gera o novo certificado de CA raiz e o adiciona ao truststore de todos os componentes de propriedade do Apigee. O novo certificado também aparece na resposta organizations.get para que você possa buscá-lo e prepará-lo. O tempo de execução da Apigee continua apresentando um certificado de servidor assinado pela CA raiz atual. Portanto, os clientes atuais ainda não são afetados. A Apigee envia uma notificação ao cliente quando essa etapa começa.
2. Transição do certificado de folha Cerca de 60 dias antes da expiração do certificado atual Atual e novo (ambos) O ambiente de execução da Apigee começa a apresentar um novo certificado de servidor (folha) assinado pela nova CA raiz. Os clientes que confiam apenas na CA raiz atual não passam na validação de TLS depois que essa etapa é concluída na região deles. Os clientes que confiam nos dois certificados (ou apenas no novo) continuam funcionando. A Apigee envia uma notificação ao cliente quando essa etapa começa.
3. Certificado antigo removido Cerca de 30 dias antes da expiração do certificado atual Apenas novos A Apigee remove a AC raiz antiga dos repositórios de confiança internos e para de retorná-la de organizations.get. Os clientes que ainda confiam apenas na AC raiz antiga não podem se conectar. A Apigee envia uma notificação ao cliente quando essa etapa começa.
4. Rotação concluída Na data de vencimento original Apenas novos A Apigee exclui permanentemente a CA raiz antiga, e a rotação é concluída. A nova CA raiz é agora a única CA raiz, e um novo ciclo de aproximadamente 10 anos começa. A Apigee envia uma notificação ao cliente quando essa etapa é concluída.

Quem é afetado por uma rotação

Se uma rotação exige ação da sua parte depende de como os clientes acessam o ambiente de execução da Apigee:

Padrão de acesso É necessário fazer algo? Por quê?
Roteamento externo (MIG) com um balanceador de carga de aplicativo externo do Google Cloud Não O balanceador de carga externo encerra o TLS usando um certificado gerenciado por você. Os clientes confiam no seu certificado, não na CA raiz da Apigee. A rotação não afeta esses clientes.
Roteamento interno (VPC), opção 1 do TLS (balanceador de carga de aplicativo HTTPS interno) Não O balanceador de carga interno encerra o TLS usando um certificado gerenciado por você. Os clientes confiam no seu certificado, não na CA raiz da Apigee. A rotação não afeta esses clientes.
Roteamento interno (VPC), opção 2 de TLS (nome de domínio padrão interno totalmente qualificado) Sim Os clientes se conectam diretamente ao balanceador de carga interno gerenciado pelo Apigee e validam o certificado do servidor emitido pelo Apigee. Cada cliente precisa confiar na nova CA raiz antes da transição da rotação.
Conexão TCP direta ao IP de entrada da instância de execução (por exemplo, por um balanceador de carga TCP interno) Sim Os clientes validam o certificado do servidor emitido pela Apigee. Cada cliente precisa confiar na nova CA raiz antes da transição da rotação.
Opção não TLS (a flag curl -k ou qualquer cliente que ignore a validação do certificado) Não O cliente não valida o certificado do servidor, então a rotação não tem efeito funcional. Essa opção não é recomendada fora de ambientes de teste.

Como se preparar para uma rotação

Se você usa um dos padrões de acesso que exigem ação, siga estas etapas antes da data de transição da rotação que você recebe na notificação.

Etapa 1: descobrir as instâncias de ambiente de execução da Apigee

Liste as instâncias do ambiente de execução da Apigee na sua organização. Cada instância tem um IP de entrada dedicado, que é o host que os clientes de conexão direta acessam.

# Ensure $AUTH and $PROJECT_ID are set in your environment
curl -H "$AUTH" \
  https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/instances \
  | jq -r '.instances[] | "\(.name)\t\(.host)"'

Se os clientes se conectarem a um host diferente desses IPs (por exemplo, seu próprio nome DNS na frente de um balanceador de carga interno), use esse host em vez disso.

Etapa 2: buscar os certificados de CA raiz atuais e futuros

Leia o campo caCertificates[] de organizations.get. Durante uma rotação, essa matriz contém a CA raiz atual e a nova, cada uma codificada em base64:

curl -H "$AUTH" \
  https://apigee.googleapis.com/v1/organizations/$PROJECT_ID \
  | jq -r '.caCertificates[]' \
  | awk '/-----BEGIN/{i++}{print > ("ca_" i ".b64")}'

Decodifique cada entrada para o formato PEM e inspecione o período de validade para identificar o novo certificado:

for f in ca_*.b64; do
  base64 -d "$f" > "${f%.b64}.crt"
  echo "==> ${f%.b64}.crt"
  openssl x509 -in "${f%.b64}.crt" -noout -subject -issuer -dates
done

O certificado com a data notAfter mais recente é a nova CA raiz.

Etapa 3: adicione a nova CA raiz aos seus repositórios de confiança

Adicione o novo certificado de CA raiz a cada truststore de confiança do cliente que atualmente confia na CA raiz da Apigee. Mantenha a CA raiz atual até que a transição seja concluída para que as conexões continuem funcionando durante a janela de transição. Após a transição, você pode remover a CA raiz antiga dos seus truststores.

O procedimento exato depende do cliente. Os casos mais comuns incluem:

  • Adicionar o certificado ao truststore no nível do SO (por exemplo, /etc/ssl/certs/ em sistemas baseados em Debian seguido por update-ca-certificates).
  • Adicionar o certificado a um truststore gerenciado por um aplicativo (por exemplo, um keystore Java cacerts, um pacote Nginx ssl_trusted_certificate ou um pacote de confiança Envoy validation_context).
  • Adicionar o certificado a um Secret ou ConfigMap do Kubernetes montado nos pods de carga de trabalho.

Etapa 4: verificar se a conexão funciona com a nova CA raiz

Depois de preparar a nova CA raiz, verifique se uma solicitação HTTPS para o ambiente de execução da Apigee é bem-sucedida quando você confia apenas no novo certificado:

# Ensure $ENV_GROUP_HOSTNAME and $INTERNAL_LOAD_BALANCER_IP are set
curl -is -H "Host: $ENV_GROUP_HOSTNAME" \
  https://example.$PROJECT_ID.apigee.internal/PROXY_BASEPATH \
  --cacert NEW_CA_FILE \
  --resolve example.$PROJECT_ID.apigee.internal:443:$INTERNAL_LOAD_BALANCER_IP

Se esse comando for bem-sucedido, seu cliente estará pronto para a transição. Se isso falhar, o cliente ainda não confia na nova CA raiz. Consulte a etapa 3.

Exemplo: roteamento interno (VPC), opção 2 do TLS

Este exemplo demonstra as etapas de rotação para o padrão de acesso documentado em Roteamento interno (VPC), opção 2 do TLS, em que o cliente se conecta diretamente ao balanceador de carga interno da Apigee e valida o certificado autoassinado da Apigee. Esse é o padrão de acesso mais afetado por uma rotação.

Antes da transição:

  1. Consiga o IP do balanceador de carga interno da Apigee: 
    export INTERNAL_LOAD_BALANCER_IP=$(curl -H "$AUTH" \
  https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/instances -s \
  | jq -r '.instances[0].host')
  2. Busque as CAs raiz atuais e novas em arquivos separados e identifique a nova: 
    curl -H "$AUTH" \
  https://apigee.googleapis.com/v1/organizations/$PROJECT_ID \
  | jq -r '.caCertificates[]' \
  | awk '/-----BEGIN/{i++}{print > ("ca_" i ".b64")}'

for f in ca_*.b64; do
  base64 -d "$f" > "${f%.b64}.crt"
done

# Identify the new root CA (latest notAfter):
openssl x509 -in ca_1.crt -noout -dates
openssl x509 -in ca_2.crt -noout -dates
  3. Crie um keystore combinado que contenha a CA raiz atual e a nova e use-o para sua solicitação de teste: 
    cat ca_1.crt ca_2.crt > cacert-combined.crt

curl -is -H "Host: $ENV_GROUP_HOSTNAME" \
  https://example.$PROJECT_ID.apigee.internal/PROXY_BASEPATH \
  --cacert cacert-combined.crt \
  --resolve example.$PROJECT_ID.apigee.internal:443:$INTERNAL_LOAD_BALANCER_IP

    Se a solicitação for bem-sucedida, implante cacert-combined.crt como seu truststore do cliente. O truststore combinado continua validando o certificado atual hoje e vai validar o novo certificado após a migração.

Após a transição (normalmente em alguns dias após a data), confirme a rotação verificando se a conexão ainda é bem-sucedida quando você confia apenas no novo certificado:

curl -is -H "Host: $ENV_GROUP_HOSTNAME" \
  https://example.$PROJECT_ID.apigee.internal/PROXY_BASEPATH \
  --cacert NEW_CA_FILE \
  --resolve example.$PROJECT_ID.apigee.internal:443:$INTERNAL_LOAD_BALANCER_IP

Quando essa solicitação for concluída, você poderá remover a CA raiz antiga do seu repositório de confiança.

Notificações

A Apigee envia uma notificação aos proprietários do projeto e da organização do seu projeto Google Cloud no início de cada etapa de rotação. Cada notificação inclui o nome do estágio, a data em que ele será aplicado à sua organização e um link para esta página.

Notificação Ação recomendada para o cliente
1. Novo certificado publicado
(~1 ano antes da expiração)		 Extraia a nova CA raiz de caCertificates[] e adicione a cada keystore de confiança do cliente que atualmente confia na CA raiz do Apigee. Consulte Como se preparar para uma rotação.
2. Transição do certificado folha
(~60 dias antes do vencimento)		 Confirme se todos os seus clientes confiam na nova CA raiz antes que esta etapa seja aplicada à sua região. Depois dessa etapa, os clientes que confiam apenas na CA raiz antiga não poderão se conectar.
3. Certificado antigo retirado
(~30 dias antes do vencimento)		 Depois que essa etapa for aplicada a todas as regiões, você poderá remover com segurança a CA raiz antiga dos repositórios de confiança do cliente.
4. Rotação concluída
(na data de expiração original)		 Nenhuma ação é necessária. A AC raiz antiga foi excluída permanentemente, e a nova é a única AC raiz da sua organização.

Se você não receber notificações de rotação e usar um dos padrões de acesso listados em Quem é afetado por uma rotação, entre em contato com o suporte da Apigee para confirmar os destinatários das notificações da sua organização.

A seguir