Observabilidade por meio de logs de conexão - Amazon CloudFront
O que são logs de conexão?Habilitar logs de conexãoCampos de log de conexãoCódigos de erro de conexão

Observabilidade por meio de logs de conexão

Os logs de conexão do CloudFront oferecem evidências detalhadas dos eventos de autenticação TLS mútua, permitindo o monitoramento da validação de certificados, o acompanhamento das tentativas de conexão e a solução de problemas de autenticação.

O que são logs de conexão?

Os logs de conexão capturam informações detalhadas sobre handshakes do TLS e validação de certificados para distribuições habilitadas para TLS mútua. Diferentemente dos logs de acesso padrão que registram informações de solicitação HTTP, os logs de conexão se concentram especificamente em fatores da fase de estabelecimento da conexão TLS, como:

  • status da conexão (êxito/falha);

  • detalhes do certificado do cliente;

  • protocolo TLS e informações sobre cifras;

  • métricas de tempo de conexão;

  • dados personalizados das funções de conexão.

Esses logs oferecem ampla visibilidade dos eventos de autenticação baseados em certificados, o que ajuda a monitorar a segurança, solucionar problemas e atender aos requisitos de conformidade.

Habilitar logs de conexão

Os logs de conexão estão disponíveis somente para distribuições com a autenticação TLS mútua habilitada. É possível enviar logs de conexão a vários destinos, como CloudWatch Logs, Amazon Data Firehose e Amazon S3.

Pré-requisitos

Antes de habilitar os logs de conexão:

  • Configure a autenticação TLS mútua para a distribuição do CloudFront.

  • Habilite os logs de conexão para a distribuição do CloudFront.

  • Verifique se você tem as permissões necessárias para o destino de registro em log escolhido.

  • Para entrega entre contas, configure as políticas apropriadas do IAM.

Como habilitar os logs de conexão (console)

  1. Faça login no Console de gerenciamento da AWS e abra o console do CloudFront em https://console.aws.amazon.com/cloudfront/v4/home.

  2. Na lista de distribuição, selecione sua distribuição habilitada para mTLS.

  3. Escolha a guia Logging (Registrar em log).

  4. Escolha Adicionar.

  5. Selecione o serviço para receber os logs:

    • CloudWatch Logs

    • Firehose

    • Amazon S3

  6. Em Destino, selecione o recurso para o serviço escolhido:

    • Para o CloudWatch Logs, insira o nome do grupo de logs.

    • Para o Firehose, selecione Fluxo de entrega do Firehose.

    • Para o Amazon S3, insira o nome do bucket (adicionando, opcionalmente, um prefixo).

  7. (Opcional) Configurar definições adicionais:

    • Seleção de campo: selecione campos de log específicos a serem incluídos.

    • Formato de saída: escolha entre JSON, Plain, w3c, Raw ou Parquet (somente no S3).

    • Delimitador de campo: especifique como separar os campos de log.

  8. Selecione Save changes (Salvar alterações)

Como habilitar os logs de conexão (AWS CLI)

O seguinte exemplo mostra como habilitar os logs de conexão usando a API do CloudWatch:

# Step 1: Create a delivery source
aws logs put-delivery-source \
  --name "cf-mtls-connection-logs" \
  --resource-arn "arn:aws:cloudfront::123456789012:distribution/E1A2B3C4D5E6F7" \
  --log-type CONNECTION_LOGS

# Step 2: Create a delivery destination
aws logs put-delivery-destination \
  --name "s3-destination" \
  --delivery-destination-configuration \
  "destinationResourceArn=arn:aws:s3:::amzn-s3-demo-bucket1"

# Step 3: Create the delivery
aws logs create-delivery \
  --delivery-source-name "cf-mtls-connection-logs" \
  --delivery-destination-arn "arn:aws:logs:us-east-1:123456789012:delivery-destination:s3-destination"
nota

Ao usar a API do CloudWatch, é necessário especificar a região Leste dos EUA (Norte da Virgínia) (us-east-1), mesmo ao entregar logs a outras regiões.

