Associar uma função de conexão do CloudFront

As funções de conexão do CloudFront permitem implementar uma lógica personalizada de validação de certificados durante handshakes do TLS, oferecendo extensões aos recursos integrados de autenticação mTLS.

O que são funções de conexão?

As funções de conexão são funções JavaScript executadas no handshake do TLS após a validação de certificados de cliente. O certificado de cliente validado é transmitido à função de conexão, momento em que a função de conexão pode determinar se deseja conceder acesso ou não. Para ter informações mais detalhadas sobre como funções de conexão, consulte Personalizar na borda com o CloudFront Functions.

Como as funções de conexão funcionam com a mTLS

Quando um cliente tenta estabelecer uma conexão mTLS com uma distribuição do CloudFront, ocorre a seguinte sequência de eventos:

As funções de conexão são invocadas tanto para o modo de verificação quanto para o modo opcional (quando os clientes apresentam certificados).

Solicitar um aumento de cota de função de conexão

Solicite um aumento de cota de função de conexão para sua Conta da AWS.

Depois que a solicitação for aprovada, você poderá criar uma função de conexão na sua conta e associá-la a uma ou mais distribuições ao usar a TLS mútua.

Criar uma função de conexão

É possível criar funções de conexão usando o console do CloudFront ou a AWS CLI.

Como criar uma função de conexão (console)

Como criar uma função de conexão (AWS CLI)

O seguinte exemplo mostra como criar uma função de conexão:

Escreva o código da função em um arquivo separado (por exemplo, code.js):

function connectionHandler(connection) {
  connection.allow();
}

aws cloudfront create-connection-function \
  --name "certificate-validator" \
  --connection-function-config '{
      "Comment": "Client certificate validation function",
      "Runtime": "cloudfront-js-2.0"
  }' \
  --connection-function-code fileb://code.js

Estrutura do código da função de conexão

As funções de conexão implementam uma função connectionHandler que recebe um objeto de conexão contendo informações de certificado e conexão. A função deve usar connection.allow() ou connection.deny() para tomar uma decisão sobre a conexão.

Exemplo de uma função de conexão básica

O seguinte exemplo mostra uma função de conexão simples que verifica o campo de assunto de certificados de cliente:

function connectionHandler(connection) {
    // Only process if a certificate was presented
    if (!connection.clientCertificate) {
        console.log("No certificate presented");
        connection.deny();
    }
    
    // Check the subject field for specific organization
    const subject = connection.clientCertificate.certificates.leaf.subject;
    if (!subject.includes("O=ExampleCorp")) {
        console.log("Certificate not from authorized organization");
       connection.deny();
    } else {
        // All checks passed
        console.log("Certificate validation passed");
        connection.allow();
    }
}

A especificação completa das propriedades do certificado do cliente disponíveis no objeto de conexão é apresentada aqui:

{
  "connectionId": "Fdb-Eb7L9gVn2cFakz7wWyBJIDAD4-oNO6g8r3vXDV132BtnIVtqDA==", // Unique identifier for this TLS connection
  "clientIp": "203.0.113.42", // IP address of the connecting client (IPv4 or IPv6)
  "clientCertificate": {
    "certificates": {
      "leaf": {
        "subject": "CN=client.example.com,O=Example Corp,C=US", // Distinguished Name (DN) of the certificate holder
        "issuer": "CN=Example Corp Intermediate CA,O=Example Corp,C=US", // Distinguished Name (DN) of the certificate authority that issued this certificate
        "serialNumber": "4a:3f:5c:92:d1:e8:7b:6c", // Unique serial number assigned by the issuing CA (hexadecimal)
        "validity": {
          "notBefore": "2024-01-15T00:00:00Z", // Certificate validity start date (ISO 8601 format)
          "notAfter": "2025-01-14T23:59:59Z"   // Certificate expiration date (ISO 8601 format)
        },
        "sha256Fingerprint": "a1b2c3d4e5f6...abc123def456", // SHA-256 hash of the certificate (64 hex characters)
      },
    },
  },
}

Associar uma função de conexão

Depois de criar uma função de conexão, é necessário publicá-la no estágio ATIVO e associá-la à distribuição.

Como publicar e associar uma função de conexão (console)

Alternativamente, as funções de conexão publicadas também podem ser associadas na página de detalhes da distribuição.

Como associar uma função de conexão (AWS CLI)

O seguinte exemplo mostra como associar uma função de conexão a uma distribuição:

// DistributionConfig:
{
   ...other settings,
    "ConnectionFunctionAssociation": {
        "Id": "cf_30c2CV2elHwCoInb3LtcaUJkZeD"
    }
}
                

Casos de uso de funções de conexão

As funções de conexão permitem vários casos de uso avançados de mTLS:

Próximas etapas

Após a associação de uma função de conexão a uma distribuição do CloudFront, é possível definir configurações opcionais para personalizar o comportamento da implementação de mTLS. Para ver instruções detalhadas sobre como definir configurações adicionais, como um modo opcional de validação de certificados de cliente, consulte Definir configurações adicionais.