Campos de log de conexão

Os logs de conexão incluem informações detalhadas sobre cada tentativa de conexão TLS:

Campo Descrição Exemplo
eventTimestamp Carimbo de data/hora no formato ISO 8601 indicando quando a conexão foi estabelecida ou falhou. 1731620046814
connectionId Identificador exclusivo para a conexão TLS. oLHiEKbQSn8lkvJfA3D4gFowK3_iZ0g4i5nMUjE1Akod8TuAzn5nzg==
connectionStatus

Status da tentativa de conexão mTLS.

 Success ou Failed
clientIp Endereço IP do cliente que está se conectando. 2001:0db8:85a3:0000:0000:8a2e:0370:7334
clientPort Porta usada pelo cliente. 12137
serverIp Endereço IP do servidor de borda do CloudFront. 99.84.71.136
distributionId ID da distribuição do CloudFront. E2DX1SLDPK0123
distributionTenantId ID do locatário da distribuição do CloudFront (quando aplicável). dt_2te1Ura9X3R2iCGNjW123
tlsProtocol Versão do protocolo TLS. TLSv1.3
tlsCipher Conjunto de cifras TLS usado para a conexão. TLS_AES_128_GCM_SHA256
tlsHandshakeDuration Duração do handshake do TLS em milissegundos. 153
tlsSni Valor da Indicação de Nome de Servidor do handshake do TLS. d111111abcdef8.cloudfront.net
clientLeafCertSerialNumber Número de série do certificado do cliente. 00:b1:43:ed:93:d2:d8:f3:9d
clientLeafCertSubject Campo de assunto do certificado do cliente. C=US, ST=WA, L=Seattle, O=Amazon.com, OU=CloudFront, CN=client.test.mtls.net
clientLeafCertIssuer Campo do emissor do certificado do cliente. C=US, ST=WA, L=Seattle, O=Amazon.com, OU=CloudFront, CN=test.mtls.net
clientLeafCertValidity Período de validade do certificado do cliente. NotBefore=2025-06-05T23:28:21Z;NotAfter=2125-05-12T23:28:21Z
connectionLogCustomData Dados personalizados adicionados por meio de funções de conexão. REVOKED:00:b1:43:ed:93:d2:d8:f3:9d

Códigos de erro de conexão

Failed:ClientCertMaxChainDepthExceeded
Failed:ClientCertMaxSizeExceeded
Failed:ClientCertUntrusted
Failed:ClientCertNotYetValid
Failed:ClientCertExpired
Failed:ClientCertTypeUnsupported
Failed:ClientCertInvalid
Failed:ClientCertIntentInvalid
Failed:ClientCertRejected
Failed:ClientCertMissing
Failed:TcpError
Failed:TcpTimeout
Failed:ConnectionFunctionError
Failed:ConnectionFunctionDenied
Failed:Internal
Failed:UnmappedConnectionError

Quando as conexões falham, o CloudFront registra códigos de motivo específicos:

Código Descrição
ClientCertMaxChainDepthExceeded Profundidade máxima da cadeia de certificados excedida.
ClientCertMaxSizeExceeded Tamanho máximo do certificado excedido.
ClientCertUntrusted O certificado não é confiável.
ClientCertNotYetValid O certificado ainda não é válido.
ClientCertExpired O certificado está vencido.
ClientCertTypeUnsupported O tipo de certificado não é compatível.
ClientCertInvalid O certificado é inválido.
ClientCertIntentInvalid A intenção do certificado é inválida.
ClientCertRejected Certificado rejeitado por validação personalizada.
ClientCertMissing O certificado não existe.
TcpError

Ocorreu um erro ao tentar estabelecer uma conexão.
TcpTimeout

Não foi possível estabelecer a conexão dentro do período de tempo limite.
ConnectionFunctionError

Uma exceção não detectada foi lançada durante a execução da função de conexão.
Interno

Ocorreu um erro interno de serviço.
UnmappedConnectionError

Ocorreu um erro que não se enquadra em nenhuma das outras categorias.